Type to search.

↵ to open ↑↓ to navigate Esc to close

Page structure

Each article is a single HTML file. The theme reads its structure from standard tags: <article> wraps the page, <section> wraps each topic, and id-bearing headings drive anchors, deep links, and the right-hand table of contents.

Article shape

The pipeline expects an <article> with an <h1> title and one or more nested <section> blocks. The first heading inside each section carries a stable id: 

<article>
  <h1>Title</h1>
  <section>
    <h2 id="intro">Intro</h2>
    <p>…</p>
    <section>
      <h3 id="intro:details">Details</h3>
      <p>…</p>
    </section>
  </section>
</article>

The <h1> is the page title (used in the <title> tag too). Heading levels track section depth: <h2> for top-level sections, <h3> for nested ones, and so on through <h5>.

IDs and anchors

Every <h2>–<h5> with an id gets a small link icon prepended that pulls into the left gutter and shows on hover. The id is the URL fragment for that heading, so page-structure.html#ids-and-anchors lands here.

By convention nested ids carry the parent’s id as a colon-separated prefix: 

<h2 id="config">Configuration</h2>
<h3 id="config:options">Options</h3>
<h3 id="config:options:advanced">Advanced options</h3>

Nothing in the pipeline enforces the convention — ids only need to be unique inside the page — but the prefixed form reads as a path from the page root and keeps the ToC’s deep links self-describing.

Targeted headings glow

When the URL fragment matches a heading id, the heading gets a soft highlight band. The same applies to p, li, dt, and code targets — useful when a search result deep-links into a paragraph mid-page.

Table of contents

The right-hand ToC is built from <article> > <section> top-level entries and any nested <section> children. Each entry uses the first id-bearing heading inside the section. Sections whose first heading lacks an id are skipped — they’re structural, not navigable.

Omitting from the ToC

Two opt-outs control how a section participates:

data-toc="omit"

Skip this section entirely, including its descendants.

data-toc="omit-children"

Include this section but not its nested ones — useful for a long FAQ-style section where the children are noise in the ToC. 

<section data-toc="omit-children">
  <h2 id="faq">FAQ</h2>
  <section><h3 id="faq:q1">…</h3></section>
  <section><h3 id="faq:q2">…</h3></section>
</section>

Lead paragraph

The first <p> directly inside <article> — the one before any <section> — is automatically styled as a lead: larger type, lighter weight, with a rule underneath separating it from the body. Use it for the one-paragraph summary of the page.

Write internal links the way you author the files — with .html suffixes: 

<a href="code-blocks.html">Code blocks</a>
<a href="code-blocks.html#embed">Embedding a file</a>

The link-rewriter pass strips the .html and turns the URL into a clean directory form (code-blocks/). Query strings and fragments are preserved. To opt out of rewriting on a particular link, mark it data-external.

Use the same opt-out for links to HTML pages that live in the same deployment but outside the doc set — standalone demos and the like. Marking them data-external keeps the .html intact and leaves the page-relative path untouched: 

<a href="../cookbook/labels-advanced.html" data-external>Lots of labels</a>

Absolute URLs (anything starting with a protocol, with //, or with mailto:) are left alone. After rewriting, the relativize pass turns every internal URL into a page-relative form so the site is portable to any URL prefix — see Deployment for the details.

Page title

The <title> tag for each page is taken from its <h1>. No frontmatter, no title: data file — the heading is the source of truth. If a page has no <h1>, the title falls back to "apidocs".