Documentation

This site is built with the MyST Document Engine^[1]. It lives in the docs/ folder.

Preview and build¶

From the repository root:

npm install
npm run docs:live  # live preview at http://localhost:3000
npm run docs       # static HTML in docs/_build/html

Add a page¶

1. Create a Markdown file in docs/.

2. Add it to the toc in docs/myst.yml.

Some pages {include} READMEs from the repository so they have one source of truth. Relative links in those READMEs are fixed by the myst-include-link-rewrites plugin.

How styling works¶

We re-skin the default book-theme so the docs match the design language of The Stacks.

The site uses MyST’s stock book-theme plus one stylesheet, brand.css, loaded from myst.yml.

Almost everything is done by overriding the MyST theme CSS variables. In a few cases we need extra work to get the design right, and each one has a comment in brand.css explaining why.

Brand and styling source of truth¶

Brand guidelines: Colors, fonts, logos and the favicon come from the brand guidelines, the design system for The Stacks. myst.yml points to the logo files there, so they aren’t copied.

Typography: We follow the brand fonts, with one docs-specific choice: body text uses the sans font because it’s easier to scan in technical docs. The theme has no font variables, so headings need one selector override.