markdownPlugin

Scans the pages, builds the sidebar tree, and picks the layout for every markdown file.

theme.markdownPlugin({
  include: ["pages/**/*.{html,md}"],
  baseDirectory: "pages",
  layouts: { default: "@layouts/document.layout.html" },
  icons: "@parts/sidebar-icons",
  publish: true,
  customizations: {
    "~/installation.md": {},
    "~/guides": { label: "Guides", collapsed: false },
    "~/guides/setup.md": { data: { icon: "rocket", badgeText: "new", badgeVariant: "tip" } },
  },
});

Options

Option	Type	Default	Role
`include`	`string[]`	`["pages/*/.{html,md}"]`	Globs of the pages to scan.
`exclude`	`string[]`	`[]`	Globs to leave out.
`baseDirectory`	`string`	`"contents"`	The folder that becomes the root of the tree. Everything before it in a path is ignored.
`layouts`	`{ default: string; [name]: string }`	required	Layout files by name. A page picks one with `layout: <name>` in front matter.
`icons`	`string`		Folder holding `<name>.icon.html` files. Without it `data.icon` is ignored.
`publish`	`boolean`	`true`	Default for pages without a `publish` front matter key. See Content.
`customizations`	`Record<string, Customization>`	`{}`	Per-node settings, keyed by path. Aliases like `~/` work.
`sidebarLayout`	`{ path, tag, sourceAttribute, slotName }`	the theme’s part	The part the tree is injected into, see Overriding.
`directoryLayout`	`{ path, tag, sourceAttribute }`	the theme’s part	The part rendering a folder.
`linkLayout`	`{ path, tag, sourceAttribute }`	the theme’s part	The part rendering a page link.

Layouts

Every markdown page gets a layout. default is used unless the page names another one:

layouts: {
  default: "@layouts/document.layout.html",
  plain: "@layouts/plain.layout.html",
},

---
layout: plain
---

The layout receives the page’s front matter as $data, so minHeading and maxHeading in front matter reach the table of contents part.

Order

The order of the entries in customizations is the order in the sidebar. Each folder counts on its own, so siblings only need to be listed in the order they should appear. Pages not listed keep their filesystem order after the listed ones. Set order on an entry to override its position.

customizations: {
  "~/installation.md": {},      // first
  "~/guides": {},               // second
  "~/guides/setup.md": {},      // first inside guides
  "~/guides/deploy.md": {},     // second inside guides
  "~/faq.md": { order: 1 },     // explicit, jumps ahead of installation
}

Node settings

Key	Applies to	Role
`label`	both	Text shown instead of the name derived from the file name.
`collapsed`	directories	Whether the folder starts closed. Default `true`.
`order`	both	Position among siblings, 1-based.
`data`	both	Values passed to the sidebar parts, see below.

data keys the theme’s parts read:

Key	Role
`icon`	Name of an icon file in the `icons` folder.
`badgeText`	Text of a badge after the link title.
`badgeVariant`	`note`, `tip`, `important`, `warning`, `caution`, `success`, `danger`.

Front matter

A page can carry its own sidebar settings, the same keys with a sidebar. prefix. sidebar.parent. targets the folder the page sits in.

---
sidebar.label: Setup
sidebar.order: 1
sidebar.parent.label: Guides
sidebar.parent.collapsed: false
---

Config entries win over front matter.

Titles

A link’s text is the file name turned into words, or label when set. The page’s first # heading is carried as data-title on the link, the previous and next links use it. A root index.md shows as “Home”.

Icons

Icons are HTML files, one <svg> each, named <name>.icon.html. htmlLayoutPlugin must register the tag:

plugins.htmlLayoutPlugin({ tags: ["layout", "part", "icon"] });