Customize a site
5 minutes read
A Slipway site is Markdown, mizzen.yml, and optionally _data/navigation.yml. The engine and theme are packages, so most changes are configuration, not edits to theme code.
Site settings
mizzen.yml sits at the site root; every path in it is relative to that folder. These keys change the site as a whole:
title: My docs
description: One sentence about the site.
lang: en
url: https://example.github.io
base: /my-docs
source: docs
repository:
url: https://github.com/example/my-docs
branch: main
url and base are what make canonical links, the sitemap, social images, and the deploy workflow's links point at the published site. Without url, those tags stay relative or are left out with a warning. The configuration reference lists every key.
Logo and footer
The theme reads a few blocks from theme.options. The engine carries each block to the theme unread, so a key the theme does not know is ignored rather than failing the build.
theme:
options:
logo:
light: /assets/logo.svg
dark: /assets/logo-dark.svg
footer:
copyright: © 2026 Example
license: MIT
links:
- title: Source
url: https://github.com/example/my-docs
- title: Guides
url: /guides/
logo.lightandlogo.darkare shown in the respective color scheme. Both are site paths;baseis added for you. Without a logo, the header shows the site title.footer.copyrightandfooter.licenseare plain text.footer.linksaccepts atitleand aurl; site paths start with/, andhttps,http, andmailtolinks work. Other schemes are dropped, so a config value cannot inject a script.
Announcement bar
A dismissible bar above the header announces a release or an event:
theme:
options:
announcement:
id: v0-4
text: Slipway 0.4 is out.
href: /changelog/
text is shown only when it is not empty, and href is optional: when set, the text becomes a link, with the same safe-scheme rule as footer links. Use a new id for each announcement, because a visitor's dismissal is remembered under slipway-announcement:<id>. The bar is readable without JavaScript; the dismiss button appears once the script loads, and a returned visitor's bar hides at that point rather than before first paint.
Page-agent menu
On a doc page, the "Use with an agent" menu copies the page's Markdown and offers links that open it in an agent. The defaults are Claude, ChatGPT, and Cursor. Replace them with theme.options.pageAgent.providers:
theme:
options:
pageAgent:
providers:
- title: Claude
url: https://claude.ai/new?q=Read+{markdown}
- title: My agent
url: https://agent.example.com/open?url={url}&title={title}
Each URL may use {markdown} (the page's Markdown twin), {url} (the page's absolute URL), and {title}. The values are URL-encoded. A template that needs {markdown} or {url} is skipped when url is unset, because a relative path would give the agent a link it cannot open.
Page feedback
With an endpoint configured, a doc page ends with "Was this page helpful?" and Yes and No buttons. The answer is POSTed as JSON, {"url": "/guide/install/", "helpful": true}, and the page remembers it in sessionStorage for the rest of the browser session; nothing is written to cookies or localStorage. The widget renders hidden and JavaScript reveals it, so a visitor without JavaScript sees no control. Without the block, no feedback markup is rendered.
theme:
options:
feedback:
endpoint: https://feedback.example.com/vote
Navigation
The header menu and the doc sidebar come from _data/navigation.yml. The shape is the one 0.2 used: main is the header, docs is the sidebar, and a group holds links under a heading.
main:
- title: Home
url: /
- title: Guides
url: /guides/
- title: Reference
url: /config/
docs:
- title: Start
children:
- title: Install
url: /install/
- title: Customize
url: /guides/customize/
URLs are written without base; the engine adds it. A language adds its own list with a suffix, such as main_fa; a language without one uses the plain list. Set navigation in mizzen.yml to use a file at another path. When the file does not exist, navigation is built from folders and each page's order front matter.
Default front matter
Apply a layout and other values to a folder instead of repeating them in every page:
source: docs
defaults:
- path: ""
values:
layout: doc
path is a folder relative to source, and "" covers every page. Later entries win over earlier ones, and a page's own front matter always wins.
Search
The engine writes the search index and the theme loads it on first use. Keep less text per page, or turn search off for the whole site:
search:
text: 200
search: false builds no index. A single page leaves the index with search: false in its front matter.
Redirects and generated files
Old addresses are redirect pages, so a renamed page keeps its URL:
redirects:
/old-guide/: /guides/
/install: https://example.com/docs/install/
An output is switched off by its name:
outputs:
twins: false
llms: false
The names are the files in the engine's outputs folder, such as twins, llms, llms-full, sitemap, search, sourcemap, robots, and agents-md. HTML pages and assets cannot be turned off.
Language and direction
lang sets the interface strings and the default dir, so lang: fa or lang: ar gives a right-to-left page without another key. A page overrides either one with lang or dir in its front matter. To offer more than one language, list them in switcher order:
languages:
- code: en
name: English
prefix: ""
- code: fa
name: فارسی
prefix: /fa
Pages join a language by lang and the translations of one page by translation_key.
Per-page settings
The theme ships doc, home, not-found, versions, and base layouts. A page can also set:
permalinkfor a URL other than the one its file path gives.orderto sort it among siblings when navigation comes from folders.status(experimental,beta,deprecated,proposed,accepted,rejected, orsuperseded) for the label the theme shows.width(narrow,wide, orfull) for a page wider or narrower than the reading column.imagefor the page's own social card.agentfor instructions to an agent editing the page, such asedit: falseand thesourcefile to change instead.
Changing the theme itself
The colors, type, spacing, and component styles are design tokens in the theme, not config keys. In 0.3.0 there is no token override in mizzen.yml and no assets/css/custom.css slot: a color or font change belongs to a theme.
For deeper changes, keep a copy of the theme, edit its tokens in tokens/*.json and its styles in styles/, and point the site at it:
theme:
name: ./theme
options:
logo:
light: /assets/logo.svg
A relative theme.name is resolved from the site root. After editing the JSON, rebuild the token stylesheet with npm run tokens --workspace @velella/lateen for the theme in this repository, or node scripts/tokens.mjs inside a copy. Use logical CSS properties (margin-inline-start, not margin-left) so the copy still works in right-to-left languages.