Documentation files

Markdown committed next to the code is rendered by Kimtu in one consistent style, ordered by your mkdocs.yml when there is one.

Attaching markdown to a component

Kimtu renders markdown itself rather than hosting a build output, so every team's documentation looks the same. Point docs at the directory your markdown lives in — one path, not a list. A component can override it with a path of its own, which claims the files underneath for that component.

Documentation is sent only when you tick the box on the prompt screen. Without it, kimtu.yaml is the only file that leaves your machine.

kimtu.yaml

# the repository's documentation directory
docs: ./docs

components:
  # a component can override it with a path of its own,
  # which claims the markdown underneath it
  - id: invoicing-job
    name: Invoicing Job
    type: job
    docs: ./docs/invoicing-job

What no component claims goes to the component sharing the repository's id — the service a repository is named for, beside its own database. A document's own front matter overrides both: a kimtu: block can name the component it belongs to, a category of technical or business, and a title.

Ordering pages

If the directory contains an mkdocs.yml, its nav drives the tree in the left rail — including the group labels and any depth of nesting. Without one, pages are listed in folder order and titled from their first heading.

docs/mkdocs.yml

nav:
  - Overview: overview.md
  - Documentation:
      - Invoice lifecycle: lifecycle.md
      - Retries and dunning: retries.md
  - Guides:
      - Tax and rounding:
          - Rounding rules: guides/tax/rounding.md
          - VAT handling: guides/tax/vat.md
  - Decisions:
      - ADR-014 Idempotency keys: decisions/014.md

A file named overview.md — or index.md, or README.md — replaces the generated overview for that component. Everything else is added as a page under the group it sits in.

MkDocs itself is never run. mkdocs.yml is read as data, and only nav and docs_dir are read from it. A page named in nav that was not uploaded is dropped, as MkDocs does; if every entry misses, the rail falls back to folder order and the page says so.

What renders

Kimtu renders the markdown itself, on the server, in its own design system. MkDocs is a Python site generator: running it would put Python in the stack and execute uploaded configuration, which mkdocs.yml can ask for. What teams use it for is supportable without running it.

nav: — order, titles, sections, nestingRendered: Drives the rail, with its group labels and any depth of nesting. Without an mkdocs.yml, folders and filenames do instead, and the page says which it used.
docs_dirRendered: Read, and checked against the manifest's docs:. A file outside every declared documentation path is dropped at import and named in the response.
Tables, fenced code, footnotes, toc anchorsRendered: Tables keep their column alignment and scroll within the measure rather than widening the page. Headings get the same anchors MkDocs's toc would give them, so a link to a section still lands. Code is not colourised.
Admonitions !!! note "Title", collapsible ??? noteRendered: Rendered as Kimtu's note block, its icon coloured by the kind. A collapsible one is a native details, so it opens without script.
Content tabs === "Tab", code block titlesRendered: Tabs render as tabs, and a fenced block's title= becomes the filename on its header.
Mermaid fencesIn the browser: Drawn in your browser — the one part of a documentation page that runs any script at all. Everything else is rendered on the server.
attr_list { .class }Stripped: The attributes go and the text stays. Pages render in Kimtu's design system, so a class from your own theme would have nothing to match.
Raw HTML in markdownStripped: Its text shows and its tags never render; script and style go entirely. These files are uploads served from Kimtu's own origin, so none of it can be trusted to run.
Content-generating plugins: mkdocstrings, macros, snippet includesNot run: They need source code, which Kimtu never receives, or they execute templates. The page shows a note naming what was skipped rather than a gap.
Themes, custom CSS and JS, overridesNot run: Pages render in Kimtu's design system, so every team's documentation reads the same way.

Python-Markdown and CommonMark disagree on a few edge cases — a nested list indented by two spaces rather than four, most often — so a page can render slightly differently here from your own site.

Images are the one thing worth knowing about in advance: they are never uploaded, so an image shows its alt text with a mark in its place and the sentence around it still reads.