API

markupress is an ESM package. Its functions run on Node; the controllers under markupress/controllers/ run in the browser.

MarkupKit plugins

markupress(options) adds versioned documentation with the Markupress theme to an MarkupKit site. It takes the configuration options plus root, and includes markdown(). The markupress command adds it after the plugins of the site's markupkit.config.ts.

markdown(options) alone makes any MarkupKit site's .md files into pages, with no versions or theme:

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

export default defineConfig({ plugins: [markdown()] });

`markdown()` option	Type	Does
`publicDir`	`(file) => string \| undefined`	The directory a page's root-relative images and files (`/logo.svg`) come from. Without one, they stay site URLs.
`onPage`	`(page, context) => void`	Called with each compiled page, its `file` and its `href`, for example to catalog documents. The second argument is MarkupKit's native `PageContext`.
`styles`	`string[]`	Stylesheet files every Markdown page component imports, such as a theme's prose styles.
`lineNumbers`	`boolean`	Numbers the lines of every highlighted code block unless its fence says `show-line-numbers=false`.
`markdownSyntax`	`'standard' \| 'compatible'`	The syntax of pages whose front matter sets no `markdownSyntax`; `standard` by default.
`translations`	`(file) => TranslationOverrides \| undefined`	Reader strings for code actions and unlabelled details blocks, resolved per source file.
`alternates`	`(context) => Promise<readonly LanguageAlternate[]>`	Declarative alternate-language head links, available before Markdown compilation. MarkupKit's immutable `context.pages` identifies the current source discovery.
`frontmatter`	`(file) => FrontMatter \| undefined`	Front matter for a page, which its own fields override.
`home`	`(file) => string`	The URL a page's root-relative links (`/guide/`) start from. The site's base by default.

Building and serving

Function	Returns
`buildSite(options)`	`Promise<BuildResult>`: writes the static site, with the `outDir` and the routes it built.
`devSite(options)`	`Promise<ApplicationServer>`: the development server, with its `url` and `close()`.
`previewSite(options)`	`Promise<ApplicationServer>`: serves the built site.
`siteOptions(options, markupkit?)`	The MarkupKit options the three functions above use: the site's MarkupKit options with `markupress()` added after their plugins.

Each takes the configuration options plus root, host and port, and loads the site's markupkit.config.ts as the markupress command does. They take their options as given, and loadConfig(root) reads the site's Markupress configuration:

import { buildSite, loadConfig } from 'markupress';

const root = 'website';
const { outDir, routes } = await buildSite({ ...await loadConfig(root), root });

Configuration

defineConfig(options) returns its options unchanged and types a markupress.config.ts. loadConfig(root) returns the options from the site's markupress.config.ts, .js or .json, or {} without one.

Versions

snapshotVersion(id, options) records the current docs as version id in versions/<id>/, as markupress snapshot does, and returns its id, directory and publicDir. It never replaces an existing snapshot.

versionLinks(documents, versions, id, selected, base, fallbackNote?) returns the version switcher's links for the document id: each version's href, label, current and the note that explains a fallback to that version's home. The optional (versionLabel) => string callback localizes that note.

Compiling Markdown

MarkdownOptions.canonical supplies a resolved canonical URL for site policy such as source-content fallback. uiLanguage identifies the language and direction of generated code controls and unlabelled details summaries independently of the article.

compileMarkdown(source, options) compiles one Markdown document to an HTML Next page resource, as the markdown() plugin does for each page:

import { compileMarkdown } from 'markupress';

const page = await compileMarkdown('# Hello\n\nText.', { file: 'docs/hello.md', pageName: 'page-hello' });
page.resource;  // the page component's HTML
page.outline;   // [{ id, href, label, depth }] in the page's outline range

Option	Does
`file`	The Markdown file's path, which diagnostics name and relative links resolve from.
`pageName`	The page component's tag.
`resolveLink`	`(href, kind) => string`: resolves each link (`kind` `"link"`) and image (`"asset"`).
`styles`, `lineNumbers`, `markdownSyntax`, `frontmatter`	As the `markdown()` options of the same names.

It returns resource, the resolved title, the document id, aliases, the validated frontmatter, the outline, and generated, whether the page is a folder's generated index.

Controllers

markupress/controllers/shell.js, code.js and outline.js are the theme's browser controllers: the shell's theme button and drawer, code block buttons, and the outline's current heading. The theme and Markdown pages load them; a site layout can reference them too.

Search configuration types

SearchOptions accepts local LocalSearchOptions with an optional provider: 'local', or AlgoliaSearchOptions with provider: 'algolia', appId, public search-only apiKey, indexName and optional filters, limit, timeout and debounce. See Search for index fields, context filters and import instructions. MarkupressOptions.search also accepts false; omission uses local search.