DOCS0 Documentation #

DOCS0 turns a folder of Markdown files into one self-contained HTML file — navigation, styles, scripts, images and diagrams included. Email it, attach it to a ticket, or publish it to GitHub Pages. No server, no build chain, no config.

1. Why DOCS0#

Most documentation tools want a framework, a config file and a dev server. DOCS0 wants a folder.

2. How it works#

flowchart LR
  A[docs/ folder] -->|walk| B(Page tree)
  B -->|marked + highlight.js| C(HTML pages)
  C --> D{Inline assets}
  D -->|images → data: URIs| E[index.html]
  D -->|CSS + JS + mermaid| E
  E -->|open=true| F([Browser])
  E -->|open=false| G([GitHub Pages])
  A -.->|save, with --watch| B

Every page is rendered at build time. In the browser a tiny hash router shows one page at a time, so links like Quick Start work without a server.

3. Where to next#

• New here? Start with Getting Started.
• Writing docs? Read Writing Docs and browse the Markdown Showcase.
• Need the flags? See the CLI Reference.

Getting Started #

Welcome! This section takes you from zero to a published documentation site in about five minutes.

Prerequisites#

• Node.js 20 or newer
• A folder containing at least one .md file

The path#

journey
  title From Markdown to published docs
  section Write
    Create docs folder: 5: You
    Add Markdown files: 4: You
  section Build
    Run npx @tforster/docs0: 5: DOCS0
    Preview in browser: 5: You
  section Ship
    Add GitHub Action: 4: You
    Docs on GitHub Pages: 5: GitHub

1. Installation — optional; npx works without installing anything
2. Quick Start — build and view your first site

Installation#

No install: npx#

The fastest route. npx downloads DOCS0 into a cache and runs it:

npx @tforster/docs0 ./docs

Global install#

npm install -g @tforster/docs0
docs0 ./docs

Project dev dependency#

Pin the version alongside your code so every contributor and CI run uses the same build:

npm install --save-dev @tforster/docs0

{
  "scripts": {
    "docs": "docs0 docs",
    "docs:watch": "docs0 docs --watch",
    "docs:build": "docs0 docs --out=_site/index.html --open=false"
  }
}

Verifying#

$ docs0 --help
Usage: docs0 <docs-root> [--out=docs.html] [--open=false]

Quick Start #

1. Create a docs folder#

mkdir -p docs/guides
cat > docs/README.md <<'MD'
# My Project

Welcome to the docs.
MD
cat > docs/guides/setup.md <<'MD'
# Setup

## Table of Contents <!-- omit in toc -->

- [Install](#install)

## Install

Run the installer.
MD

The resulting tree:

docs/
├── README.md          → home page
└── guides/
    └── setup.md       → Guides › Setup

2. Build and open#

npx @tforster/docs0 docs

DOCS0 writes the site to <os temp>/docs0/<project>-<hash>/index.html and opens it in your default browser. Your repo stays clean, and re-running refreshes the same file.

3. Watch while you write#

npx @tforster/docs0 docs --watch

DOCS0 builds and opens the site once, then keeps running. Each time you save a .md file or an image, it re-renders only the affected pages (usually in tens of milliseconds) and rewrites the same file. Refresh the tab to see the change. Press Ctrl-C to stop. See Watch mode.

4. Build without opening#

Perfect for CI:

npx @tforster/docs0 docs --out=_site/index.html --open=false

5. Check for broken links#

The build summary counts problems such as broken .md links and missing images:

   13 pages from /home/me/project/docs · 3190 KB · 160 ms · 2 warnings (-v to list)

Add -v (or --verbose) to list each one with its file:

npx @tforster/docs0 docs -v

6. Share it#

The output file is fully self-contained. Attach it to an email, drop it in Slack, or publish it — see Publishing to GitHub Pages.

Writing Docs #

DOCS0 has no config file. Everything is driven by conventions in your folder and files.

Folder structure becomes navigation#

The folder tree below your docs root is the left nav:

docs/
├── README.md                    # Home
├── 01-getting-started/
│   ├── README.md                # landing page; folder shows as "Getting Started"
│   ├── 01-installation.md
│   └── 02-quick-start.md
├── 02-guides/                   # no README → label derived from folder name: "Guides"
│   └── 01-writing-docs.md
└── assets/                      # no .md files → not shown in nav
    └── banner.png

Ordering with numeric prefixes#

In every folder the landing page comes first, then loose files, then sub-folders. Each group sorts by name using natural (numeric) ordering, so 2- comes before 10-. Prefixes such as 01-, 02_ or 3. are stripped from labels and from URLs: 02-guides/01-writing-docs.md is served at #/guides/writing-docs.

Landing pages#

A README.md (or index.md) inside a folder becomes that folder's landing page. Clicking the folder name opens it. The README.md at the docs root is the home page.

Folder labels come from the folder name, not the README title — READMEs often share a title (think several # Explanation pages in a Diátaxis tree) while folder names are unique. When the README title contains the folder name, its casing is kept: iam/ with # IAM — Explanation shows as IAM.

Page titles#

The first # heading is the page title shown in the nav. Files without one fall back to a tidied filename: 03-api_keys.md → Api keys.

Tables of contents become the sidebar#

Add a list under this exact heading:

## Table of Contents <!-- omit in toc -->

- [Install](#install)
  - [From npm](#from-npm)
- [Configure](#configure)

DOCS0 removes it from the page body and renders it as the sticky On this page sidebar, highlighting the section you are reading. The <!-- omit in toc --> comment keeps tools like Markdown All in One from listing the TOC heading in itself.

Linking between pages#

Use ordinary relative links — the same ones that work on GitHub:

Try one: jump to the flags section of the CLI reference.

What gets ignored#

• Files and folders starting with .
• node_modules
• Folders that contain no .md files (they can still hold images)

Markdown Showcase #

A tour of the GitHub Flavored Markdown (GFM) that DOCS0 renders. View this file's source next to the rendered page to see how each element is written.

Text formatting#

You can write bold, italic, both, strikethrough and inline code. Autolinks such as https://github.com work, as do inline links and reference-style links like highlight.js.

Press Ctrl + K to highlight things with inline HTML.

Lists#

1. Ordered lists
2. Keep their numbering
   • and nest
   • unordered items
     1. to any depth
3. Back to the top level

• Unordered item
• Another item with a longer line of text that wraps naturally when the viewport is narrow, demonstrating comfortable line length and spacing for reading.

Task lists#

• Walk the docs tree
• Render Markdown with marked
• Inline images as data URIs
• Full-text search (coming soon)

Callouts#

Code#

Code blocks are highlighted at build time, so there is no highlighting JavaScript in the output. Hover a block to copy it.

JavaScript#

/**
 * Resolves a hash route into a page and optional section.
 * @param {string} hash - e.g. "#/guides/diagrams/flowcharts"
 */
export function resolve(hash, routes) {
  const path = decodeURIComponent(hash).replace(/^#\/?/, "");
  if (routes.has(path)) return { page: path, anchor: "" };
  const i = path.lastIndexOf("/");
  return { page: path.slice(0, i), anchor: path.slice(i + 1) };
}

Python#

from pathlib import Path

def pages(root: Path) -> list[Path]:
    """Every markdown file below root, in natural order."""
    return sorted(p for p in root.rglob("*.md") if not p.name.startswith("."))

if __name__ == "__main__":
    for page in pages(Path("docs")):
        print(f"{page.relative_to('docs')}")

Shell and config#

#!/usr/bin/env bash
set -euo pipefail
npx @tforster/docs0 docs --out="build/docs.html" --open=false
echo "Built $(du -h build/docs.html | cut -f1) of docs"

# .github/workflows/docs.yml (excerpt)
on:
  push:
    branches: [main]
    paths: ["docs/**"]

:root[data-theme="dark"] {
  --bg: #0d1117;
  --accent: #58a6ff;
}

Diffs#

- const html = marked.parse(md);
+ const html = applyCallouts(marked.parser(tokens));

Unknown or missing languages render as plain, escaped text:

No language specified — <b>tags</b> are shown literally.

Tables#

Columns honour :--- (left), :---: (centre) and ---: (right) alignment.

Images#

Local images are embedded as data: URIs so the output stays a single file. Both SVG and raster formats work:

Remote images are left as links and load normally when online:

Block quotes#

Documentation is a love letter that you write to your future self.

— Damian Conway

Raw HTML#

Inline HTML is passed through, which gives you collapsible sections for free:

Diagrams #

Fenced code blocks tagged mermaid are rendered as diagrams. They follow the light/dark theme and re-render when you toggle it.

Flowchart#

```mermaid
flowchart TD
  Start([docs0 docs]) --> Walk[Walk tree]
```

flowchart TD
  Start([docs0 docs]) --> Walk[Walk tree]
  Walk --> Lex[Lex each .md]
  Lex --> Titles[Derive titles & routes]
  Titles --> Render[Render pages]
  Render --> Mermaid{Any mermaid?}
  Mermaid -->|yes| Embed[Embed fallback runtime]
  Mermaid -->|no| Write
  Embed --> Write[Write docs.html]
  Write --> Open{open=false?}
  Open -->|no| Browser([Open browser])
  Open -->|yes| Done([Exit])

Sequence diagram#

sequenceDiagram
  actor Reader
  participant Browser
  participant Router as DOCS0 router
  participant Mermaid
  Reader->>Browser: Click "Diagrams" in nav
  Browser->>Router: hashchange #/guides/diagrams
  Router->>Router: Hide old page, show new page
  Router->>Mermaid: render(pending diagrams)
  Mermaid-->>Router: SVG
  Router-->>Reader: Page with diagrams

Class diagram#

classDiagram
  class Page {
    +string file
    +string rel
    +string route
    +string title
    +Token[] tokens
  }
  class DirNode {
    +string name
    +Page landing
    +children
  }
  DirNode "1" o-- "*" Page : contains
  DirNode "1" o-- "*" DirNode : contains

State diagram#

stateDiagram-v2
  [*] --> idle
  idle --> loading: page has diagrams
  loading --> ready: CDN loaded
  loading --> ready: embedded fallback
  loading --> failed: no runtime
  ready --> ready: theme toggled / re-render
  failed --> [*]

Entity relationship#

erDiagram
  FOLDER ||--o{ FOLDER : contains
  FOLDER ||--o{ PAGE : contains
  FOLDER |o--o| PAGE : "landing page"
  PAGE ||--o{ HEADING : has
  PAGE ||--o{ IMAGE : embeds

Gantt chart#

gantt
  title DOCS0 roadmap
  dateFormat YYYY-MM-DD
  section Core
    Tree to nav          :done, 2026-09-01, 7d
    Sticky TOC           :done, 2026-09-05, 5d
    Single-file output   :done, 2026-09-08, 6d
  section Next
    Full-text search     :active, 2026-10-01, 14d
    Minified output      :2026-10-15, 7d

Pie chart#

pie title Where the bytes go (typical docs.html)
  "Mermaid fallback" : 2900
  "Highlight.js themes" : 3
  "DOCS0 CSS + JS" : 25
  "Your content" : 120

Git graph#

gitGraph
  commit id: "init"
  branch docs
  commit id: "add docs tree"
  commit id: "add diagrams"
  checkout main
  merge docs
  commit id: "v0.1.0" tag: "v0.1.0"

How loading works#

Publishing to GitHub Pages #

Because the output is a single file, publishing is just "build, then upload one file".

The workflow#

Save as .github/workflows/docs.yml:

name: Docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Restore file dates
        run: git ls-files -z docs | while IFS= read -r -d '' f; do touch -d "$(git log -1 --format=%cI -- "$f")" "$f"; done
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - id: docs
        run: npx --yes @tforster/docs0 docs
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ steps.docs.outputs.dir }}
      - id: deployment
        uses: actions/deploy-pages@v4

sequenceDiagram
  participant Dev as Developer
  participant GH as GitHub
  participant Runner as Actions runner
  participant Pages as GitHub Pages
  Dev->>GH: push to main
  GH->>Runner: trigger Docs workflow
  Runner->>Runner: docs0 docs → /tmp/docs0/…/index.html
  Runner->>Pages: upload that folder
  Pages-->>Dev: https://you.github.io/repo/

Enable Pages#

1. Open Settings → Pages in your repository.
2. Under Build and deployment → Source, choose GitHub Actions.
3. Push to main.

Custom output locations#

CLI #

Synopsis#

docs0 <docs-root> [--out=file.html] [--open=false] [-w|--watch] [-v|--verbose] [--workers=N]

Arguments#

Flags#

Flags may be written with or without the leading --.

Environment#

Exit codes#

Output#

$ docs0 docs --open=false

📚  DOCS0 → /tmp/docs0/my-project-3f9a1c2e/index.html
   13 pages from /home/me/project/docs · 3190 KB · 85 ms

When there are warnings and --verbose is off, the summary ends with · 3 warnings (-v to list).

Without --out, the file goes to <os temp>/docs0/<project>-<hash>/index.html: <project> comes from the nearest package.json name (or the folder name) and <hash> from the absolute docs path. Nothing is written into your repo, re-running overwrites the same file, and different projects never collide. The temp folder is /tmp on Linux, $TMPDIR on macOS, %TEMP% on Windows (also /tmp on GitHub-hosted Linux runners).

Warnings (broken image paths, broken links, links that leave the docs tree) are printed to stderr but do not fail the build.

Watch mode#

$ docs0 docs --watch

📚  DOCS0 → /tmp/docs0/my-project-3f9a1c2e/index.html
   13 pages from /home/me/project/docs · 3190 KB · 160 ms

   Watching /home/me/project/docs · Ctrl-C to stop

↻  14:02:11  1 page re-rendered · 24 ms

After the first build DOCS0 keeps watching the docs root. Each save rewrites the same output file, so refresh the open tab to see the change. Only the pages a change affects are re-rendered:

The nav, pager and folder labels are rebuilt every time, so a changed title shows up everywhere. A burst of saves (editors often write several times) is debounced into one rebuild. If a build fails the error is printed, the last good file is kept, and watching continues.

Architecture #

Design goals#

1. One file out. The output must work from file://, an email attachment or any static host.
2. Two dependencies. marked and highlight.js; nothing else at runtime.
3. No config. Conventions over settings — see Writing Docs.

Build pipeline#

A page's body never depends on another page's content or title, only on the site's file → route map, which comes from paths alone. So every page renders as an independent job, and only the cheap, site-wide parts (nav, pager, folder labels) are assembled on the main thread.

flowchart LR
  S[scan: readdir + stat] --> M[file → route map]
  M --> P{{render pool}}
  subgraph P [render: inline or worker threads]
    L[lex] --> X[extract TOC] --> R[render] --> C[callouts]
  end
  C --> K[(cache per page)]
  K --> A[assemble nav, pager, HTML]
  A --> W[write tmp + rename]

Trees below 40 pages render inline, because starting workers would cost more than it saves. Larger trees use one worker_threads worker per spare core (up to 8). Each worker takes the next queued page as soon as it is free, so a few slow pages don't hold up the rest.

// Per page, in docs0.render.js (simplified)
const tokens = marked.lexer(readFileSync(file, "utf8"));
const tocTokens = extractToc(tokens); // removes "## Table of Contents" + list
const body = applyCallouts(marked.parser(tokens));
return { title, body, toc, mermaid, warnings, images, links };

Each result records the local images it inlined and the link targets it resolved. In --watch mode, those let a rebuild re-render only the pages a change affects. See Watch mode.

Output anatomy#

<header id="topbar">…brand · path · version · theme…</header>
<nav id="nav">…folder tree…</nav>
<main id="content">
  <article class="page has-toc" data-route="guides/diagrams" hidden>
    <div class="page-main">…rendered markdown…</div>
    <aside class="page-toc">…sticky TOC…</aside>
  </article>
  …one article per page…
</main>
<script type="text/plain" id="docs0-mermaid">
  …offline fallback…
</script>
<script>
  …router, spy, theme…
</script>

Version detection#

The version badge in the top bar comes from the nearest package.json with a version field, searching the docs root first and then each parent folder. If none is found the badge is omitted.

Last updated dates#

The date beside the path in the top bar is the file's modified time, shown as yyyy-mm-dd. It comes from the same stat the scan already makes, so it costs nothing and needs no version control. A fresh CI checkout sets every file's modified time to the checkout time. See Publishing for restoring real dates first.

Routing #

Hash format#

#/<page-route>[/<heading-slug>]

Heading slugs follow GitHub's rules, so ## 1. Why DOCS0 becomes 1-why-docs0.

Resolution rules#

1. If the whole path is a page route, show that page from the top.
2. Otherwise split off the last segment: the rest is the page, the segment is the heading slug.
3. Unknown routes fall back to the home page.

Why not real anchors#

All pages live in one document, so heading ids would collide (every page may have an "Overview"). Headings carry a data-anchor attribute instead and the router scrolls to them.

Theming #

Light and dark#

The initial theme follows your operating system (prefers-color-scheme). The ☀/☾ button in the top bar overrides it, and the choice is remembered in localStorage. Until you choose, DOCS0 follows live system changes.

stateDiagram-v2
  direction LR
  [*] --> System
  System --> Light: toggle
  System --> Dark: toggle
  Light --> Dark: toggle
  Dark --> Light: toggle

Design tokens#

All colours are CSS custom properties on :root, swapped under :root[data-theme="dark"]:

:root {
  --bg: #ffffff;
  --text: #1f2328;
  --accent: #0969da;
}
:root[data-theme="dark"] {
  --bg: #0d1117;
  --text: #e6edf3;
  --accent: #58a6ff;
}

Syntax colours use highlight.js's GitHub and GitHub Dark themes, scoped to the same attribute.

Reading layout#

Two top-bar buttons trade the sidebars for reading width. Both choices are stored in localStorage and applied before first paint, so a reload doesn't flash the old layout.

Diagrams scale down to fit their column, never beyond their natural size, so wide sequence diagrams and Gantt charts gain the most from the extra room. On narrow screens (800px and below) the nav is always off-canvas, and ☰ opens it over the page.