docs: improve readability

woile · woile · commit 33b69c33e44e · 2026-04-07T06:57:00.000+01:00
diff --git a/docs/commands/bump.md b/docs/commands/bump.md
@@ -30,94 +30,6 @@ The version follows the `MAJOR.MINOR.PATCH` format, with increments determined b
 | `MINOR`   | New features                | `feat`                  |
 | `PATCH`   | Fixes and improvements      | `fix`, `perf`, `refactor`|
 
-### `--version-scheme`
-
-By default, Commitizen uses [PEP 440][pep440] for version formatting. You can switch to semantic versioning using either:
-
-1. Command line:
-```sh
-cz bump --version-scheme semver
-```
-
-2. Configuration file:
-```toml title="pyproject.toml"
-[tool.commitizen]
-version_scheme = "semver"
-```
-
-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 file with `version_scheme = "semver"`.
-
-!!! note
-    [pep440][pep440] and [semver][semver] are quite similar, although their difference lies in
-    how the prereleases look. For example, `0.3.1a0` in pep440 is equivalent to `0.3.1-a0` in semver.
-
-    The following table illustrates the difference between the two schemes:
-
-    | Version Type | pep440         | semver          |
-    |--------------|----------------|-----------------|
-    | Non-prerelease | `0.1.0`        | `0.1.0`         |
-    | Prerelease     | `0.3.1a0`      | `0.3.1-a0`      |
-    | Devrelease     | `0.1.1.dev1`   | `0.1.1-dev1`    |
-    | Dev and pre    | `1.0.0a3.dev1` | `1.0.0-a3-dev1` |
-
-
-!!! note "Incomplete Version Handling"
-    Commitizen treats a three-part version (major.minor.patch) as complete.
-    If your configured version is incomplete (for example, `1` or `1.2`), Commitizen pads missing parts with zeros when it needs `major/minor/patch` for tag formatting.
-    The tag output depends on your `tag_format`: formats using `${version}` keep `1`/`1.2`, while formats using `${major}.${minor}.${patch}` will render `1.0.0`/`1.2.0`.
-
-    When bumping from an incomplete version, Commitizen looks for the latest existing tag that matches the provided release prefix.
-    For example, if the current version is `1.2` and the latest `1.2.x` tag is `1.2.3`, then a patch bump yields `1.2.4` and a minor bump yields `1.3.0`.
-
-!!! tip
-    To control the behaviour of bumping and version parsing, you may implement your own `version_scheme` by inheriting from `commitizen.version_schemes.BaseVersion` or use an existing plugin package.
-
-
-### PEP440 Version Examples
-
-Commitizen supports the [PEP 440][pep440] version format, which includes several version types. Here are examples of each:
-
-#### Standard Releases
-```text
-0.9.0    # Initial development release
-0.9.1    # Patch release
-0.9.2    # Another patch release
-0.9.10   # Tenth patch release
-0.9.11   # Eleventh patch release
-1.0.0    # First stable release
-1.0.1    # Patch release after stable
-1.1.0    # Minor feature release
-2.0.0    # Major version release
-```
-
-#### Pre-releases
-```text
-1.0.0a0  # Alpha release 0
-1.0.0a1  # Alpha release 1
-1.0.0b0  # Beta release 0
-1.0.0rc0 # Release candidate 0
-1.0.0rc1 # Release candidate 1
-```
-
-#### Development Releases
-```text
-1.0.0.dev0  # Development release 0
-1.0.0.dev1  # Development release 1
-```
-
-#### Combined Pre-release and Development
-```text
-1.0.0a1.dev0  # Development release 0 of alpha 1
-1.0.0b2.dev1  # Development release 1 of beta 2
-```
-
-> **Note**: `post` releases (e.g., `1.0.0.post1`) are not currently supported.
-
 ## Command line options
 
 ![cz bump --help](../images/cli_help/cz_bump___help.svg)
@@ -176,7 +88,7 @@ For example, if the current version is `1.0.0b1` then bumping with `--prerelease
 Applies the exact changes that have been specified with `--increment` or determined from the commit log.
 For example, `--prerelease beta` will always result in a `b` tag, and `--increment PATCH` will always increase the patch component.
 
-#### Examples
+**Examples**
 
 The following table illustrates the difference in behavior between the two modes:
 
@@ -525,6 +437,100 @@ Automatically answers “yes” to all interactive prompts during the bump proce
 cz bump --yes
 ```
 
+### `--version-scheme`
+
+Format used for the version.
+
+**Available options**
+
+- `pep440`: [PEP 440][pep440]: recommended for Python projects, **default** (for legacy reasons)
+- `semver2`: [Semantic Versioning v2][semver]: recommended for non-Python projects
+- `semver`: [Semantic Versioning v1](https://semver.org/spec/v1.0.0.html): use if you are stuck with semver v1
+
+**Examples**
+
+1. Command line:
+```sh
+cz bump --version-scheme semver2
+```
+
+2. Configuration file:
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_scheme = "semver2"
+```
+
+
+!!! note
+    [pep440][pep440] and [semver][semver] are quite similar, although their difference lies in
+    how the prereleases look. For example, `0.3.1a0` in pep440 is equivalent to `0.3.1-a0` in semver.
+
+    The following table illustrates the difference between the two schemes:
+
+    | Version Type | pep440         | semver          |
+    |--------------|----------------|-----------------|
+    | Non-prerelease | `0.1.0`        | `0.1.0`         |
+    | Prerelease     | `0.3.1a0`      | `0.3.1-a0`      |
+    | Devrelease     | `0.1.1.dev1`   | `0.1.1-dev1`    |
+    | Dev and pre    | `1.0.0a3.dev1` | `1.0.0-a3-dev1` |
+
+
+!!! note "Incomplete Version Handling"
+    Commitizen treats a three-part version (major.minor.patch) as complete.
+    If your configured version is incomplete (for example, `1` or `1.2`), Commitizen pads missing parts with zeros when it needs `major/minor/patch` for tag formatting.
+    The tag output depends on your `tag_format`: formats using `${version}` keep `1`/`1.2`, while formats using `${major}.${minor}.${patch}` will render `1.0.0`/`1.2.0`.
+
+    When bumping from an incomplete version, Commitizen looks for the latest existing tag that matches the provided release prefix.
+    For example, if the current version is `1.2` and the latest `1.2.x` tag is `1.2.3`, then a patch bump yields `1.2.4` and a minor bump yields `1.3.0`.
+
+!!! tip
+    To control the behaviour of bumping and version parsing, you may implement your own `version_scheme` by inheriting from `commitizen.version_schemes.BaseVersion` or use an existing plugin package.
+
+
+### PEP440 Version Examples
+
+Commitizen supports the [PEP 440][pep440] version format, which includes several version types. Here are examples of each:
+
+#### Standard Releases
+
+```text
+0.9.0    # Initial development release
+0.9.1    # Patch release
+0.9.2    # Another patch release
+0.9.10   # Tenth patch release
+0.9.11   # Eleventh patch release
+1.0.0    # First stable release
+1.0.1    # Patch release after stable
+1.1.0    # Minor feature release
+2.0.0    # Major version release
+```
+
+#### Pre-releases
+
+```text
+1.0.0a0  # Alpha release 0
+1.0.0a1  # Alpha release 1
+1.0.0b0  # Beta release 0
+1.0.0rc0 # Release candidate 0
+1.0.0rc1 # Release candidate 1
+```
+
+#### Development Releases
+
+```text
+1.0.0.dev0  # Development release 0
+1.0.0.dev1  # Development release 1
+```
+
+#### Combined Pre-release and Development
+
+```text
+1.0.0a1.dev0  # Development release 0 of alpha 1
+1.0.0b2.dev1  # Development release 1 of beta 2
+```
+
+> **Note**: `post` releases (e.g., `1.0.0.post1`) are not currently supported.
+
 [pep440]: https://www.python.org/dev/peps/pep-0440/
 [semver]: https://semver.org/
 [version_files]: ../config/bump.md#version_files
diff --git a/docs/commands/changelog.md b/docs/commands/changelog.md
@@ -77,28 +77,36 @@ cz changelog --extra key=value -e short="quoted value"
 
 ### `--file-name`
 
-This value can be updated in the configuration file with the key `changelog_file` under `tool.commitizen`.
-
 Specify the name of the output file. Note that changelog generation only works with Markdown files.
 
 ```bash
 cz changelog --file-name="CHANGES.md"
 ```
 
+This value can be updated in the configuration file with the key `changelog_file` under `tool.commitizen`.
+
+```toml
+[tool.commitizen]
+# ...
+changelog_file = "CHANGES.md"
+```
+
 ### `--incremental`
 
-This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`
+Build from the latest version found in changelog.
 
 Benefits:
 
-- Build from the latest version found in changelog. This is useful if you have an existing changelog and want to use commitizen to extend it.
+- Useful if you have an existing changelog and want to use commitizen to extend it.
 - Update unreleased area
 - Allows users to manually edit the changelog without it being completely rewritten.
 
 ```bash
 cz changelog --incremental
 ```
 
+This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`.
+
 ```toml
 [tool.commitizen]
 # ...
@@ -107,14 +115,14 @@ changelog_incremental = true
 
 ### `--start-rev`
 
-This value can be set in the configuration file with the key `changelog_start_rev` under `tool.commitizen`
-
 Start from a given git rev to generate the changelog. Commits before that rev will not be considered. This is especially useful for long-running projects adopting conventional commits, where old commit messages might fail to be parsed for changelog generation.
 
 ```bash
 cz changelog --start-rev="v0.2.0"
 ```
 
+This value can be set in the configuration file with the key `changelog_start_rev` under `tool.commitizen`
+
 ```toml
 [tool.commitizen]
 # ...
@@ -123,14 +131,14 @@ changelog_start_rev = "v0.2.0"
 
 ### `--merge-prerelease`
 
-This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tool.commitizen`
-
 Collects changes from prereleases into the next non-prerelease version. If you have a prerelease version followed by a normal release, the changelog will show the prerelease changes as part of the normal release. If not set, prereleases will be included as separate entries in the changelog.
 
 ```bash
 cz changelog --merge-prerelease
 ```
 
+This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tool.commitizen`
+
 ```toml
 [tool.commitizen]
 # ...
diff --git a/docs/config/bump.md b/docs/config/bump.md
@@ -212,6 +212,47 @@ version_files = [
 !!! note "Historical note"
     This option was renamed from `files` to `version_files`.
 
+## `version_provider`
+
+Mechanism by which Commitizen reads and writes version information in your project.
+
+For a detailed explanation, check the [version provider](./version_provider.md) section.
+Which includes, how to create your own version provider.
+
+**Available options**
+
+- `commitizen`: default version provider and stores the version in the active commitizen config (`pyproject.toml` or `.cz.toml`) under the key `version`
+- `scm`: git tags provide the real version to commitizen (read only)
+- `pep621`: (python) manages version in `pyproject.toml` under the `project.version` field, following [PEP 621](https://peps.python.org/pep-0621/) standards
+- `poetry`: takes the version from poetry v1, use `pep621` with poetry v2 or later
+- `uv`: same as `pep621` except that it also updates the `uv.lock`
+- `cargo`: manages version in both `Cargo.toml` (`package.version`) and `Cargo.lock`
+- `npm`: manages version in `package.json` and the lock
+- `composer`: for PHP's Composer package manager
+
+**Example**
+
+```toml
+[tool.commitizen]
+version_provider = "pep621"
+```
+
 ## `version_scheme`
 
-See [`--version-scheme`](../commands/bump.md#-version-scheme).
+Format used for the version.
+
+For a detail explanation, check [`--version-scheme`](../commands/bump.md#-version-scheme).
+
+**Available options**
+
+- `pep440`: [PEP 440](https://www.python.org/dev/peps/pep-0440/): recommended for Python projects, **default** (for legacy reasons)
+- `semver2`: [Semantic Versioning](https://semver.org/): recommended for non-Python projects
+- `semver`: [Semantic Versioning](https://semver.org/spec/v1.0.0.html): use if you are stuck with semver v1
+
+**Example**
+
+
+```toml
+[tool.commitizen]
+version_scheme = "semver2"
+```
diff --git a/docs/config/option.md b/docs/config/option.md
@@ -1,43 +1,57 @@
-# Misc Options
+# General Options
 
 ## `name`
 
+Name of the committing rules to use. What we generally call the **commit conventions**.
+
 - Type: `str`
 - Default: `"cz_conventional_commits"`
+- Options
+  - `cz_conventional_commits`: uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+  - `cz_jira`: jira [smart commits](https://support.atlassian.com/bitbucket-cloud/docs/use-smart-commits/)
+  - `cz_customize`: (**not recommended**) customize the convention directly in the `TOML` file under `[tool.commitizen.customize]`, read [Customize in configuration file](../customization/config_file.md) for more. There's a plan to provide a different functionality.
 
-Name of the committing rules to use.
+You can write your own convention, and release it on PyPI, check [Customizing through a Python class](../customization/python_class.md).
 
 ## `version`
 
+Current version.
+
+Required if you use `version_provider = "commitizen"`.
+
 - Type: `str`
 - Default: `None`
 
-Current version. Example: `"0.1.2"`. Required if you use `version_provider = "commitizen"`.
+ Example: `"0.1.2"`.
 
 ## `style`
 
+Style for the prompts.
+
 - Type: `list`
 - Default: `[]`
 
-Style for the prompts (It will merge this value with default style.) See [Styling your prompts with your favorite colors](https://github.com/tmbo/questionary#additional-features) for more details.
+It will merge this value with default style. See [Styling your prompts with your favorite colors](https://github.com/tmbo/questionary#additional-features) for more details.
 
 ## `customize`
 
+Custom rules for committing and bumping.
+
 - Type: `dict`
 - Default: `None`
 
 **Supported in TOML, JSON, and YAML configuration files.**
 
-Custom rules for committing and bumping. See [customization](../customization/config_file.md) for more details.
+See [customization](../customization/config_file.md) for more details.
 
 ## `use_shortcuts`
 
+Show keyboard shortcuts when selecting from a list. When enabled, each choice shows a shortcut key; press that key or use the arrow keys to select.
+
 - Type: `bool`
 - Default: `False`
 
-Show keyboard shortcuts when selecting from a list. When enabled, each choice shows a shortcut key; press that key or use the arrow keys to select.
-
-Example:
+**Example**
 
 ```toml title="pyproject.toml"
 [tool.commitizen]
diff --git a/docs/config/version_provider.md b/docs/config/version_provider.md
diff --git a/mkdocs.yml b/mkdocs.yml
