Style the site #

View this page as Markdown

Prompt:

Make the generated docs use our site's header, footer, and colors.

Also works: "Change the docs' colors to match our brand." "Put our opening section on the docs home page."

What your tool does #

• Asks whether the pages should use your site's header and footer or only its colors, when the request does not say.
• For the colors alone, writes a CSS file that redefines the tool's custom properties on .docs-shell and passes it with --stylesheet.
• For the header and the footer, writes a complete HTML document containing the two markers and passes it with --shell.
• For a home opening, writes an HTML fragment and passes it with --home-opening.
• Builds, and reports the success line, which lists the shell, the opening, and the stylesheet the build used.

What you need #

• If you want your site's own header and footer: their HTML, and the web address of your site's stylesheet.
• If you want your own colors instead: the values to use, following the property list on Output.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

• The tool installed and a corpus that builds (Getting started).

Steps #

1. Choose between a stylesheet and a shell #

Without a shell, the tool renders every page into its default layout, with the navigation on the left and the article beside it. A site stylesheet changes the colors and needs no shell. A shell replaces the default layout with your site's own HTML document. A home opening adds a fragment to the home page alone.

The options combine. With a shell, --stylesheet still works, and the build writes both stylesheet links at the shell's <!--tzdoc:head--> marker (step 3).

2. Supply a site stylesheet #

Write a CSS file that redefines the tool's color properties on the .docs-shell element. A value set on :root, html, or body does not reach the pages, because the tool's own declaration on .docs-shell wins. A redefinition outside a media query replaces both the light and the dark default. To give the two color schemes different values, write your own media query.

The tool's test suite builds with this exact file and keeps it equal to the example on Output, which lists every property and selector:

.docs-shell {
  --docs-bg: #0b1020;
  --docs-text: #e6edf6;
  --docs-link: #7cc4ff;
  --docs-pre-bg: #05080f;
}
.docs-main pre code .docs-line-hl {
  background: rgba(124, 196, 255, 0.12);
}

Pass the file with --stylesheet. The build copies it into the tree as site.css, with LF line endings, and links it after the tool's docs.css on every page. At equal specificity, its rules win.

tzdocs build --source docs --out site --stylesheet theme.css

The tree's site.css sits at the tree root. If the tree is served at your site's root, its site.css has the address /site.css, so do not serve another file there.

The same file retunes the callouts. Each type's color, for its bar and its title, is a property on .docs-shell: --docs-callout-note, --docs-callout-tip, --docs-callout-important, --docs-callout-warning, and --docs-callout-caution.

.docs-shell {
  --docs-callout-note: #1d4ed8;
  --docs-callout-warning: #b45309;
}

With --next-previous, each page ends with the pager, a nav classed docs-pager whose links are classed docs-pager-prev and docs-pager-next. It takes its colors from --docs-link, --docs-muted, and --docs-border. To change its spacing, write a rule at the tool's own selector, such as .docs-main .docs-pager.

3. Supply a shell #

A shell is a complete HTML document of your site's own, containing the two markers. At the head marker, the build writes only the page's own head elements: its title, its description, its share tags, and the stylesheet links (Output). So put the charset and viewport lines in the shell's head yourself, as the default layout does. Put the share tags every page has in common there too, such as your site's name and its share image.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="/styles.css">
<!--tzdoc:head-->
</head>
<body>
<header>… the site's header …</header>
<div class="site-docs">
<!--tzdoc:page-->
</div>
<footer>… the site's footer …</footer>
</body>
</html>

Pass the shell with --shell.

tzdocs build --source docs --out site --shell shell.html

The build renders every page into the shell. At <!--tzdoc:head--> it writes the title, the description, the share tags, and the relative stylesheet links: the tool's docs.css and, where the build was given one, site.css after it. At <!--tzdoc:page--> it writes the docs-shell wrapper containing the navigation, the article, and the copy control, outlined below with ellipses marking the generated content.

<div class="docs-shell">
<nav class="docs-nav" aria-label="Documentation">…</nav>
<main class="docs-main">
… the article …
</main>
</div>
<script>… the copy control …</script>

The tool does not change the shell's own links, so keep them correct yourself. A stylesheet link placed before the head marker loses to both tool stylesheets at equal specificity. A link placed after the marker wins over them.

Under a shell, the tool's body rules do not apply, because they target the default layout's body class, tzdoc-page. Your site's font family therefore applies to the pages. The line height of 1.6 still applies, because the tool sets it on the docs-shell wrapper. Redirect stubs are not pages and take no shell.

The tool's docs.css leaves the article's list indent to the browser's default. A site stylesheet that resets padding on every element removes that indent, and the bullets then hang to the left of the article's text. Restore the indent in your own stylesheet.

.site-docs .docs-main ul,
.site-docs .docs-main ol {
  padding-left: 1.5rem;
}

A shell's stylesheet redefines the colors the same way, with its wrapper's class in front so that its own selector wins.

.site-docs .docs-shell {
  --docs-bg: var(--surface);
  --docs-text: var(--text);
  --docs-link: var(--accent);
  --docs-pre-bg: var(--surface-strong);
  --docs-tok-keyword: #f97583;
}

4. Supply a home opening #

A home opening is an HTML fragment, with no doctype and no stylesheet link. The build places it at the head of the home page's article column, above the page's own content and beside the navigation. Every other page is unchanged. An opening works with or without a shell. Pass it with --home-opening.

tzdocs build --source docs --out site --shell shell.html --home-opening home_opening.html

5. Place a fixed header above the pages #

To keep your site's header in view, make it position: fixed. Then give the element around the page marker top padding equal to the header's height. The navigation stays in view while the article scrolls, so set its top to the header's height and subtract that height from its maximum height. On a window 800 pixels wide or narrower the navigation does not stay in view, so the media rule removes the height limit there. The navigation then starts below the header on every page and stays below it as the page scrolls.

header {
  position: fixed;
  top: 0;
  height: 64px;
}
.site-docs {
  padding-top: 64px;
}
.docs-nav {
  top: 64px;
  max-height: calc(100vh - 64px);
}
@media (max-width: 800px) {
  .docs-nav {
    max-height: none;
  }
}

Expected result #

The success line lists the files the build used. It has this form: built 13 pages into site with the shell shell.html, the home opening home_opening.html, the site stylesheet theme.css.

Every page's head contains the title, the description, the share tags, and the two stylesheet links in order. Every page's body contains your site's header and footer around the docs-shell element, and the home page has the opening above its article. site.css sits at the tree root with LF line endings.

Refusals #

The build refuses on each of these before writing anything, with exit code 1. Refusals and findings gives the exact text.

A --shell, --home-opening, or --stylesheet flag with no file after it, or given twice, is a usage error. The tool prints the reason and the usage lines and exits with code 2 (Refusals and findings).

Related #

• Output lists the properties, the classes, the attributes, and the selectors a stylesheet targets.
• Highlight a code block explains the figure the token properties color.