Configuration

Configuration files

The markupress command reads the site's configuration from markupress.config.ts, markupress.config.js or markupress.config.json in its root, one of the three. defineConfig types a TypeScript configuration, and every key is optional:

// markupress.config.ts
import { defineConfig } from 'markupress';

export default defineConfig({
  title: 'Looma',
  base: '/looma/',
  nav: [
    { label: 'HTML Next', href: 'https://nextwebwg.org/declarative-components/' },
    { label: 'GitHub', href: 'https://github.com/threadlabs-studio/looma', icon: '/github.svg' },
  ],
});

The same options as JSON data:

{ "title": "Looma", "base": "/looma/" }

A TypeScript or JavaScript configuration loads through Vite, as MarkupKit's markupkit.config.ts does, so it imports its own TypeScript files by their .js names. loadConfig(root) returns the options the command reads.

Options

Option	Default	Does
`title`	`"Documentation"`	The site title in the top bar.
`titleTemplate`	`":title \| <title>"`	Each page's document `<title>`, where `:title` is the page's title, such as `":title · My site"`. `false` gives the page's title alone. A version's home page is titled with the site title.
`locales`, `defaultLocale`	no locale folders	Discovers translations inside each version, serves the default locale without a language prefix, and isolates language switching and search. Each locale has a label, optional directory, language tag and direction, plus reader-string and theme overrides (see Languages).
`localeFallback`	`'home'`	`'source'` serves missing translations from the default locale inside the selected version, with localized controls and a notice. Translations win by document identity. See Untranslated content.
`translations`	built-in English, French or Arabic; English for other languages	Partial reader-string overrides. Each locale can supply further overrides. Search counts use native plural categories and number formatting (see Languages).
`dateFormat`	`{ dateStyle: 'long', timeZone: 'UTC' }`	Native `Intl.DateTimeFormat` options for visible last-updated dates, globally or per locale. The ISO `datetime` value stays unchanged.
`lang`	`en`	The language of every page, a language tag such as `fr` or `pt-BR`: the document's `<html lang>`. A page's `lang` front matter takes its place.
`base`	`/`	The URL path the site is served under. It starts and ends with `/`.
`origin`	none	The site's origin, such as `"https://example.com"`. With it, `build` writes `sitemap.xml` at the base, listing every canonical page; configured locales also produce reciprocal alternate-language links.
`robots`	none	`build` writes `robots.txt`: `true` allows every crawler, and a string is the file's text. With `origin` set, the file ends with a `Sitemap` line.
`contentDir`	`docs`	The current version's content directory.
`outDir`	`site`	Where `build` writes the static site.
`versions`, `defaultVersion`	the folders in `versions/`, `current`	The versions and their order and labels, and the version the site root serves (see Versions).
`drafts`	`true` in `dev`, `false` in `build`	Whether pages with `draft: true` front matter are served. Set it, or pass `--drafts`, to build a staging site with its drafts.
`lineNumbers`	`false`	Numbers the lines of every code block.
`markdownSyntax`	`standard`	How Markdown pages read: `standard` Expressive Markdown, or `compatible` CommonMark and GFM. A page's `markdownSyntax` front matter overrides it.
`nav`	none	Links after the sections in the top navigation: `{ "label", "href" }`, with an optional `icon` image shown in place of the label.
`search`	`{ limit: 20, fuzzy: 0.2, prefix: true }`	Local search options, an explicit `{ provider: 'algolia', appId, apiKey, indexName }` provider, or `false` to omit search and generated indexes. `limit` is a positive integer, `fuzzy` is `false` or a fraction from 0 to 1, and `prefix` is a boolean. Page front matter `search: false` and HTML `data-search-ignore` exclude content (see Search).
`sidebarNavigation`	`tree`	`tree` uses nested disclosures. `sections` keeps category links visible and lists pages only beneath the current category; a category opens its overview or first page. Both modes work without JavaScript.
`logo`	`public/logo.svg` and `public/logo-dark.svg`	One image path, or `{ "light", "dark" }`, in place of the logo files.
`favicon`	`public/favicon.svg`	The site icon's path, in place of the icon file.
`editLink`	none	A URL ending in `/`, which each page's file path follows to make its "Edit this page" link (see Edit link and last updated).

Image paths starting with / are files in public/. base, origin, robots and outDir set the MarkupKit options of the same names, in place of the MarkupKit config's. An unknown key fails with the list of options.

Link check

build checks every link in the pages it writes. A link within the site to a page or file missing from the output, or to a #fragment naming no heading or element in its page, fails the build with each page and link. A nav or footer link starting with / is checked in every version, so the page it names must be in each one. A site whose links are not ready yet builds with MarkupKit's linkCheck option set to "warn" in its markupkit.config.ts, which reports the same links as a warning:

// markupkit.config.ts
import { defineConfig } from '@threadlabs/markupkit';

export default defineConfig({ linkCheck: 'warn' });

Programmatic options

The programmatic buildSite, devSite and previewSite APIs, and the markupress() plugin, take the same options plus root, host and port; siteOptions returns the MarkupKit options they use (see API).

Contextual sidebars

Documentation pages show the navigation for their section. Set sidebar: false in a page's front matter when that page provides its own tools or navigation, such as a customizer. A folder's index page supplies the default for its descendants; sidebar: true on a child restores documentation navigation there. This controls the documentation sidebar, while the mobile section menu remains available.

Appearance starts in Automatic, following the operating system. The monitor, sun and moon controls select Automatic, Light and Dark. An explicit choice persists across navigation and reload; Automatic clears it and follows system changes again.