Wikidown

Home / Getting Started / Format

Format Specification

Wikidown's on-disk format is deliberately minimal: markdown pages, folder-based hierarchy, and .order navigation files. The goal of this specification is to ensure that a repository's documentation is equally readable by humans browsing the file system, AI agents using the CLI, and web-based renderers.

By enforcing these rules, Wikidown prevents the link rot and structural drift that typically plagues flat-file documentation.

The format is built first for GitHub and Jekyll (GitHub Pages): a project wiki that people and different LLM tools share, which renders correctly on github.com and publishes as a static site. It started from Azure DevOps wiki conventions and stays readable by Azure DevOps wikis, but those are no longer the reference point.

1. Page Files and Titles

Every page in the wiki is a standard Markdown file (.md). A page's title is its first # Heading, as plain text (link, code, and emphasis markup is stripped). That's the title readers and tools see: the site nav (in export-html and Jekyll's generated _data/navigation.yml), the export-pdf table of contents and bookmarks, and the title column of wikidown list and wikidown walk.

The file name is the page's path and URL: the title with spaces written as hyphens.

So when you create a page titled "Getting Started", the file is named Getting-Started.md (wikidown new --title "Getting Started" does this and writes the # Getting Started heading for you).

Every page should start with a # Heading. Because the title comes from the heading rather than the file name, it can contain characters a file name can't show: a page Attacks-Defense.md headed # Attacks & Defense is titled "Attacks & Defense", and # Move-1 keeps its hyphen. If a page has no # Heading, the file name is the fallback title, with hyphens shown as spaces. A folder with no page of its own shows its folder name.

2. Subpages and Hierarchy

Wikidown supports infinite nesting of pages. To create subpages for a given parent page, you must create a folder with the exact same base name as the parent page's file, located in the same directory.

This sibling-folder structure ensures that deleting or moving a parent page can easily include all of its children.

Every subpage folder's parent page should exist and should link every child in its body — see § Index pages below. WikiRepository.Write will happily create /Architecture/Data-Model even if /Architecture doesn't exist yet, which silently orphans the whole subtree: wikidown list / wikidown search / wikidown check-links' normal link scan all walk the wiki by descending from already-discovered pages, so a page whose parent was never created is invisible to all of them. check-links catches this specific case — see below.

3. Ordering

Alphabetical sorting is rarely the correct way to read documentation. Wikidown uses .order files to explicitly define the navigation hierarchy.

Every folder in the wiki (including the root /docs folder) should contain an .order file. This is a plain text file that lists the base names of the pages in that folder, one per line, from top to bottom.

Example .order file:

Getting-Started
Architecture
API-Reference

If a page exists in the folder but is not listed in the .order file, it is typically appended to the end of the list alphabetically by the renderer.

.order controls navigation-widget ordering only — it has no effect on GitHub's raw file view, so it's never a substitute for real body links. See § Index pages.

Internal links between wiki pages must be relative file paths, not "/"-rooted ones. GitHub resolves a "/"-rooted path like /Architecture/Data-Model against the repository root, not the wiki root (and a GitHub Pages project site resolves it against the domain root), so a link written that way 404s when the page is viewed on github.com or the published site. A relative path resolves correctly on GitHub, on Pages, and in Wikidown-aware renderers.

Write the link relative to the linking page's own folder, adjusted for depth, and include the .md extension:

Images and other repo assets follow the same rule, e.g. ![map](../.attachments/map.png). Keep them inside the wiki folder: a file elsewhere in the repo (../../assets/x.png, or /assets/x.png) isn't published by any route. wikidown check-links --fix copies such files into .attachments/from-repo/ and relinks them for you.

Run wikidown check-links (see CLI) to walk every page and verify that relative links and image references resolve to real files; by default it also flags any "/"-rooted link left in a page body that names something in the wiki — a title path like /Architecture/Data-Model or a root path to a file like /.attachments/map.png — and audits that every folder has a linked index page (§ Index pages). wikidown check-links --fix rewrites those "/"-rooted links relative to the linking page for you.

This rule only applies to links inside page bodies. Addressing a page through the CLI — e.g. wikidown read --path /Getting-Started/Format — still uses the title path, since that's a command argument rather than a rendered link.

check-links prints one line per issue:

page:line -> target  (reason)

What to do depends on the (reason):

After editing, re-run wikidown check-links to confirm the line is gone.

5. Index Pages

A folder's parent page is that folder's index — the entry point a reader lands on before descending into its children. Two invariants keep that entry point real rather than aspirational, both audited by wikidown check-links (pass --no-index-check to skip this pass):

A page's own breadcrumb links upward to its ancestors, but that's a different direction from this check: the breadcrumb doesn't help a reader on the parent page discover its children, and it doesn't verify the ancestor pages it links to actually exist — a folder missing its index page still gets a breadcrumb pointing at a .md file that isn't there, which is exactly the case index-page auditing is meant to catch.

Every page gets a one-line breadcrumb trail auto-injected as its first line, always leading back to /Home when the wiki has one:

[Home](../Home.md) / [Encounters](../Encounters.md) / The Sky Hunters <!-- wikidown:breadcrumb -->

This exists because GitHub's own file-path breadcrumb (shown above the raw file view) reflects the repository path — docs / Encounters / The-Sky-Hunters.md — not the wiki's page hierarchy or titles. Wikidown's breadcrumb is built purely from the page's own title chain instead: Home (if it exists) leads, then each further ancestor is a link (relative, per the convention above), and the current page's title is the final, unlinked segment — the same shape GitHub uses, just scoped to the wiki rather than the whole repo.

Key behavior:

7. Markdown Dialect

Wikidown relies on standard CommonMark. There are no proprietary macros or shortcodes required to render the core text. An MVP renderer only needs a standard markdown parser plus the title and file-name rules described above.