docs src configuration

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 yardang’s 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 won’t 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" }

Option	Default	Description
`layout`	`docs`	`docs` puts the header beside the sidebar; `notebook` spans it across the top.
`toc_style`	`normal`	`clerk` dims headings away from the current one.
`color_preset`	`neutral`	Accent colour: `neutral`, `amber`, `blue`, `emerald`, `purple`, `rose`.
`fonts`	`bundled`	`system` skips the bundled webfonts and uses the system stack.
`search`	`true`	Enables the search dialog and its index.
`sidebar_hide_name`	`false`	Hides the project name next to the logo.
`default_open_level`	`1`	Sidebar folder depth expanded by default.
`github_url`	—	Adds a GitHub link, and an “Edit this page” link.
`edit_page_url_template`	—	Overrides the edit link, e.g. `https://host/edit/main/{filename}`.
`nav_links`	—	Header links, as `[{title, url}]` or `"Title
`sidebar_tabs`	—	Navigator entries under the search box, as `[{title, url, description, icon, match}]`.
`announcement`	—	Banner text shown above the header.
`footer_text`	—	Extra line in the footer.
`light_css_variables` / `dark_css_variables`	—	CSS custom property overrides, e.g. `{ "color-fd-primary" = "#e11d48" }`.

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:

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

::: :::{tab-item} uv

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:

```markdown

```{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 section’s 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.

```toml
[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 yardang’s own docs.yaml), each theme is browsable live at a suburl of the published site:

`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 CLI’s --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 Klink’s 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:

- [Example Notebook](example)

## [Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html) arguments

[Configuration for Autodoc Pydantic](https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html).

```toml
[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

GitHub Admonitions

GitHub admonitions are automatically translated to sphinx.

NOTE

Note markdown content

TIP

Tip content

IMPORTANT

Important content

WARNING

Warning content

CAUTION

Caution content

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

Here’s 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

Here’s 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

Here’s 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.

📚 Full Documentation | 💻 Repository

Uh oh!

docs src configuration

Configuration

name

title

module

description

author

version

theme

The fuma theme

Content components

Fonts

Page icons

Navigator

use-search

custom-css / custom-js

Previewing themes

source-dir

root

cname

pages

use_autoapi

Sphinx Options

Myst

Myst-NB

Mermaid

GitHub Admonitions

NOTE

TIP

IMPORTANT

WARNING

CAUTION

Breathe/Doxygen Integration

projects

default-project

domain-by-extension

domain-by-file-pattern

projects-source

build-directory

default-members

show-define-initializer

show-enumvalue-initializer

show-include

implementation-filename-extensions

doxygen-config-options

doxygen-aliases

use-project-refids

order-parameters-first

separate-member-pages

Complete Example

Sphinx-Rust Integration

crates

doc-dir

rustdoc-fmt

visibility

strip-src

generate-mode

Complete Example

Sphinx-JS Integration

js-source-path

js-language

root-for-relative-js-paths

jsdoc-config-path

jsdoc-tsconfig-path

ts-type-bold

Complete Example

GitHub Wiki Integration

enabled

output-dir

generate-sidebar

generate-footer

fix-links

footer-docs-url

footer-repo-url

markdown-flavor

markdown-anchor-sections

markdown-anchor-signatures

markdown-bullet

Complete Example

`name`

`title`

`module`

`description`

`author`

`version`

`theme`

The `fuma` theme

`use-search`

`custom-css` / `custom-js`

`source-dir`

`root`

`cname`

`pages`

`use_autoapi`

`projects`

`default-project`

`domain-by-extension`

`domain-by-file-pattern`

`projects-source`

`build-directory`

`default-members`

`show-define-initializer`

`show-enumvalue-initializer`

`show-include`

`implementation-filename-extensions`

`doxygen-config-options`

`doxygen-aliases`

`use-project-refids`

`order-parameters-first`

`separate-member-pages`

`crates`

`doc-dir`

`rustdoc-fmt`

`visibility`

`strip-src`

`generate-mode`

`js-source-path`

`js-language`

`root-for-relative-js-paths`

`jsdoc-config-path`

`jsdoc-tsconfig-path`

`ts-type-bold`

`enabled`

`output-dir`

`generate-sidebar`

`generate-footer`

`fix-links`

`footer-docs-url`

`footer-repo-url`

`markdown-flavor`

`markdown-anchor-sections`

`markdown-anchor-signatures`

`markdown-bullet`

`enabled`

`description`

`full-build`