Configuration

Configuration for yardang is driven from the pyproject.toml, either via standard sections like project or from the dedicated tool.yardang section. Each option below corresponds to the Sphinx configuration.

Here is yardangs own configuration, in pyproject.toml

[tool.yardang]
root = "docs/src/home.md"
cname = "yardang.python-templates.dev"
pages = [
    "docs/src/overview.md",
    "docs/src/installation.md",
    "docs/src/configuration.md",
]
use-autoapi = true

name

The project name is taken from the standard section, or from the cwd.

[project]
name = "your project name"

title

Same as name

module

The module title is taken from the name, replacing - with _, or from the cwd doing the same.

description

[project]
description = "your project description"

author

[project]
authors = "your project authors"

version

[project]
version = "0.1.0"

theme

The Sphinx HTML theme to build with. Defaults to furo.

[tool.yardang]
theme = "furo"

yardang ships per-theme defaults (sensible CSS tweaks, and an optional dependency) for the following themes:

• furo (the default, always installed)

• sphinxawesome_theme

• shibuya

• fuma

• klink

furo is always available; install the rest with pip install yardang[themes]. Any other installed Sphinx theme works too you just wont get the bundled defaults. See Previewing themes below to compare them live.

The fuma theme

sphinx-fuma is a separate distribution, installed by pip install yardang[themes]. It is a three-column layout page tree on the left, content in the middle, page headings on the right with a / or Cmd-K search dialog, light/dark modes that work without JavaScript, and a scroll-following heading indicator that traces the outline of the page. Its design system follows fumadocs.

Search comes from sphinx-searchlite, which works with any Sphinx theme on its own.

See the sphinx-fuma README for the full option list; the common ones are below.

[tool.yardang]
theme = "fuma"

[tool.yardang.sphinx]
html_theme_options = { github_url = "https://github.com/you/project", toc_style = "clerk" }

Content components

The theme adds a steps directive for numbered walkthroughs. Each heading inside it becomes a step on a numbered rail:

```{steps}
### Install the package

Pull it from your package index.

### Start the daemon

Run `acme serve`.
```

Tabbed code blocks use sphinx-design, which yardang already installs, and are styled to read as a single framed block:

::::{tab-set}
:::{tab-item} pip
```bash
pip install acme
```
:::
:::{tab-item} uv
```bash
uv add acme
```
:::
::::

A files directive renders a project layout from an ordinary nested list. A trailing / or having children marks an entry as a directory:

```{files}
- src/
  - acme/
    - `__init__.py`
    - server.py
- pyproject.toml
```

Wrap names in backticks when Markdown would otherwise reinterpret them, as with the leading underscores above.

Search

The dialog (/ or Cmd-K) reads a JSON index emitted alongside the build, so it works offline and needs no search service. Results are ranked with BM25 over two fields a match on a sections own heading outranks one on the title of the page it belongs to and the word you are still typing is matched as a prefix, so configu finds Configuration. Every word must match, so extra words narrow the results rather than widening them.

Set search = false to drop both the dialog and the index.

Colours

The greys are fixed; a preset only recolours --color-fd-primary, which drives the active sidebar entry, the table-of-contents highlight and its rail. amber is the grey-and-yellow pairing used on fumadocs own site.

[tool.yardang.sphinx.html_theme_options]
color_preset = "amber"

Anything in light_css_variables / dark_css_variables overrides the preset, so you can start from one and adjust:

[tool.yardang.sphinx.html_theme_options]
color_preset = "amber"
dark_css_variables = { "color-fd-background" = "#0a0a0a" }

Fonts

The theme ships Geist and JetBrains Mono as variable-weight Latin subsets (68 KB together), served from your own build so pages make no third-party requests. Both are SIL Open Font License 1.1; the licence texts are copied into _static/fonts/ alongside them.

Set fonts = "system" to skip the download and fall back to the system UI and monospace stacks.

Page icons

Give a page an icon in its front matter and it appears beside the entry in the sidebar tree:

---
icon: rocket
---

# Installation

Available names: album, blocks, book, bookmark, box, braces, bug, code, cog, compass, database, file, files, flask, folder, gauge, graduation-cap, layers, lightbulb, package, play, puzzle, rocket, server, settings, sparkles, terminal, test-tube, wrench, zap. Unknown names render nothing.

Navigator

sidebar_tabs adds a switcher between sections of the documentation. match is a docname prefix used to decide which entry is current; it defaults to the directory part of url.

[[tool.yardang.sphinx.html_theme_options.sidebar_tabs]]
title = "Guides"
url = "guides/index.html"
description = "Get up and running"
icon = "rocket"
match = "guides"

use-search

Client-side search, provided by sphinx-searchlite and enabled by default for every theme. Bind to / or Cmd-K.

[tool.yardang]
use-search = false

The fuma theme renders the results in its own dialog; every other theme gets the one sphinx-searchlite ships. Options such as searchlite_index_filename pass through [tool.yardang.sphinx] as normal.

custom-css / custom-js

Inject a custom stylesheet or script. The value may be a path or raw content. When unset, yardang looks for a bundled per-theme asset named {theme}.css / {theme}.js, then falls back to the generic custom.css / custom.js. This lets each theme ship sensible defaults for example, sphinxawesome_theme and shibuya hide the duplicate copy button.

[tool.yardang]
custom-css = "docs/_static/my.css"

Previewing themes

Build the docs once per theme to compare them side-by-side:

yardang preview

This renders the documentation into docs/html/_previews/<theme>/ for each bundled theme (furo, sphinxawesome_theme, shibuya, fuma, klink). Themes whose package is not installed are skipped. Restrict the set with --themes:

yardang preview --themes furo --themes shibuya

Install the optional themes with:

pip install yardang[themes]

When this runs in CI before the GitHub Pages deploy (as in yardangs own docs.yaml), each theme is browsable live at a suburl of the published site:

• /_previews/furo/

• /_previews/sphinxawesome_theme/

• /_previews/shibuya/

• /_previews/fuma/

• /_previews/klink/

source-dir

Optional existing Sphinx source directory, relative to the project directory. With this option, yardang build reads the existing source tree instead of generating an index.md from a README. It leaves source documents and .gitignore unchanged. Define navigation in the source documents; pages does not generate a toctree in this mode.

root names an existing document relative to source-dir and defaults to index.rst. Static and extra asset paths are also relative to source-dir. Yardang still generates its configuration from pyproject.toml; a conf.py inside the source directory is not loaded. The CLIs --source-dir overrides the configured directory.

Use yardang build --warning-is-error to fail the build on Sphinx warnings, for example in CI. Sphinx still processes all documents before returning a failure status.

[tool.yardang]
source-dir = "docs/source"
root = "index.rst"
use-autoapi = false
html-static-path = ["_static"]

To retain a Klink site, install klink (or yardang[themes]) and set theme = "klink". Yardang registers Klinks theme path, including for releases without a Sphinx theme entry point. Theme options go in [tool.yardang.html-theme-options]. Intersphinx inventories can be configured with explicit inventory URLs:

[tool.yardang]
extensions = ["sphinx.ext.intersphinx"]

[tool.yardang.intersphinx-mapping]
python = ["https://docs.python.org/3/", "https://docs.python.org/3/objects.inv"]

root

The root page to use, defaults to README.md.

[tool.yardang]
root = "docs/src/index.md"

cname

If set, will generate a CNAME file for GitHub Pages custom domains.

[tool.yardang]
cname = "yardang.python-templates.dev"

pages

Pages to include in the contents tree.

[tool.yardang]
pages = [
    "docs/src/overview.md",
    "docs/src/installation.md",
    "docs/src/configuration.md",
]

use_autoapi

Whether or not to use Sphinx AutoAPI. NOTE: it is recommended to manually autodoc your code.

[tool.yardang]
use-autoapi = true

Sphinx Options

[tool.yardang]
extensions = ["your_package.sphinx"]
html_theme_options = {}
html_static_path = []
html_css_files = []
html_js_files = []
source_suffix = []
exclude_patterns = []
language = "en"
pygments_style = "sphinx"

Myst

[tool.yardang]
myst_enable_extensions = ["amsmath", "colon_fence", "dollarmath", "html_image"]
myst_fence_as_directive = ["mermaid"]

Myst-NB

[tool.yardang]
nb_execution_mode = "off"
nb_execution_excludepatterns = []

Notebooks can be included with:

```{eval-rst}
.. toctree::
  :maxdepth: 1

  ../notebooks/example
```

An example follows:

Autodoc Pydantic arguments

Configuration for Autodoc Pydantic.

[tool.yardang]
autodoc_pydantic_model_show_config_summary = false
autodoc_pydantic_model_show_validator_summary = false
autodoc_pydantic_model_show_validator_members = false
autodoc_pydantic_field_list_validators = false
autodoc_pydantic_field_show_constraints = false
autodoc_pydantic_model_member_order = "bysource"
autodoc_pydantic_model_show_json = true
autodoc_pydantic_settings_show_json = false
autodoc_pydantic_model_show_field_summary = false

Mermaid

        graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
    

        %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%

graph TD
  A[\Replenish Value Add stock/] --->C
  B(Order product with Value Add) --->C
  C{Frequent process?} --->|Yes|D
  C --->|No|F
  D{New template?} --->|Yes|E
  D --->|No|G
  E(Create work order template) --->G
  F(Create work order) --->H
  G(Copy template to work order) --->I
  H(Add materials to work order processes) --->J
  I(Adjust material quantities) --->J
  J(Monitor work orders) --->K
  K{Material quantities in stock?} --->|No|L
  K --->|Yes|M
  L(Procure materials) --->M
  M(Change status to In Progress) --->N
  N{External Vendor to perform step?} --->|Yes|O
  N --->|No|P
  O(Add vendor costs) --->Q
  P[\Perform work order step/] --->R
  Q([Ship materials to Vendor]) --->S --->X
  R{Additional processing required?} --->|Yes|N
  R--->|No|T
  S[\Perform work order step/] --->U
  T(Receive final stock) --->V
  U(Receive product from vendor) --->W
  V(Ship product on order) --->Y
  W{Partial quantity received?} --->|Yes|X
  W --->|No|Z
  X[Create work order backorder] ---> J
  Y(Change status to complete) --->AA
  Z(Pay vendor invoice) --->R
  AA([Finish])
    

        zenuml
    title Demo
    Alice->John: Hello John, how are you?
    John->Alice: Great!
    Alice->John: See you later!
    

        mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid
    

GitHub Admonitions

GitHub admonitions are automatically translated to sphinx.

Breathe/Doxygen Integration

Yardang provides integration with Breathe for documenting C/C++ code using Doxygen. To use this feature, install yardang with the breathe extra:

pip install yardang[breathe]

All breathe configuration is under [tool.yardang.breathe].

projects

A dictionary mapping project names to their Doxygen XML output directories.

[tool.yardang.breathe]
projects = { myproject = "docs/doxygen/xml", another = "path/to/xml" }

default-project

The default project to use when no project is specified in breathe directives.

[tool.yardang.breathe]
default-project = "myproject"

domain-by-extension

Map file extensions to Sphinx domains.

[tool.yardang.breathe]
domain-by-extension = { "hpp" = "cpp", "h" = "cpp", "py" = "py" }

domain-by-file-pattern

Map file patterns to Sphinx domains.

[tool.yardang.breathe]
domain-by-file-pattern = { "*.hpp" = "cpp" }

projects-source

Configure source files for automatic Doxygen XML generation.

[tool.yardang.breathe]
projects-source = { auto = ["src", ["file1.hpp", "file2.hpp"]] }

build-directory

The directory where Doxygen XML is built.

[tool.yardang.breathe]
build-directory = "build/doxygen"

default-members

Default member visibility for doxygenclass directives.

[tool.yardang.breathe]
default-members = ["members", "protected-members", "private-members"]

show-define-initializer

Show the initializer value for #define macros.

[tool.yardang.breathe]
show-define-initializer = true

show-enumvalue-initializer

Show the initializer value for enum values.

[tool.yardang.breathe]
show-enumvalue-initializer = true

show-include

Show the #include directive for documented entities.

[tool.yardang.breathe]
show-include = true

implementation-filename-extensions

List of file extensions considered as implementation files.

[tool.yardang.breathe]
implementation-filename-extensions = [".c", ".cc", ".cpp"]

doxygen-config-options

Additional Doxygen configuration options for auto-generated XML.

[tool.yardang.breathe]
doxygen-config-options = { EXTRACT_ALL = "YES", QUIET = "YES" }

doxygen-aliases

Doxygen aliases for custom commands.

[tool.yardang.breathe]
doxygen-aliases = { "myalias" = "Custom documentation text" }

use-project-refids

Use project-qualified reference IDs to avoid conflicts.

[tool.yardang.breathe]
use-project-refids = true

order-parameters-first

Order function parameters before other members in documentation.

[tool.yardang.breathe]
order-parameters-first = true

separate-member-pages

Generate separate pages for each class member.

[tool.yardang.breathe]
separate-member-pages = false

Complete Example

Heres a complete example configuration for a C++ project:

[tool.yardang]
title = "My C++ Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.breathe]
projects = { mylib = "docs/doxygen/xml" }
default-project = "mylib"
domain-by-extension = { "hpp" = "cpp", "cpp" = "cpp", "h" = "cpp" }
show-define-initializer = true
show-enumvalue-initializer = true
show-include = true
use-project-refids = true

Then in your documentation files, you can use breathe directives:

# API Reference

## MyClass

\`\`\`{doxygenclass} MyNamespace::MyClass
:members:
:protected-members:
\`\`\`

## Functions

\`\`\`{doxygenfunction} MyNamespace::myFunction
\`\`\`

Sphinx-Rust Integration

Yardang provides integration with sphinxcontrib-rust for documenting Rust code. To use this feature, install yardang with the rust extra:

pip install yardang[rust]

This extra is GPL-3.0 licensed, unlike yardang itself, which is Apache-2.0.

It also relies on a sphinx-rustdocgen binary, which the Python package only builds as a side effect of compiling its sdist. Installing from a cached wheel skips that step, so install the binary explicitly to be sure it is present:

cargo install sphinx-rustdocgen

All configuration is under [tool.yardang.sphinx-rust].

crates

A mapping of crate name to crate directory. Every crate listed here is scanned and documented.

[tool.yardang.sphinx-rust]
crates = { crate1 = "path/to/crate1", crate2 = "path/to/crate2" }

doc-dir

Where the generated pages are written, relative to the documentation root. Defaults to "api", producing api/<crate>/lib.md for each crate.

[tool.yardang.sphinx-rust]
doc-dir = "api"

rustdoc-fmt

The markup used inside Rust doc comments, either "md" or "rst". Defaults to "md", since Rust doc comments are conventionally markdown. Accepts a single value for all crates, or a per-crate mapping.

[tool.yardang.sphinx-rust]
rustdoc-fmt = { mycrate = "rst" }

visibility

The minimum item visibility to document. Defaults to "pub"; use "crate" or "pvt" to include less visible items.

[tool.yardang.sphinx-rust]
visibility = "pub"

strip-src

Strip the src directory from generated paths. Defaults to true.

[tool.yardang.sphinx-rust]
strip-src = true

generate-mode

When to regenerate pages: "changed" (default), "always", or "skip".

[tool.yardang.sphinx-rust]
generate-mode = "changed"

Complete Example

Heres a complete example configuration for a Rust project:

[tool.yardang]
title = "My Rust Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.sphinx-rust]
crates = { mylib = "crates/mylib", mylib-utils = "crates/mylib-utils" }
doc-dir = "api"
rustdoc-fmt = { mylib-utils = "rst" }

The pages are generated for you, so your documentation files only need a toctree entry pointing at them:

# API Reference

\`\`\`{toctree}
:maxdepth: 2

/api/mylib/lib
/api/mylib-utils/lib
\`\`\`

Sphinx-JS Integration

Yardang provides integration with sphinx-js for documenting JavaScript and TypeScript code. To use this feature, you also need JSDoc or TypeDoc installed:

# For JavaScript projects
npm install jsdoc

# For TypeScript projects
npm install typedoc

All sphinx-js configuration is under [tool.yardang.sphinx-js].

js-source-path

A list of directories containing your JS/TS source files, relative to the project root. This is required to enable sphinx-js.

[tool.yardang.sphinx-js]
js-source-path = ["src", "lib"]

Or as a single path:

[tool.yardang.sphinx-js]
js-source-path = "src"

js-language

The language of your source files. Use "javascript" (default) or "typescript".

[tool.yardang.sphinx-js]
js-language = "typescript"

root-for-relative-js-paths

The root directory for resolving relative JS entity paths. Required if you have multiple js-source-path entries.

[tool.yardang.sphinx-js]
root-for-relative-js-paths = "src"

jsdoc-config-path

Path to a JSDoc configuration file.

[tool.yardang.sphinx-js]
jsdoc-config-path = "jsdoc.json"

jsdoc-tsconfig-path

Path to a TypeScript configuration file (for TypeDoc).

[tool.yardang.sphinx-js]
jsdoc-tsconfig-path = "tsconfig.json"

ts-type-bold

Make TypeScript types bold in the output. Defaults to false.

[tool.yardang.sphinx-js]
ts-type-bold = true

Complete Example

Heres a complete example configuration for a TypeScript project:

[tool.yardang]
title = "My TypeScript Library"
root = "docs/index.md"
pages = ["docs/api.md", "docs/examples.md"]
use-autoapi = false

[tool.yardang.sphinx-js]
js-language = "typescript"
js-source-path = ["src"]
jsdoc-tsconfig-path = "tsconfig.json"
ts-type-bold = true

Then in your documentation files, you can use sphinx-js directives:

# API Reference

## Functions

\`\`\`{js:autofunction} myFunction
\`\`\`

## Classes

\`\`\`{js:autoclass} MyClass
:members:
\`\`\`

## Modules

\`\`\`{js:automodule} myModule
\`\`\`

GitHub Wiki Integration

Yardang can generate GitHub Wiki compatible markdown documentation using sphinx-markdown-builder. This allows you to publish your documentation to a GitHub Wiki in addition to (or instead of) a static HTML site.

To generate wiki output, use the yardang wiki command instead of yardang build.

Wiki output is configured in the [tool.yardang.wiki] section:

[tool.yardang.wiki]
enabled = true
output-dir = "docs/wiki"
generate-sidebar = true
generate-footer = true
fix-links = true
footer-docs-url = "https://your-project.dev"
footer-repo-url = "https://github.com/your-org/your-project"
markdown-flavor = "github"

enabled

Enable the markdown builder extension. Must be true to use yardang wiki. Defaults to false.

[tool.yardang.wiki]
enabled = true

output-dir

Output directory for the generated markdown files. Defaults to "docs/wiki".

[tool.yardang.wiki]
output-dir = "docs/wiki"

generate-sidebar

Generate a _Sidebar.md file for wiki navigation. Defaults to true.

[tool.yardang.wiki]
generate-sidebar = true

generate-footer

Generate a _Footer.md file with links to docs and repo. Defaults to true.

[tool.yardang.wiki]
generate-footer = true

fix-links

Fix internal markdown links for GitHub Wiki compatibility. Defaults to true.

[tool.yardang.wiki]
fix-links = true

footer-docs-url

URL to the full documentation site (for the footer).

[tool.yardang.wiki]
footer-docs-url = "https://your-project.dev"

footer-repo-url

URL to the repository (for the footer).

[tool.yardang.wiki]
footer-repo-url = "https://github.com/your-org/your-project"

markdown-flavor

Markdown flavor to use. Set to "github" for GitHub-flavored markdown. Defaults to "github".

[tool.yardang.wiki]
markdown-flavor = "github"

markdown-anchor-sections

Add anchors before each section. Defaults to true.

[tool.yardang.wiki]
markdown-anchor-sections = true

markdown-anchor-signatures

Add anchors before each function/class signature. Defaults to true.

[tool.yardang.wiki]
markdown-anchor-signatures = true

markdown-bullet

Bullet character to use for lists. Defaults to "-".

[tool.yardang.wiki]
markdown-bullet = "-"

Complete Example

[tool.yardang]
title = "My Project"
root = "docs/index.md"
pages = ["docs/overview.md", "docs/api.md"]

[tool.yardang.wiki]
enabled = true
output-dir = "docs/wiki"
generate-sidebar = true
generate-footer = true
footer-docs-url = "https://myproject.dev"
footer-repo-url = "https://github.com/myorg/myproject"
markdown-flavor = "github"

Usage

Generate GitHub Wiki output:

yardang wiki

The output will be in the docs/wiki/ directory (or the configured output directory). To publish to your GitHub Wiki:

# Clone your wiki repository
git clone https://github.com/YOUR-ORG/YOUR-REPO.wiki.git

# Copy the generated markdown files
cp -r docs/wiki/* YOUR-REPO.wiki/

# Commit and push
cd YOUR-REPO.wiki
git add .
git commit -m "Update wiki documentation"
git push

The generated wiki includes:

• Home.md - The main landing page (converted from index.md)

• _Sidebar.md - Navigation sidebar with links to all pages

• _Footer.md - Footer with links to documentation and repository

• All documentation pages converted to GitHub-flavored markdown

LLM-friendly Documentation

The [tool.yardang.llms] section controls LLM-friendly output generated by yardang build.

[tool.yardang.llms]
enabled = true
description = "Documentation for My Project"
full-build = true

When enabled, the HTML output directory also contains:

• llms.txt: Project description and links to pages reachable from the root toctree.

• llms-full.txt: Combined content of all linked pages when full-build is enabled.

• *.html.md: Markdown representation of each linked HTML page.

enabled

Enables LLM-friendly output. Defaults to false.

description

Sets the project summary in llms.txt. Defaults to the project description.

full-build

Generates llms-full.txt and links it from llms.txt. Defaults to true.