Templates and styling
Stock reader pages use templates/base.html. The builder makes fixed literal replacements, not a template-language runtime, arbitrary theme loader or frontmatter per-page layout selector. This guide is for your own reviewed installation/fork. The official showcase keeps its pinned engine unchanged.
Files and responsibilities
| Source | Purpose |
|---|---|
| Base template | Document structure, metadata, resources and controls |
| Main CSS | Type, layout, themes and component states |
| Code-theme CSS | Syntax-token colors |
| Logo SVG | Header/tab identity |
| Reader JS | Behavior, not ordinary branding text |
| Site settings | Supported identity changes without template edits |
Exact paths are templates/base.html, static/css/main.css, static/css/hljs-theme.css and static/svg/logo.svg. Public paths omit static/. Preserve your source diff. Editing generated HTML is not durable: the next build overwrites it.
Custom content selectors still use installed templates/assets. Runtime branding may override file branding. Check these layers before changing CSS to fix a title actually supplied by settings.
Exact placeholders
Use double braces around the exact name. No whitespace-insensitive expansion, conditions, loops or arbitrary property access is implemented.
| Key | Escaped value |
|---|---|
siteTitle |
Effective header title, not necessarily home hero title |
title |
Page title |
description |
Effective page-description metadata |
url |
Site address plus generated route |
baseUrl |
Configured template path prefix |
copyrightText |
File setting; not displayed by stock template |
| Key | Generated fragment |
|---|---|
breadcrumbs |
Normal-page crumbs; home/404 empty |
sidebar |
Full generated navigation tree |
toc |
H2 rail for at least two headings; 404 empty |
prevNext |
Normal-page sidebar-order neighbors; home/404 empty |
pageClass |
Home class suffix or empty |
headerLinks |
Shown validated links/icons |
content |
Rendered body and normal-page metadata |
Stock browser title uses {{title}} | {{siteTitle}}. The latter is effective header label. Changing display markup does not independently change the page route map.
Text replacements are escaped; generated fragments are HTML. content follows Markdown/raw-HTML policy. Do not escape the entire body or treat generated navigation as a label. Unknown/misspelled placeholders remain unresolved. Inspect the built result for literal braces.
Normal-page date/reading metadata is inserted after the first closing H1. Without H1 that insertion will not appear there. Home/404 skip normal breadcrumb, previous-next and metadata; home can still have a qualifying heading rail. Every generated fragment has its own scope, not an interchangeable layout token.
Preserve behavior contracts
| Structure | Why it matters |
|---|---|
| Early state scripts | Apply theme/sidebar state before main paint |
| Font loader/noscript | Local fonts with fallback |
| Search input | Opens client palette |
| Theme button | Changes reader preference |
| Sidebar/toggles | Tree expansion/current row/drawer state |
| Mobile button/overlay | Phone navigation open/close |
| Headings/article | Anchors, rail and navigation |
| End scripts | Search, controls, code copy and Mermaid |
IDs, classes, data attributes and JS selectors are coupled. Placeholder preservation alone is insufficient if custom DOM removes controls or moves them behind overlays. The stock mobile toggle is outside the header’s backdrop-filter stacking context. Moving it can change hit targets/layering.
The template loads search core, app and Mermaid loader at the end, marking the loader for public rendering. It loads fonts/restores state early, defaults dark, and uses CSS system-font fallback. A deployed static host supplies its response security policy; editor server CSP is not automatically attached to reader files.
Theme and cascade
| Token group | Effects |
|---|---|
| Spacing | Padding, gaps, vertical rhythm |
| Type | Font stacks/sizes, code, headings |
| Layout | Sidebar/header/article/rail widths |
| Colors | Backgrounds, links, text, borders, active state |
| Alerts/code | Callout/code surfaces and token colors |
| Motion/focus | Transitions, reduced motion, keyboard visibility |
Main CSS has shared variables and dark/light color blocks. Later compact-reader declarations override some earlier sizes. Inspect final computed values, not only the first matching rule. Update corresponding colors in both themes; verify contrast, hover, active/error and focus states.
Code-token colors live separately. A light screenshot does not prove dark mode. CSS names/breakpoints are implementation details for this pin, not a stable theming API guarantee across future versions.
Improve content before changing engine layout: concise columns, split related tables, meaningful headings and breakable prose. Stock article tables have width 100%, not an automatic horizontal scrolling wrapper. Long inline keys/slash-chained words can overflow phones. Recompose the facts without reducing text size or hiding qualifications.
Paths, caching and privacy
Use baseUrl for local template links/assets at a subpath. It does not rewrite authored Markdown. Test deep reload, search/index, media and fonts at the actual hosted path, not only root home.
Stock CSS/script URLs have query-version strings. In your own modified release, review them and host cache rules so readers receive coherent assets. A query string is not a content hash or universal purge guarantee; inspect actual requested bytes after deployment.
Analytics, remote scripts/fonts/embeds change network/security assumptions. A custom CSP can also block expected resources. Record and test those choices instead of calling them stock local-resource behavior. Template metadata does not create an automatic sitemap/canonical-link service.
Safe customization procedure
- Record selected engine and keep an untouched original/source diff.
- Prefer supported branding fields for identity changes.
- Make one intended template/style edit in a separate reviewed checkout.
- Build into a new dedicated output.
- Inspect home, landing, ordinary page, lab and 404 in both themes.
- Test search, heading anchors/rail, previous-next, tree, mobile drawer, copy and diagrams.
- Inspect long titles, actual tables/code, fonts and focus at phone/intermediate/desktop widths.
- Check Escape, reduced motion, console/network errors and intended public bytes.
- Deploy tested output with a return path, then verify live host/cache behavior.
| Failure | Safe recovery |
|---|---|
| Literal braces | Restore exact supported placeholder |
| Dead control | DOM selectors, scripts and focus and layering |
| Old styles | Check source, build, output, path, cache and version |
| Phone overflow | Actual content, table and code pixels, then recompose |
| Wrong theme | Both color blocks and early saved state |
| Broken subpath | Generated prefix, authored paths and host mapping |
| Upgrade loses edits | Recover reviewed diff, port deliberately and retest |
Keep feature changes separate from styling in review. See Local assets, Site settings and Contributor workflow. This describes source/template behavior, not a claim that your customization was deployed or that every physical browser passed.