cihai · tony · Jul 5, 2026 · Jul 5, 2026 · Jul 5, 2026
diff --git a/CHANGES b/CHANGES
@@ -39,6 +39,15 @@ $ uvx --from 'cihai-cli' --prerelease allow cihai
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Documentation
+
+#### Clearer documentation links and examples (#354)
+
+Documentation pages now link readers from the first mention of key tools, API
+entry points, and command pages to the right reference. The quickstart and
+completion pages also keep shell examples copyable by moving explanatory text
+into prose, so readers can follow setup steps without editing copied commands.
+
 ## cihai-cli 0.34.0 (2026-06-28)
 
 cihai-cli 0.34.0 tracks the latest cihai and unihan-etl releases. The `cihai`

diff --git a/MIGRATION b/MIGRATION
@@ -1,6 +1,6 @@
 # Migration notes
 
-Migration and deprecation notes for cihai-cli are here, see {ref}`changelog` as
+Migration and deprecation notes for cihai-cli are here, see {ref}`history` as
 well.
 
 ```{admonition} Welcome on board! 👋

diff --git a/docs/cli/completion.md b/docs/cli/completion.md
@@ -6,25 +6,27 @@
 
 # Completions
 
+Shell completion lets your shell suggest `cihai` commands and options as you type.
+
 ## cihai-cli 0.15+ (experimental)
 
 ```{note}
 See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for cihai-cli.
 ```
 
-Provisional support for completions in cihai-cli 0.15+ are powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with cihai-cli**.
+Provisional support for completions in cihai-cli 0.15+ is powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with cihai-cli**.
 
 ```console
 $ pip install shtab --user
 ```
 
-Or manage it inside an existing project with uv:
+Or manage it inside an existing project with [uv]:
 
 ```console
 $ uv add --dev shtab
 ```
 
-Install `shtab` as a user-wide tool with uv:
+Install `shtab` as a user-wide tool with [uv]:
 
 ```console
 $ uv tool install shtab
@@ -36,6 +38,8 @@ Run it on-demand without installing:
 $ uvx shtab
 ```
 
+Each shell command below points `shtab` at {func}`cihai_cli.cli.create_parser`, the parser factory used by cihai-cli.
+
 :::{tab} bash
 
 ```console
@@ -75,10 +79,8 @@ cihai-cli 0.2 to 0.14 use [click](https://click.palletsprojects.com)'s completio
 
 _~/.bashrc_:
 
-```bash
-
-eval "$(_CIHAI_COMPLETE=bash_source cihai)"
-
+```console
+$ eval "$(_CIHAI_COMPLETE=bash_source cihai)"
 ```
 
 :::
@@ -87,10 +89,10 @@ eval "$(_CIHAI_COMPLETE=bash_source cihai)"
 
 _~/.zshrc_:
 
-```zsh
-
-eval "$(_CIHAI_COMPLETE=zsh_source cihai)"
-
+```console
+$ eval "$(_CIHAI_COMPLETE=zsh_source cihai)"
 ```
 
 :::
+
+[uv]: https://docs.astral.sh/uv/
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -54,6 +54,7 @@ completion
     :func: create_parser
     :prog: cihai
     :nosubcommands:
+    :no-description:
 
     subparser_name : @replace
         See :ref:`cli-info`, :ref:`cli-reverse`

diff --git a/docs/project/code-style.md b/docs/project/code-style.md
@@ -2,7 +2,7 @@
 
 ## Formatting
 
-cihai-cli uses [ruff](https://github.com/astral-sh/ruff) for both linting and formatting.
+cihai-cli uses [Ruff](https://github.com/astral-sh/ruff) for both linting and formatting.
 
 ```console
 $ uv run ruff format .
@@ -22,7 +22,7 @@ $ uv run mypy
 
 ## Docstrings
 
-All public functions and methods use NumPy-style docstrings.
+All public functions and methods use [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html).
 
 ## Imports
 

diff --git a/docs/project/contributing.md b/docs/project/contributing.md
@@ -1,6 +1,6 @@
 # Contributing
 
-cihai-cli follows the cihai project's contributing guidelines.
+cihai-cli follows the [cihai project](https://cihai.git-pull.com/)'s contributing guidelines.
 
 See the [cihai contributing guide](https://cihai.git-pull.com/contributing/) for
 development setup, running tests, and submitting pull requests.

diff --git a/docs/project/index.md b/docs/project/index.md
@@ -16,7 +16,7 @@ How to get involved and submit changes.
 :::{grid-item-card} Code Style
 :link: code-style
 :link-type: doc
-Ruff, mypy, NumPy docstrings, import conventions.
+[Ruff](https://github.com/astral-sh/ruff), [mypy](https://mypy-lang.org/), [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html) docstrings, import conventions.
 :::
 
 :::{grid-item-card} Releasing

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,6 +1,6 @@
-(usage)=
+(quickstart)=
 
-# Usage
+# Quickstart
 
 cihai is designed to work out-of-the-box without configuration.
 
@@ -10,13 +10,13 @@ cihai is designed to work out-of-the-box without configuration.
 $ pip install --user cihai-cli
 ```
 
-Or manage it inside an existing project with uv:
+Or manage it inside an existing project with [uv]:
 
 ```console
 $ uv add cihai-cli
 ```
 
-Install the CLI as a user-wide tool with uv:
+Install the CLI as a user-wide tool with [uv]:
 
 ```console
 $ uv tool install cihai-cli
@@ -44,7 +44,12 @@ the 4th beta release of `1.10.0` before general availability.
 
   ```console
   $ pipx install --suffix=@next 'cihai-cli' --pip-args '\--pre' --force
-  // Usage: cihai@next info 好
+  ```
+
+  Run that prerelease command as `cihai@next`:
+
+  ```console
+  $ cihai@next info 好
   ```
 
 - [uv tool install][uv-tools]\:

diff --git a/src/cihai_cli/cli.py b/src/cihai_cli/cli.py
@@ -293,7 +293,7 @@ def setup_logger(
 
     Parameters
     ----------
-    logger : :py:class:`Logger`
+    logger : :class:`logging.Logger`
         Instance of logger, if one set up.
     """
     if not logger: