Themes
A theme is a set of layouts, includes and public files that your project builds on. Your own files override the theme's, one file at a time, so you can change a header or a stylesheet and keep everything else.
The default theme
Unless you configure otherwise, Postdoc uses its built-in default theme. Its guide pages look like this, and under each part is where it comes from:
- 1A header, with a search box and a switch between light, dark and the reader's system theme includes/header.ejs
- 2A sidebar, with a filter includes/left_side_menu.ejs
- 3Your page, from its Markdown page.content
- 4A table of contents, from the page's headings includes/api_right_sidebar.ejs
- 5Links to the previous and the next page includes/prev_next.ejs
It also provides:
- layouts for the
guide/,getting-started/andapi_reference/folders, and forabout/changelog.mdandabout/glossary.md - a layout for API pages
- styles for code blocks, code groups, callouts and tables
The theme's layouts/index.ejs lays out every other page, docs/index.md too: the page and its table of contents, without the guide's sidebar. For a home page with a design of its own, add a layout such as layouts/home.ejs, and name it in the page's front matter: layout: home.
The theme reads its menus from the app settings:
export default {
appSettings: {
name: 'Acme',
// Links in the header and the footer
headerNav: [
{ title: 'Guide', url: '/guide/index.html' },
{ title: 'API', url: '/api_reference/index.html' }
],
// A link to the repository in the header, and one to edit each page
github: { repo: 'acme/docs', branch: 'main' },
// A menu of the site's versions in the header
versions: [
{ title: 'v2 (latest)', url: '/', current: true },
{ title: 'v1', url: 'https://v1.acme.dev/' }
],
// The sidebar of the guide pages, in sections
nav: [
{
title: 'Getting started',
children: [
{ title: 'Installation', url: '/getting-started/installation.html' },
{ title: 'Quick start', url: '/getting-started/quick-start.html' }
]
}
],
// The sidebar of the api_reference pages
apiNav: [
{
title: 'Reference',
children: [
{ title: 'Overview', url: '/api_reference/index.html' }
]
}
]
}
};A child in nav can have children of its own, for one more level of nesting. The sidebar's sections and groups open and close, and the ones with the current page in them start open. The sections a reader opens stay open as they move from page to page.
github adds a link to the repository to the header. With a branch, every page made from Markdown, apart from story pages, also gets a link to edit it on GitHub. When your project isn't at the top of the repository, dir names its folder, such as dir: 'website'. For the header's link alone, github can be just the repository: 'acme/docs', or its address.
When the pages are in another repository than the one the header links to, editLink names it for the edit links, with the same repo, branch and dir:
export default {
appSettings: {
github: 'acme/acme',
editLink: { repo: 'acme/docs', branch: 'main' }
}
};editLink: false leaves the edit links out.
versions adds a menu of the site's versions to the header. The version with current: true names the menu, or else appSettings.version does.
The header's theme switch offers light, dark, and the reader's system setting, which is where it starts. The theme is applied before the page is shown, so a dark page doesn't flash light while it loads.
Previous and next links
The previous and next links follow the order of nav, or of apiNav on the API pages. A page's front matter can change either link, or leave it out:
---
title: Configuration
prev: false
next:
text: Deploy your site
link: /guide/deployment.html
---Without text, a link has the title that its page has in the navigation. Without link, it leads where it would anyway, with your text. editLink: false leaves out the link to edit the page.
Override a file
To replace part of the theme, create a file with the same name in your project:
| To change | Create |
|---|---|
| A layout, such as the guide layout | layouts/guide/index.ejs |
| An include, such as the header | includes/header.ejs |
| A public file, such as a stylesheet | public/css/guide.css |
Paths are relative to baseDir, postdoc/ by default. A project configured for 0.3.0-preview4, without baseDir, has no theme unless it sets one. Your file is used instead of the theme's, everywhere the theme uses it. Layouts explains how theme layouts and your own layouts work together.
Use your own theme
A theme is a folder with up to three subfolders, all optional:
my-theme/
├── layouts/
├── includes/
└── public/Point the theme setting at the folder:
export default {
theme: './my-theme'
};The path needs a / in it. A name without one, such as 'default', refers to a theme that comes with Postdoc.
To build without a theme, set theme to null.