HTML pages

When a page is mostly markup, write it as HTML and skip the Markdown parser.

This page is a .html file in docs/guide/. It is not run through the Markdown parser, but it is still a first-class page: front matter, heading anchors, table of contents, link rewriting, search indexing and the page-scoped stylesheet all work exactly as they do for Markdown.

What still happens for you

Three things are rewritten at build time so an HTML page behaves like any other page in the app:

  • Headings — h2 and h3 get stable ids and appear in the table of contents on the right.
  • Links — href="./markdown.md" becomes an app route, so this link navigates without a page reload.
  • Assets — relative src attributes are pointed at the copied asset folder.

When to use it

Reach for an HTML page when the markup is the content: a component gallery, a comparison layout, a status board. If the page is mostly prose with a little markup in it, stay in Markdown — raw HTML works there too.

Scoped styles

This grid is styled by html-pages.scss, compiled at build time and scoped to this page. The class names cannot collide with anything else.

Design tokens

The card borders and accent use the same custom properties as the rest of the site, so they follow light and dark mode with no extra work.

No build step to learn

Drop the file in, save, and it is in the sidebar. Same as Markdown.

The trade-off

You lose the Markdown conveniences: admonitions, code fence highlighting and tables all have to be written out as markup. Mixing formats across a docs set is fine — the reader cannot tell which file produced which page.