Layouts
A layout is an HTML file with EJS tags that wraps a page's content. Layouts live in the layouts folder, postdoc/layouts/ by default. They run in Node.js when the site is built, so they can read files, import modules and compute whatever a page needs. Nothing in a layout runs in the browser unless you add a <script>.
A first layout
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title><%= page.title %> | <%= appSettings.name %></title>
<link rel="stylesheet" href="/css/site.css" />
</head>
<body>
<%- include('header') %>
<main>
<%- page.content %>
</main>
</body>
</html>EJS has three kinds of tags:
<%= value %>prints a value with HTML escaped.<%- value %>prints a value as it is. Use it forpage.contentand includes, which are HTML already.<% code %>runs JavaScript without printing anything, such as a loop or anif. You can useawaitin it.
Every layout can use page, pages, appSettings and a few more variables; Layout variables lists them all.
How a page's layout is picked
Postdoc picks a layout from the page's path. For docs/guide/setup.md, it checks these files and uses the first one that exists:
layouts/guide/setup.ejs, a layout for this page onlylayouts/guide/index.ejs, a layout for the wholeguidefolderlayouts/setup.ejslayouts/index.ejs, a layout for every page that has no more specific one
So one layouts/index.ejs can serve a whole site, and you add layouts for folders or single pages as they need their own design. A page without any matching layout is reported as an error and left out.
When a theme is active, Postdoc checks the theme's layouts at each step too, right after yours. A layout in your project wins over the theme's layout at the same place, and a more specific layout wins over a more general one, wherever it comes from.
A page can also name its layout in its front matter, whatever its path:
---
title: The voyage
layout: story
---Postdoc then uses layouts/story.ejs, or the theme's story.ejs if your project has none. The name can include folders, such as layout: guide/wide for layouts/guide/wide.ejs. The default theme has a story layout, for stories told with full-window storymaps.
Includes
Includes are partials that layouts share, such as a header or a sidebar. They live in the includes folder, postdoc/includes/ by default. Include one by its file name without the extension:
<%- include('header') %>An include sees the same variables as the layout. To pass it more, add an object:
<%- include('sidebar', { title: 'Guide' }) %>If the include is not in your project, Postdoc looks for it in the theme.
Navigation menus
pages lists the URL of every page, which is enough to find the pages of a section:
<ul>
<% for (const { url } of pages.filter(({ url }) => url.startsWith('/guide/'))) { %>
<li><a href="<%= url %>"><%= url %></a></li>
<% } %>
</ul>Page titles are not part of pages, so for a menu with titles and a fixed order, keep the menu in a module:
export const sidebar = [
{ title: 'Introduction', url: '/guide/index.html' },
{ title: 'Installation', url: '/guide/install.html' }
];and import it in the layout. Relative paths are resolved from the layout's folder:
<% const { sidebar } = await importModule('../../sidebar.js'); %>
<nav>
<ul>
<% for (const item of sidebar) { %>
<li>
<a href="<%= item.url %>" <%- item.url === page.url ? 'aria-current="page"' : '' %>><%= item.title %></a>
</li>
<% } %>
</ul>
</nav>This site builds its sidebars this way.
Pages without Markdown
A layout that no Markdown page uses as its own URL, or names in its front matter, becomes a page itself: layouts/404.ejs is published as /404.html, and layouts/about/index.ejs as /about/index.html when there is no docs/about/index.md. That's useful for a home page or an error page that is all design and no text. HTML files in the layouts folder are published the same way.
The same applies to folder layouts. If layouts/guide/index.ejs exists but docs/guide/index.md doesn't, the layout is also published as an empty /guide/index.html. Add an index page to the folder to avoid that.
Styles and scripts
Link styles and scripts from your layouts with paths from the site's root. In a build, Vite bundles the CSS and JavaScript files they point to, so you can import other modules and use any format Vite understands. Static assets has the details.
Because pages switch without a reload, a <script type="module" src="..."> in a layout runs once, when the reader opens the site, and not again on every page they move to. Navigation without reloads shows how to run code each time a page is shown.