docs: improve mdbook docs (#896)

* docs: improve mdbook docs

* chore: put the link to new docs into README

* docs: use lefthook documentation as a top level title

README.md

@@ -14,6 +14,7 @@ A Git hooks manager for Node.js, Ruby, Python and many other types of projects.
 * **Powerful.** It allows to control execution and files you pass to your commands.
 * **Simple.** It is single dependency-free binary which can work in any environment.
 
+📖 [Check the docs](https://evilmartians.github.io/lefthook/)
 📖 [Read the introduction post](https://evilmartians.com/chronicles/lefthook-knock-your-teams-code-back-into-shape?utm_source=lefthook)
 
 <a href="https://evilmartians.com/?utm_source=lefthook">

book.toml

@@ -3,7 +3,7 @@ authors = ["Evil Martians"]
 language = "en"
 multilingual = false
 src = "docs/mdbook"
-title = "Lefthook"
+title = "Lefthook Documentation"
 
 [output.html]
 no-section-label = true

docs/mdbook/SUMMARY.md

@@ -1,8 +1,8 @@
-# Lefthook
+[Introduction](./intro.md)
 
 # User guide
 
-- [Installation](./install.md)
+- [Installation](./installation/README.md)
   - [Ruby](./installation/ruby.md)
   - [Node.js](./installation/node.md)
   - [Go](./installation/go.md)
@@ -17,7 +17,14 @@
   - [Alpine](./installation/alpine.md)
   - [Arch Linux](./installation/arch.md)
   - [Manual](./installation/manual.md)
-- [Configuration](./configuration/README.md)
+- [Usage](./usage/README.md)
+  - [Commands](./usage/commands.md)
+  - [ENV variables](./usage/env.md)
+  - [Tips](./usage/tips.md)
+
+# Reference guide
+
+- [Config options](./configuration/README.md)
   - [`assert_lefthook_installed`](./configuration/assert_lefthook_installed.md)
   - [`colors`](./configuration/colors.md)
   - [`no_tty`](./configuration/no_tty.md)
@@ -69,7 +76,8 @@
       - [`interactive`](./configuration/interactive.md)
       - [`use_stdin`](./configuration/use_stdin.md)
       - [`priority`](./configuration/priority.md)
-- [Usage](./usage.md)
-  - [Commands](./usage/commands.md)
-  - [ENV variables](./usage/env.md)
-  - [Tips](./usage/tips.md)
+- [Examples](./examples/README.md)
+  - [Commitlint](./examples/commitlint.md)
+  - [Remotes](./examples/remotes.md)
+  - [Auto stage changed files](./examples/stage_fixed.md)
+  - [Filter files](./examples/filters.md)

docs/mdbook/configuration/Commands.md

@@ -1,4 +1,4 @@
-### `commands`
+## `commands`
 
 Commands to be executed for the hook. Each command has a name and associated run [options](#command).
 

docs/mdbook/configuration/README.md

@@ -1,4 +1,21 @@
-# Config options
+## Config file name
+
+Lefthook supports the following file names for the main config:
+
+- `lefthook.yml`
+- `.lefthook.yml`
+- `lefthook.yaml`
+- `.lefthook.yaml`
+- `lefthook.toml`
+- `.lefthook.toml`
+- `lefthook.json`
+- `.lefthook.json`
+
+If there are more than 1 file in the project, only one will be used, and you'll never know which one. So, please, use one format in a project.
+
+Lefthook also merges an extra config with the name `lefthook-local`. All supported formats can be applied to this `-local` config. If you name your main config with the leading dot, like `.lefthook.json`, the `-local` config also must be named with the leading dot: `.lefthook-local.json`.
+
+## Options
 
 - [`assert_lefthook_installed`](./assert_lefthook_installed.md)
 - [`colors`](./colors.md)

docs/mdbook/configuration/assert_lefthook_installed.md

@@ -1,4 +1,4 @@
-# `assert_lefthook_installed`
+## `assert_lefthook_installed`
 
 **Default: `false`**
 

docs/mdbook/configuration/colors.md

@@ -1,4 +1,4 @@
-### `colors`
+## `colors`
 
 **Default: `auto`**
 

docs/mdbook/configuration/configs.md

@@ -1,4 +1,4 @@
-### `configs`
+## `configs`
 
 **Default:** `[lefthook.yml]`
 

docs/mdbook/configuration/env.md

@@ -1,4 +1,4 @@
-### `env`
+## `env`
 
 You can specify some ENV variables for the command or script.
 

docs/mdbook/configuration/exclude.md

@@ -1,14 +1,12 @@
-### `exclude`
+## `exclude`
 
 For the `exclude` option two variants are supported:
 
 - A list of globs to be excluded
 - A single regular expression (deprecated)
 
 
-> NOTE
->
-> The regular expression is matched against full paths to files in the repo,
+> **Note:** The regular expression is matched against full paths to files in the repo,
 > relative to the repo root, using `/` as the directory separator on all platforms.
 > File paths do not begin with the separator or any other prefix.
 
@@ -44,7 +42,7 @@ pre-commit:
       run: bundle exec rubocop --force-exclusion {staged_files}
 ```
 
-**Notes**
+**Important**
 
 Be careful with the config file format's string quoting and escaping rules when writing regexps in it. For YAML, single quotes are often the simplest choice.
 

docs/mdbook/configuration/exclude_tags.md

@@ -1,4 +1,4 @@
-### `exclude_tags`
+## `exclude_tags`
 
 [Tags](./tags.md) or command names that you want to exclude. This option can be overwritten with `LEFTHOOK_EXCLUDE` env variable.
 

docs/mdbook/configuration/extends.md

@@ -1,4 +1,4 @@
-### `extends`
+## `extends`
 
 You can extend your config with another one YAML file. Its content will be merged. Extends for `lefthook.yml`, `lefthook-local.yml`, and [`remotes`](./remotes.md) configs are handled separately, so you can have different extends in these files.
 

docs/mdbook/configuration/fail_text.md

@@ -1,4 +1,4 @@
-### `fail_text`
+## `fail_text`
 
 You can specify a text to show when the command or script fails.
 

docs/mdbook/configuration/file_types.md

@@ -1,4 +1,4 @@
-### `file_types`
+## `file_types`
 
 Filter files in a [`run`](./run.md) templates by their type. Supported types:
 
@@ -11,9 +11,7 @@ Filter files in a [`run`](./run.md) templates by their type. Supported types:
 |`symlink` | A symlink file. |
 |`not symlink` | Any non-symlink file. |
 
-> IMPORTANT
->
-> When passed multiple file types all constraints will be applied to the resulting list of files.
+> **Important:** When passed multiple file types all constraints will be applied to the resulting list of files
 
 **Examples**
 

docs/mdbook/configuration/files-global.md

@@ -1,4 +1,4 @@
-### `files` (global)
+## `files` (global)
 
 A custom git command for files to be referenced in `{files}` template. See [`run`](#run) and [`files`](#files).
 

docs/mdbook/configuration/files.md

@@ -1,4 +1,4 @@
-### `files`
+## `files`
 
 A custom git command for files or directories to be referenced in `{files}` template for [`run`](./run.md) setting.
 

docs/mdbook/configuration/follow.md

@@ -1,4 +1,4 @@
-### `follow`
+## `follow`
 
 **Default: `false`**
 
@@ -18,6 +18,4 @@ pre-push:
       run: yarn test
 ```
 
-> NOTE
->
-> If used with [`parallel`](#parallel) the output can be a mess, so please avoid setting both options to `true`.
+> **Note:** If used with [`parallel`](#parallel) the output can be a mess, so please avoid setting both options to `true`

docs/mdbook/configuration/git_url.md

@@ -1,4 +1,4 @@
-### `git_url`
+## `git_url`
 
 A URL to Git repository. It will be accessed with privileges of the machine lefthook runs on.
 

docs/mdbook/configuration/glob.md

@@ -1,4 +1,4 @@
-### `glob`
+## `glob`
 
 You can set a glob to filter files for your command. This is only used if you use a file template in [`run`](./run.md) option or provide your custom [`files`](./files.md) command.
 

docs/mdbook/configuration/interactive.md

@@ -1,10 +1,8 @@
-### `interactive`
+## `interactive`
 
 **Default: `false`**
 
-> NOTE
->
-> If you want to pass stdin to your command or script but don't need to get the input from CLI, use [`use_stdin`](./use_stdin.md) option instead.
+> **Note:** If you want to pass stdin to your command or script but don't need to get the input from CLI, use [`use_stdin`](./use_stdin.md) option instead.
 
 
 Whether to use interactive mode. This applies the certain behavior:

docs/mdbook/configuration/min_version.md

@@ -1,4 +1,4 @@
-### `min_version`
+## `min_version`
 
 If you want to specify a minimum version for lefthook binary (e.g. if you need some features older versions don't have) you can set this option.
 

docs/mdbook/configuration/no_tty.md

@@ -1,4 +1,4 @@
-### `no_tty`
+## `no_tty`
 
 **Default: `false`**
 

docs/mdbook/configuration/only.md

@@ -1,10 +1,8 @@
-### `only`
+## `only`
 
 You can force a command, script, or the whole hook to execute only in certain conditions. This option acts like the opposite of [`skip`](./skip.md). It accepts the same values but skips execution only if the condition is not satisfied.
 
-> NOTE
->
-> `skip` option takes precedence over `only` option, so if you have conflicting conditions the execution will be skipped.
+> **Note:** `skip` option takes precedence over `only` option, so if you have conflicting conditions the execution will be skipped.
 
 **Example**
 

docs/mdbook/configuration/output.md

@@ -1,4 +1,4 @@
-### `output`
+## `output`
 
 You can manage verbosity using the `output` config. You can specify what to print in your output by setting these values, which you need to have
 

docs/mdbook/configuration/parallel.md

@@ -1,9 +1,7 @@
-### `parallel`
+## `parallel`
 
 **Default: `false`**
 
-> NOTE
->
-> Lefthook runs commands and scripts **sequentially** by default.
+> **Note:** Lefthook runs commands and scripts **sequentially** by default
 
 Run commands and scripts concurrently.

docs/mdbook/configuration/piped.md

@@ -1,10 +1,8 @@
-### `piped`
+## `piped`
 
 **Default: `false`**
 
-> NOTE
->
-> Lefthook will return an error if both `piped: true` and `parallel: true` are set.
+> **Note:** Lefthook will return an error if both `piped: true` and `parallel: true` are set
 
 Stop running commands and scripts if one of them fail.
 

docs/mdbook/configuration/priority.md

@@ -1,10 +1,8 @@
-### `priority`
+## `priority`
 
 **Default: `0`**
 
-> NOTE
->
-> This option makes sense only when `parallel: false` or `piped: true` is set.
+> **Note:** This option makes sense only when `parallel: false` or `piped: true` is set.
 >
 > Value `0` is considered an `+Infinity`, so commands or scripts with `priority: 0` or without this setting will be run at the very end.
 

docs/mdbook/configuration/rc.md

@@ -1,4 +1,4 @@
-### `rc`
+## `rc`
 
 Provide an [**rc**](https://www.baeldung.com/linux/rc-files) file, which is actually a simple `sh` script. Currently it can be used to set ENV variables that are not accessible from non-shell programs.
 

docs/mdbook/configuration/ref.md

@@ -1,10 +1,8 @@
-### `ref`
+## `ref`
 
 An optional *branch* or *tag* name.
 
-> NOTE
->
-> If you initially had `ref` option, ran `lefthook install`, and then removed it, lefthook won't decide which branch/tag to use as a ref. So, if you added it once, please, use it always to avoid issues in local setups.
+> **Note:** If you initially had `ref` option, ran `lefthook install`, and then removed it, lefthook won't decide which branch/tag to use as a ref. So, if you added it once, please, use it always to avoid issues in local setups.
 
 **Example**
 

docs/mdbook/configuration/refetch.md

@@ -1,4 +1,4 @@
-### `refetch`
+## `refetch`
 
 **Default:** `false`
 

docs/mdbook/configuration/refetch_frequency.md

@@ -1,4 +1,4 @@
-### `refetch_frequency`
+## `refetch_frequency`
 
 **Default:** Not set
 

docs/mdbook/configuration/root.md

@@ -1,4 +1,4 @@
-### `root`
+## `root`
 
 You can change the CWD for the command you execute using `root` option.
 

docs/mdbook/configuration/run.md

@@ -1,4 +1,4 @@
-### `run`
+## `run`
 
 This is a mandatory option for a command. This is actually a command that is executed for the hook.
 
@@ -72,9 +72,7 @@ pre-push:
 
 Simply run `bundle exec rubocop` on all files with `.rb` extension excluding `application.rb` and `routes.rb` files.
 
-> NOTE
->
-> `--force-exclusion` will apply `Exclude` configuration setting of Rubocop.
+> **Note:** `--force-exclusion` will apply `Exclude` configuration setting of Rubocop
 
 ```yml
 # lefthook.yml

docs/mdbook/configuration/runner.md

@@ -1,4 +1,4 @@
-### `runner`
+## `runner`
 
 You should specify a runner for the script. This is a command that should execute a script file. It will be called the following way: `<runner> <path-to-script>` (e.g. `ruby .lefthook/pre-commit/lint.rb`).
 

docs/mdbook/configuration/skip.md

@@ -1,4 +1,4 @@
-### `skip`
+## `skip`
 
 You can skip all or specific commands and scripts using `skip` option. You can also skip when merging, rebasing, or being on a specific branch. Globs are available for branches.
 

docs/mdbook/configuration/skip_output.md

@@ -1,4 +1,4 @@
-### `skip_output`
+## `skip_output`
 
 > **DEPRECATED** This feature is deprecated and might be removed in future versions. Please, use `[output]` instead for managing verbosity.
 

docs/mdbook/configuration/source_dir.md

@@ -1,4 +1,4 @@
-### `source_dir`
+## `source_dir`
 
 **Default: `.lefthook/`**
 

docs/mdbook/configuration/source_dir_local.md

@@ -1,4 +1,4 @@
-### `source_dir_local`
+## `source_dir_local`
 
 **Default: `.lefthook-local/`**
 

docs/mdbook/configuration/stage_fixed.md

@@ -1,8 +1,8 @@
-### `stage_fixed`
+## `stage_fixed`
 
 **Default: `false`**
 
-> Used **only for `pre-commit`** hook. Is ignored for other hooks.
+> Works **only for `pre-commit`** hook
 
 When set to `true` lefthook will automatically call `git add` on files after running the command or script. For a command if [`files`](./files.md) option was specified, the specified command will be used to retrieve files for `git add`. For scripts and commands without [`files`](./files.md) option `{staged_files}` template will be used. All filters ([`glob`](./glob.md), [`exclude`](./exclude.md)) will be applied if specified.
 

docs/mdbook/configuration/tags.md

@@ -1,4 +1,4 @@
-### `tags`
+## `tags`
 
 You can specify tags for commands and scripts. This is useful for [excluding](./exclude_tags.md). You can specify more than one tag using comma.