Layouts
Create app/layouts/default.html to replace the Markupress shell. Your layout receives page metadata and navigation, and places the page at <slot name="page">.
To change colors, typography or widths, use theme tokens. A replacement layout is useful when you want a different page structure.
Create a layout
Declare only the props your layout uses. This example puts navigation before the page and an outline after it:
<template component="site-layout"><defs>
<prop name="navigation" type="list(object({ href: string, label: string, current: string, ... }))" required>Links</prop>
<prop name="outline" type="list(object({ href: string, label: string, depth: number, ... }))" required>On this page</prop>
<prop name="page" type="object({ title: string, editLink?: string, ... })" required>Page metadata</prop></defs>
<div class="site">
<nav><a $each="item of $navigation" from:href="$item.href" from:aria-current="$item.current">{$item.label}</a></nav>
<main><slot name="page"></slot></main>
<aside><a $each="heading of $outline" from:href="$heading.href">{$heading.label}</a></aside>
</div>
</template>Available data
Markupress supplies its loader data to your layout, so it needs no default.server.ts of its own.
End object types with ..., as in the example. MarkupKit may add fields such as a route group's group; an open type accepts them.
Loader property reference
| Prop | Value |
|---|---|
title | The site title (title option, default "Documentation"). |
home | The site's base URL. |
navigation | MarkupKit navigation items for the selected version: href, label, current ("page" or "false"), depth and pageName. |
sidebar | The page's section sidebar, in <mk-nav>'s tree shape: entries with label, current, open, depth and children, and an href on a page. A folder with an index page has both href and children. Pass it to <mk-nav from:items="$sidebar">. |
hosted | Resolved Algolia settings and the selected language/version context, or null for local search. Pass this to the shipped search component when composing a custom header. |
search | The URL of the selected version's search index, _search.json (see Search). |
nav | The sections, then the nav option's links: each has label, href, current and icon (a URL, or ""). |
footer | _footer.md's columns, each a title and items of links with label, href and current, and its copyright. |
logo, favicon, badge | The logo's light and dark URLs, the icon URL (both null when absent), and the badge text. |
crumbs | Navigation items from the version home down to this page. |
previous, next | The neighbouring navigation items, absent at either end. |
versions | Version links: href, label, current and note, which explains a fallback to that version's home. |
outline | The page's headings in its outline range: id, href (#id), label and depth. |
contents | A generated index's entries, label, href and description, and an empty list on every other page. |
page | The page's front matter, plus its resolved title and document id, its editLink (absent when it has none), and lastUpdated, the YYYY-MM-DD date its file last changed in git (absent outside git). |
Titles, metadata and icons
Declare head content inside <defs>:
<title>{$title}</title>binds the title.<meta>usesfrom:contentfor a bound value.<link rel="icon" from:href="$favicon">adds the icon when present.
A page's title, meta names and canonical link take precedence over its layout's.
A <title>, <meta> or <link> outside <defs> fails the build. A replacement layout also declares its own favicon; it does not inherit the Markupress shell's head declarations.
Wrap one section
A folder's _layout.html wraps that folder's content inside the site layout. Its _layout.server.ts loader reads Markupress data from parent.markupress:
export function load({ parent }) { return { props: { section: parent.markupress.page.title } }; }Compose with MarkupKit
The markupress command loads your markupkit.config.ts, so MarkupKit plugins compose with the site. See Project structure for configuration precedence, or Home page to replace the home layout.