---
title: Style the site
description: Give the generated pages your site's colors with a stylesheet, or its header, footer, and home opening with a shell and an opening fragment.
slug: /guides/style-the-site
order: 4
visibility: public
redirects_from: [/shell]
---

# Style the site

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](/reference/output/#the-styling-surface).

## 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](/getting-started/)).

## Steps

### 1. Choose between a stylesheet and a shell

Without a shell, the tool renders every page into its [default layout](/concepts/glossary/#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](/reference/output/#the-styling-surface), which lists every property and selector:

```css
.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.

```text
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](/guides/callouts-and-diagrams/). 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`.

```css
.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](/reference/output/#the-page-head)). 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.

```html
<!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`.

```text
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.

```html
<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.

```css
.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.

```css
.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`.

```text
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.

```css
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](/reference/refusals/) gives the exact text.

| Message | Cause | Remedy |
| --- | --- | --- |
| `the shell lacks the marker <!--tzdoc:head-->`, `the shell lacks the marker <!--tzdoc:page-->` | The shell file has no such comment. | Add the marker where the build should write the head elements or the page. |
| `the shell file is absent at <path>` | `--shell` points to a file that does not exist. | Correct the path. |
| `the home opening file is absent at <path>` | `--home-opening` points to a file that does not exist. | Correct the path. |
| `the site stylesheet file is absent at <path>` | `--stylesheet` points to a file that does not exist. | Correct the path. |
| `output contains an input source or asset — <path>` | The shell, the opening, or the stylesheet sits inside the output folder. | Keep the supplied files outside the output folder. |

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](/reference/refusals/#usage-errors)).

## Related

- [Output](/reference/output/#the-styling-surface) lists the properties, the classes, the attributes, and the selectors a stylesheet targets.
- [Highlight a code block](/guides/code-blocks/) explains the figure the token properties color.