docs: add usage documentation

Author: hyiso

README.md

@@ -1 +1,48 @@
-Dart version commitlint - A tool to lint commit message.
+## commitlint
+
+> Dart version commitlint - A tool to lint commit messages.
+
+## Getting started
+
+commitlint helps your team adhere to a commit convention. By supporting pub-installed configurations it makes sharing of commit conventions easy.
+
+### Install
+
+```bash
+# Install and configure if needed
+dart pub add --dev commitlint_cli commitlint_config
+```
+
+### Configuration
+
+```bash
+# Configure commitlint to use conventional config
+echo "include: package:commitlint_config/commitlint.yaml" > commitlint.yaml
+```
+
+### Test
+
+```bash
+# Lint from stdin
+echo 'foo: bar' | commitlint --input
+⧗   input: foo: bar
+✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
+
+✖   found 1 problems, 0 warnings
+ⓘ   Get help: http://hyiso.github.io/commitlint/#/concepts-convensional-commits
+```
+
+```bash
+# Lint last commit from history
+commitlint --from=HEAD~1
+```
+
+?> To get the most out of `commitlint` you'll want to automate it in your project lifecycle. See our [Setup guide](./guides-setup.md) for next steps.
+
+## Documentation
+
+See [documention](https://hyiso.github.io/commitlint)
+
+- **Guides** - Common use cases explained in a step-by-step pace
+- **Concepts** - Overarching topics important to understand the use of `commitlint`
+- **Reference** - Mostly technical documentation

commitlint.yaml

@@ -1,4 +1,4 @@
-include: package:commitlint_config/commitlint.yaml
+include: ./packages/commitlint_config/lib/commitlint.yaml
 
 rules:
   scope-enum:

docs/.nojekyll

@@ -0,0 +1,46 @@
+## commitlint
+
+> Dart version commitlint - A tool to lint commit messages.
+
+## Getting started
+
+commitlint helps your team adhere to a commit convention. By supporting pub-installed configurations it makes sharing of commit conventions easy.
+
+### Install
+
+```bash
+# Install and configure if needed
+dart pub add --dev commitlint_cli commitlint_config
+```
+
+### Configuration
+
+```bash
+# Configure commitlint to use conventional config
+echo "include: package:commitlint_config/commitlint.yaml" > commitlint.yaml
+```
+
+### Test
+
+```bash
+# Lint from stdin
+echo 'foo: bar' | commitlint --input
+⧗   input: foo: bar
+✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
+
+✖   found 1 problems, 0 warnings
+ⓘ   Get help: http://hyiso.github.io/commitlint/#/concepts-convensional-commits
+```
+
+```bash
+# Lint last commit from history
+commitlint --from=HEAD~1
+```
+
+?> To get the most out of `commitlint` you'll want to automate it in your project lifecycle. See our [Setup guide](./guides-setup.md) for next steps.
+
+## Documentation
+
+- **Guides** - Common use cases explained in a step-by-step pace
+- **Concepts** - Overarching topics important to understand the use of `commitlint`
+- **Reference** - Mostly technical documentation

docs/README.md

@@ -0,0 +1,7 @@
+- Guides
+  - [Setup](guides-setup.md)
+- Concepts
+  - [Convensional commits](concepts-convensional-commits.md)
+  - [Shareable config](concepts-shareable-config.md)
+- References
+  - [Rules](references-rules.md)

docs/_sidebar.md

@@ -0,0 +1,26 @@
+# Concept: Convensional commits
+
+[Convensional commits](https://www.conventionalcommits.org/) allow your team to add more semantic meaning to your git history. This e.g. includes `type`, `scope` or `breaking changes`.
+
+With this additional information tools can derive useful human-readable information for releases of your project. Some examples are
+
+- Automated, rich changelogs
+- Automatic version bumps
+- Filter for test harnesses to run
+
+The most common convensional commits follow this pattern:
+
+```
+type(scope?): subject
+body?
+footer?
+```
+
+## Multiple scopes
+
+Commitlint supports multiple scopes.  
+Current delimiter options are:
+
+- "/"
+- "\\"
+- ","

docs/concepts-convensional-commits.md

@@ -0,0 +1,30 @@
+# Concept: Shareable configuration
+
+Most commonly shareable configuration is delivered as pub package exporting one or multi
+`.yaml` file(s) containing `rules` section. To use shared configuration you specify it as value for key `include`
+
+```yaml
+# commitlint.yaml
+include: package:commitlint_config/commitlint.yaml
+```
+
+This causes `commitlint` to pick up `commitlint_config/commitlint.yaml`. Make it available by installing it.
+
+```bash
+dart pub add --dev commitlint_config
+```
+
+The rules found in `commitlint_config/commitlint.yaml` are merged with the rules in `commitlint.yaml`, if any.
+
+This works recursively, enabling shareable configuration to extend on an indefinite chain of other shareable configurations.
+
+## Relative config
+
+You can also load local configuration by using a relative path to the file.
+
+> This must always start with a `.` (dot).
+
+```yaml
+# commitlint.yaml
+include: ./lints/commitlint.yaml
+```

docs/concepts-shareable-config.md

@@ -0,0 +1,66 @@
+# Guide: Setup
+
+Get high commit message quality and short feedback cycles by linting commit messages right when they are authored.
+
+This guide demonstrates how to achieve this via git hooks.
+
+## Install commitlint
+
+Install `commitlint_cli` and a `commitlint_config` of your choice as dev dependency and
+configure `commitlint` to use it.
+
+```bash
+# Install and configure if needed
+dart pub add --dev commitlint_cli commitlint_config
+
+# Configure commitlint to use conventional config
+echo "include: package:commitlint_config/commitlint.yaml" > commitlint.yaml
+```
+
+## Install husky
+
+Install [husky](https://pub.dev/packages/husky) as dev dependency, a handy git hook helper available on pub.
+
+```sh
+# Install Husky 
+dart pub add --dev husky
+
+# Activate hooks
+dart run husky install
+```
+
+### Add hook
+
+```
+dart run husky add .husky/commit-msg  'dart run commitlint_cli --edit ${1}'
+```
+
+## Test
+
+### Test simple usage
+
+For a first simple usage test of commitlint you can do the following:
+
+```bash
+dart run commitlint_cli --from HEAD~1 --to HEAD
+```
+
+This will check your last commit and return an error if invalid or a positive output if valid.
+
+### Test the hook
+
+You can test the hook by simply committing. You should see something like this if everything works.
+
+```bash
+git commit -m "foo: this will fail"
+No staged files match any of provided globs.
+⧗   input: foo: this will fail
+✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
+
+✖   found 1 problems, 0 warnings
+ⓘ   Get help: http://hyiso.github.io/commitlint/#/concepts-convensional-commits
+
+husky - commit-msg hook exited with code 1 (add --no-verify to bypass)
+```
+
+?> Local linting is fine for fast feedback but can easily be tinkered with. To ensure all commits are linted you'll want to check commits on an automated CI Server too. Learn how to in the [CI Setup guide](guides-ci-setup.md).

docs/guides-setup.md

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>commitlint - Lint commit messages</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'commitlint',
+      repo: 'https://github.com/hyiso/commitlint',
+
+      subMaxLevel: 2,
+      loadSidebar: true,
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+</body>
+</html>