fix links

Author: bearomorphism

docs/commands/bump.md

@@ -50,7 +50,7 @@ Available options are:
 - `pep440`: [PEP 440][pep440] (**default** and recommended for Python projects)
 - `semver`: [Semantic Versioning][semver] (recommended for non-Python projects)
 
-You can also set this in the [configuration](#version_scheme) with `version_scheme = "semver"`.
+You can also set this in the configuration file with `version_scheme = "semver"`.
 
 !!! note
     [pep440][pep440] and [semver][semver] are quite similar, although their difference lies in
@@ -111,7 +111,7 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several
 
 ### `--files-only`
 
-Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository.
+Bumps the version in the files defined in [version_files][version_files] without creating a commit and tag on the git repository.
 
 ```bash
 cz bump --files-only
@@ -178,7 +178,7 @@ The following table illustrates the difference in behavior between the two modes
 
 ### `--check-consistency`
 
-Check whether the versions defined in [`version_files`](#version_files) and the version in Commitizen configuration are consistent before bumping version.
+Check whether the versions defined in [version_files][version_files] and the version in Commitizen configuration are consistent before bumping version.
 
 ```bash
 cz bump --check-consistency
@@ -207,7 +207,7 @@ from setuptools import setup
 setup(..., version="1.0.5", ...)
 ```
 
-When you run `cz bump --check-consistency`, Commitizen will verify that the current version in `pyproject.toml` (`1.21.0`) exists in all files listed in [`version_files`](#version_files).
+When you run `cz bump --check-consistency`, Commitizen will verify that the current version in `pyproject.toml` (`1.21.0`) exists in all files listed in [version_files][version_files].
 In this example, it will detect that `setup.py` contains `1.0.5` instead of `1.21.0`, causing the bump to fail.
 
 !!! warning "Partial updates on failure"
@@ -457,13 +457,9 @@ Allow the project version to be bumped even when there's no eligible version.
     cz bump --allow-no-commit
     ```
 
-### `--version-scheme`
-
-See [Version Schemes](#version-schemes-version-scheme).
-
 ### `--tag-format`
 
-`tag_format` and [`version_scheme`](#version-schemes-version-scheme) are combined to make Git tag names from versions.
+`tag_format` and [version_scheme][version_scheme] are combined to make Git tag names from versions.
 
 These are used in:
 
@@ -505,9 +501,6 @@ Supported variables:
 | `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) |
 | `$devrelease`, `${devrelease}` | Development release                         |
 
-
-## Configuration file options
-
 ## Avoid raising errors
 
 Some situations from Commitizen raise an exit code different from 0.
@@ -577,3 +570,4 @@ Read the [customizing section](../customization.md).
 
 [pep440]: https://www.python.org/dev/peps/pep-0440/
 [semver]: https://semver.org/
+[version_files]: ../config/bump.md#version_files

docs/commands/changelog.md

@@ -2,12 +2,13 @@
 
 This command will generate a changelog following the committing rules established.
 
-To create the changelog automatically on bump, add the setting [update_changelog_on_bump](./bump.md#update_changelog_on_bump)
+!!! tip
+    To create the changelog automatically on bump, add the setting [update_changelog_on_bump](../config/bump.md#update_changelog_on_bump)
 
-```toml
-[tool.commitizen]
-update_changelog_on_bump = true
-```
+    ```toml
+    [tool.commitizen]
+    update_changelog_on_bump = true
+    ```
 
 ## Usage
 

docs/config/bump.md

@@ -1,89 +1,15 @@
 # Bump Options
 
-## `legacy_tag_formats`
-
-- Type: `list`
-- Default: `[]`
-
-Legacy git tag formats, useful for old projects that changed tag format.
-Tags matching those formats will be recognized as version tags and be included in the changelog.
-Each entry uses the syntax as `tag_format`.
-
-### `version_files`
-
-Identify the files or glob patterns which should be updated with the new version.
-
-Commitizen will update its configuration file automatically when bumping,
-regardless of whether the file is present or not in `version_files`.
-
-You may specify the `version_files` in your configuration file.
-
-```toml title="pyproject.toml"
-[tool.commitizen]
-version_files = [
-    "src/__version__.py",
-]
-```
-
-It is also possible to provide a pattern for each file, separated by a colon (e.g. `file:pattern`). See the below example for more details.
-
-```toml title="pyproject.toml"
-[tool.commitizen]
-version_files = [
-    "packages/*/pyproject.toml:version",
-    "setup.json:version",
-]
-```
+## `annotated_tag`
 
-#### Example scenario
-
-We have a project with the following configuration file `pyproject.toml`:
+When set to `true`, `cz bump` is equivalent to `cz bump --annotated-tag`.
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
-version_files = [
-    "src/__version__.py",
-    "packages/*/pyproject.toml:version",
-    "setup.json:version",
-]
-```
-
-For the reference `"setup.json:version"`, it means that it will look for a file `setup.json` and will only change the lines that contain the substring `"version"`.
-
-For example, if the content of `setup.json` is:
-
-<!-- DEPENDENCY: repeated_version_number.json -->
-
-```json title="setup.json"
-{
-  "name": "magictool",
-  "version": "1.2.3",
-  "dependencies": {
-      "lodash": "1.2.3"
-  }
-}
-```
-
-After running `cz bump 2.0.0`, its content will be updated to:
-
-```diff title="setup.json"
-{
-  "name": "magictool",
-- "version": "1.2.3",
-+ "version": "2.0.0",
-  "dependencies": {
-      "lodash": "1.2.3"
-  }
-}
+annotated_tag = true
 ```
 
-!!! note
-    Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
-
-!!! note "Historical note"
-    This option was renamed from `files` to `version_files`.
-
-### `bump_message`
+## `bump_message`
 
 Template used to specify the commit message generated when bumping.
 
@@ -94,53 +20,49 @@ Defaults to: `bump: version $current_version → $new_version`
 | `$current_version` | the version existing before bumping |
 | `$new_version`     | version generated after bumping     |
 
-#### Example configuration
-
 ```toml title="pyproject.toml"
 [tool.commitizen]
 bump_message = "release $current_version → $new_version [skip-ci]"
 ```
 
-### `update_changelog_on_bump`
+## `gpg_sign`
 
-When set to `true`, `cz bump` is equivalent to `cz bump --changelog`.
+When set to `true`, `cz bump` is equivalent to `cz bump --gpg-sign`. See [`--gpg-sign`](../commands/bump.md#-gpg-sign).
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
-update_changelog_on_bump = true
+gpg_sign = true
 ```
 
-### `annotated_tag`
+## `ignored_tag_formats`
 
-When set to `true`, `cz bump` is equivalent to `cz bump --annotated-tag`.
+- Type: `list`
+- Default: `[]`
 
-```toml title="pyproject.toml"
-[tool.commitizen]
-annotated_tag = true
-```
+Tags matching those formats will be totally ignored and won't raise a warning.
+Each entry uses the syntax as [`tag_format`](#tag_format) with the addition of `*` that will match everything (non-greedy).
 
-### `gpg_sign`
+## `major_version_zero`
 
-When set to `true`, `cz bump` is equivalent to `cz bump --gpg-sign`. See [`--gpg-sign`](../commands/bump.md#-gpg-sign).
+When set to `true`, `cz bump` is equivalent to `cz bump --major-version-zero`. See [`--major-version-zero`](../commands/bump.md#-major-version-zero).
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
-gpg_sign = true
+major_version_zero = true
 ```
 
-### `major_version_zero`
+## `legacy_tag_formats`
 
-When set to `true`, `cz bump` is equivalent to `cz bump --major-version-zero`. See [`--major-version-zero`](../commands/bump.md#-major-version-zero).
+- Type: `list`
+- Default: `[]`
 
-```toml title="pyproject.toml"
-[tool.commitizen]
-major_version_zero = true
-```
+Legacy git tag formats, useful for old projects that changed tag format.
+Tags matching those formats will be recognized as version tags and be included in the changelog.
+Each entry uses the syntax as `tag_format`.
 
-### `pre_bump_hooks`
+## `pre_bump_hooks`
 
-A list of optional commands that will run right _after_ updating [`version_files`](#version_files)
-and _before_ actual committing and tagging the release.
+A list of optional commands that will run right *after* updating [`version_files`](#version_files) and *before* actual committing and tagging the release.
 
 Useful when you need to generate documentation based on the new version. During
 execution of the script, some environment variables are available:
@@ -163,9 +85,9 @@ pre_bump_hooks = [
 ]
 ```
 
-### `post_bump_hooks`
+## `post_bump_hooks`
 
-A list of optional commands that will run right _after_ committing and tagging the release.
+A list of optional commands that will run right *after* committing and tagging the release.
 
 Useful when you need to send notifications about a release, or further automate deploying the
 release. During execution of the script, some environment variables are available:
@@ -188,56 +110,106 @@ post_bump_hooks = [
 ]
 ```
 
-### `prerelease_offset`
+## `prerelease_offset`
 
 Offset with which to start counting prereleases.
 
-Defaults to: `0`
+If not specified, defaults to `0`.
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
 prerelease_offset = 1
 ```
 
-### `version_scheme`
+!!! note
+    Under some circumstances, a prerelease cannot start with `0`-for example, in embedded projects where individual characters are encoded as bytes. You can specify an offset from which to start counting.
 
-See [`--version-scheme`](../commands/bump.md#--version-scheme).
+## `tag_format`
 
-### `ignored_tag_formats`
+See [`--tag-format`](../commands/bump.md#-tag-format).
 
-- Type: `list`
-- Default: `[]`
-
-Tags matching those formats will be totally ignored and won't raise a warning.
-Each entry uses the syntax as [`tag_format`](#tag_format) with the addition of `*`
-that will match everything (non-greedy). [Read more][tag_format]
+## `update_changelog_on_bump`
 
+When set to `true`, `cz bump` is equivalent to `cz bump --changelog`.
 
-### `major_version_zero`
+```toml title="pyproject.toml"
+[tool.commitizen]
+update_changelog_on_bump = true
+```
 
-- Type: `bool`
-- Default: `False`
+## `version_files`
 
-If enabled, breaking changes on a `0.x` will remain as a `0.x` version. Otherwise, a breaking change will bump a `0.x` version to `1.0`. [Read more][major-version-zero]
+Identify the files or glob patterns which should be updated with the new version.
 
+Commitizen will update its configuration file automatically when bumping,
+regardless of whether the file is present or not in `version_files`.
 
-### `prerelease_offset`
+You may specify the `version_files` in your configuration file.
 
-- Type: `int`
-- Default: `0`
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_files = [
+    "src/__version__.py",
+]
+```
 
-In some circumstances, a prerelease cannot start with `0`-for example, in embedded projects where individual characters are encoded as bytes. You can specify an offset from which to start counting. [Read more][prerelease-offset]
+It is also possible to provide a pattern for each file, separated by a colon (e.g. `file:pattern`). See the below example for more details.
 
-### `pre_bump_hooks`
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_files = [
+    "packages/*/pyproject.toml:version",
+    "setup.json:version",
+]
+```
 
-- Type: `list[str]`
-- Default: `[]`
+!!! note "Example scenario"
+    We have a project with the following configuration file `pyproject.toml`:
+
+    ```toml title="pyproject.toml"
+    [tool.commitizen]
+    version_files = [
+        "src/__version__.py",
+        "packages/*/pyproject.toml:version",
+        "setup.json:version",
+    ]
+    ```
+
+    For the reference `"setup.json:version"`, it means that it will look for a file `setup.json` and will only change the lines that contain the substring `"version"`.
+
+    For example, if the content of `setup.json` is:
+
+    <!-- DEPENDENCY: repeated_version_number.json -->
+
+    ```json title="setup.json"
+    {
+    "name": "magictool",
+    "version": "1.2.3",
+    "dependencies": {
+        "lodash": "1.2.3"
+    }
+    }
+    ```
+
+    After running `cz bump 2.0.0`, its content will be updated to:
+
+    ```diff title="setup.json"
+    {
+    "name": "magictool",
+    - "version": "1.2.3",
+    + "version": "2.0.0",
+    "dependencies": {
+        "lodash": "1.2.3"
+    }
+    }
+    ```
 
-Calls the hook scripts **before** bumping version. [Read more][pre_bump_hooks]
+!!! note
+    Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
 
-### `post_bump_hooks`
+!!! note "Historical note"
+    This option was renamed from `files` to `version_files`.
 
-- Type: `list[str]`
-- Default: `[]`
+## `version_scheme`
 
-Calls the hook scripts **after** bumping the version. [Read more][post_bump_hooks]
+See [`--version-scheme`](../commands/bump.md#-version-scheme).