Add a page

Minimum steps

Create an HTML file inside a tab directory. The only requirements are a <title> and a <main class="doc-body"> block:

cat > docs/pages/guide/new-page.html <<'EOF'
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8">
<title>New page</title></head><body>
<main class="doc-body">
<h1>New page</h1>
<p>…</p>
</main></body></html>
EOF

With ./run_dev.sh running, the page appears in the Guide sidebar automatically — the dev server bakes the header, sidebar, breadcrumbs, TOC, and footer for you. (If the server isn't running, bake once with python3 docs/_lib/_wrap_handwritten.py.)

Controlling position

By default, new pages sort alphabetically (with index.html first). To pin a slot, add the file's stem to the order list in the tab's _tab.json section:

"order": ["index", "installation", "new-page", "quick-start", "why", "conventions"]

Stems not listed in order fall to the bottom, alphabetically.

The title and the on-this-page TOC

The sidebar label and breadcrumb come from the <title> tag (the site-name suffix is added for you — don't type it). The on-this-page TOC on the right is built from headings that carry an id:

<h2 id="overview">Overview</h2>
<h3 id="details">Details</h3>

Headings without an id are skipped by the TOC.

Linking to it

From another page in the same tab:

<a href="new-page.html">New page</a>

From a different tab:

<a href="../guide/new-page.html">New page</a>