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

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). 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:

`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 sphinx-rust for documenting Rust code. To use this feature, install yardang with the sphinx-rust extra:

pip install yardang[sphinx-rust]

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

`crates`

A list of paths to Rust crates to document.

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

`doc-formats`

A dictionary mapping crate names to their docstring format. Valid values are "restructuredtext" (default) or "myst-nb" (for markdown docstrings).

[tool.yardang.sphinx-rust]
doc-formats = { mycrate = "myst-nb" }

Note: When using myst_nb as your Sphinx parser (which yardang uses by default), use "myst-nb" instead of "markdown" for markdown docstrings.

`viewcode`

Enable links to the source code for documented items. Defaults to true.

[tool.yardang.sphinx-rust]
viewcode = true

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 = [
"crates/mylib",
"crates/mylib-utils",
]
doc-formats = { mylib = "myst-nb",
"mylib-utils" = "restructuredtext" }
viewcode = true

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

# API Reference
## Document a Crate

\`\`\`{eval-rst}
.. rust:crate:: mylib

\`\`\`

## Document Individual Items

\`\`\`{eval-rst}
.. rust:struct:: mylib::MyStruct

\`\`\`

\`\`\`{eval-rst}
.. rust:enum:: mylib::MyEnum

\`\`\`

\`\`\`{eval-rst}
.. rust:function:: mylib::my_function

\`\`\`

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

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-formats

viewcode

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

Usage

LLM-friendly Documentation

enabled

description

`name`

`title`

`module`

`description`

`author`

`version`

`theme`

The `fuma` theme

`use-search`

`custom-css` / `custom-js`

`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-formats`

`viewcode`

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