# 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](https://www.sphinx-doc.org/en/master/usage/configuration.html).

Here is `yardang`'s own configuration, in `pyproject.toml`

```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`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-project)

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

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

```toml
[project]
description = "your project description"
```

## [`author`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-author)

```toml
[project]
authors = "your project authors"
```

## [`version`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-version)

```toml
[project]
version = "0.1.0"
```

## [`theme`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme)

The Sphinx HTML theme to build with. Defaults to `fuma`.

```toml
[tool.yardang]
theme = "fuma"
```

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

- [`fuma`](https://github.com/python-project-templates/sphinx-fuma) (the default, always installed)
- [`furo`](https://github.com/pradyunsg/furo) (always installed)
- [`sphinxawesome_theme`](https://sphinxawesome.xyz/)
- [`shibuya`](https://shibuya.lepture.com/)
- [`klink`](https://github.com/pmorissette/klink)

`fuma` and `furo` are 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](#previewing-themes) below to compare them live.

### The `fuma` theme

[`sphinx-fuma`](https://github.com/python-project-templates/sphinx-fuma) is a
separate distribution, installed with `yardang`. 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](https://fumadocs.dev).

Search comes from
[`sphinx-searchlite`](https://github.com/python-project-templates/sphinx-searchlite),
which works with any Sphinx theme on its own.

See the [`sphinx-fuma` README](https://github.com/python-project-templates/sphinx-fuma)
for the full option list; the common ones are below.

```toml
[tool.yardang]
theme = "fuma"

[tool.yardang.html_theme_options]
github_url = "https://github.com/you/project"
toc_style = "clerk"
```

For `fuma`, Yardang infers `github_url` from GitHub URLs in `[project.urls]`.
It checks `Repository`, `Source`, `Source Code`, and `Homepage` first, in that
order, then remaining entries in declaration order. Labels are case-insensitive.
HTTP and HTTPS GitHub links are normalized to `https://github.com/owner/repo`,
removing `.git`, trailing slashes, subpaths, queries, and fragments.
An explicit `github_url` takes precedence; `github_url = ""` disables the link.
Other themes receive no inferred option.

Yardang also infers Fuma's `nav_links` from these case-insensitive project URL labels:

| Project URL label           | Link title |
| --------------------------- | ---------- |
| `Homepage`                  | Home       |
| `Documentation` (or `Docs`) | Docs       |

These links appear in the header and sidebar toolbar, in Home, Docs order.
`Documentation` takes precedence over `Docs`. Duplicate destinations, including
the GitHub link, are omitted; trailing slashes are ignored when comparing URLs.
Explicit `nav_links` replaces these defaults; `nav_links = []` disables them.
Missing URLs produce no link.

| 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 and sidebar toolbar links, as `[{title, url}]` or `"Title\|url, Title\|url"`.   |
| `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:

````markdown
```{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
```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:

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

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

#### Fonts

The theme ships [Geist](https://github.com/vercel/geist-font) and
[JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) 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:

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

```toml
[[tool.yardang.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`](https://github.com/python-project-templates/sphinx-searchlite)
and enabled by default for every theme. Bind to `/` or `Cmd-K`.

```toml
[tool.yardang]
use-search = false
```

The `fuma` theme renders the results in its own dialog; every other theme gets
the one `sphinx-searchlite` ships.

## `custom-css` / `custom-js`

Inject a custom stylesheet or script. The value may be a path or raw content.
When unset, `yardang` ships sensible defaults: the generic `custom.css` /
`custom.js` applies to every theme, and a bundled per-theme `{theme}.css` /
`{theme}.js` is appended when that theme has one, so theme rules win. This lets
each theme add its own tweaks — for example, `sphinxawesome_theme` and `shibuya`
hide the duplicate copy button, and `furo` gets the wide-content layout and the
`data-theme` rules that theme uses for light/dark. An explicit value replaces
both.

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

## Previewing themes

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

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

```bash
yardang preview --themes furo --themes shibuya
```

Install the optional themes with:

```bash
pip install yardang[themes]
```

When this runs in CI before the GitHub Pages deploy (as in `yardang`'s own
[`docs.yaml`](https://github.com/python-project-templates/yardang/blob/main/.github/workflows/docs.yaml)),
each theme is browsable live at a suburl of the published site:

- [`/_previews/furo/`](https://yardang.python-templates.dev/_previews/furo/)
- [`/_previews/sphinxawesome_theme/`](https://yardang.python-templates.dev/_previews/sphinxawesome_theme/)
- [`/_previews/shibuya/`](https://yardang.python-templates.dev/_previews/shibuya/)
- [`/_previews/fuma/`](https://yardang.python-templates.dev/_previews/fuma/)
- [`/_previews/klink/`](https://yardang.python-templates.dev/_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 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.

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

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

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

## `cname`

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

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

## `pages`

Pages to include in the contents tree.

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

## `use_autoapi`

Whether or not to use [Sphinx AutoAPI](https://sphinx-autoapi.readthedocs.io/en/latest/).
**NOTE:** it is recommended to manually autodoc your code.

```toml
[tool.yardang]
use-autoapi = true
```

## Sphinx Options

```toml
[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](https://myst-parser.readthedocs.io/en/latest/#)

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

## [Myst-NB](https://myst-nb.readthedocs.io/en/latest/#)

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

Notebooks can be included with:

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

  ../notebooks/example
```
````

An example follows:

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

  ../notebooks/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

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

```mermaid
%%{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])
```

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

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

> [!NOTE]
> Note `markdown` content

> [!TIP]
> Tip content

> [!IMPORTANT]
> Important content

> [!WARNING]
> Warning content

> [!CAUTION]
> Caution content

## Breathe/Doxygen Integration

Yardang provides integration with [Breathe](https://breathe.readthedocs.io/) for documenting C/C++ code using Doxygen. To use this feature, install yardang with the breathe extra:

```bash
pip install yardang[breathe]
```

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

### `projects`

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

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

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

### `domain-by-extension`

Map file extensions to Sphinx domains.

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

### `domain-by-file-pattern`

Map file patterns to Sphinx domains.

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

### `projects-source`

Configure source files for automatic Doxygen XML generation.

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

### `build-directory`

The directory where Doxygen XML is built.

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

### `default-members`

Default member visibility for doxygenclass directives.

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

### `show-define-initializer`

Show the initializer value for #define macros.

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

### `show-enumvalue-initializer`

Show the initializer value for enum values.

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

### `show-include`

Show the #include directive for documented entities.

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

### `implementation-filename-extensions`

List of file extensions considered as implementation files.

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

### `doxygen-config-options`

Additional Doxygen configuration options for auto-generated XML.

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

### `doxygen-aliases`

Doxygen aliases for custom commands.

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

### `use-project-refids`

Use project-qualified reference IDs to avoid conflicts.

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

### `order-parameters-first`

Order function parameters before other members in documentation.

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

### `separate-member-pages`

Generate separate pages for each class member.

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

### Complete Example

Here's a complete example configuration for a C++ project:

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

```markdown
# API Reference

## MyClass

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

## Functions

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

## Sphinx-Rust Integration

Yardang provides integration with [sphinxcontrib-rust](https://gitlab.com/munir0b0t/sphinxcontrib-rust) for documenting Rust code. To use this feature, install yardang with the rust extra:

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

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

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

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

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

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

### `strip-src`

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

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

### `generate-mode`

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

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

### Complete Example

Here's a complete example configuration for a Rust project:

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

```markdown
# API Reference

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

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

## Sphinx-JS Integration

Yardang provides integration with [sphinx-js](https://pypi.org/project/sphinx-js/) for documenting JavaScript and TypeScript code. To use this feature, you also need JSDoc or TypeDoc installed:

```bash
# 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.

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

Or as a single path:

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

### `js-language`

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

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

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

### `jsdoc-config-path`

Path to a JSDoc configuration file.

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

### `jsdoc-tsconfig-path`

Path to a TypeScript configuration file (for TypeDoc).

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

### `ts-type-bold`

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

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

### Complete Example

Here's a complete example configuration for a TypeScript project:

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

```markdown
# 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](https://github.com/liran-funaro/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:

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

```toml
[tool.yardang.wiki]
enabled = true
```

### `output-dir`

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

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

### `generate-sidebar`

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

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

### `generate-footer`

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

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

### `fix-links`

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

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

### `footer-docs-url`

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

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

### `footer-repo-url`

URL to the repository (for the footer).

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

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

### `markdown-anchor-sections`

Add anchors before each section. Defaults to `true`.

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

### `markdown-anchor-signatures`

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

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

### `markdown-bullet`

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

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

### Complete Example

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

```bash
yardang wiki
```

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

```bash
# 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`.

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