Migrating from Docusaurus and VitePress

Markupress reads its own model: folders as pages, one front matter vocabulary, Expressmark standard syntax and imported HTML Next components. A migration converts a site's content into that model once, then the site is a Markupress site. The tables below map each Docusaurus and VitePress feature onto the Markupress one.

Files and URLs

Move the documentation's Markdown into docs/, keeping its folders, and its static files into public/. Each file's path is its URL: docs/guide/install.md is /guide/install/.

Docusaurus or VitePress	Markupress
A number prefix such as `01-intro.md`	`01.intro.md`: a number and a dot order a page, and leave the URL.
`slug` front matter	The file's or folder's own path. Rename it to the URL it serves.
`_category_.json` (`label`, `position`, `collapsed`)	The folder's `index.md` front matter: `title`, `order` and `navigation: collapsed`.
A category's generated index page	An `index.md` with front matter and an empty body lists its folder's pages.
`sidebars.js` or VitePress's `sidebar` config	Folders, number prefixes and `order`. Each top-level folder is a section with its own sidebar (see Navigation).
Old URLs	A page's `redirectFrom` front matter redirects its old URLs to it, `aliases` serves it at more URLs, and MarkupKit's `redirects` option in `markupkit.config.ts` redirects any path.
`static/` (Docusaurus) or `public/` (VitePress)	`public/`.
`src/pages/`	Pages in `docs/`, or MarkupKit pages in `app/pages/`.

Front matter

Docusaurus	VitePress	Markupress
`title`	`title`	`title`, which also labels the page in navigation, breadcrumbs and the pager.
`sidebar_label`		`title`
`description`	`description`	`description`
`sidebar_position`		`order`
`id`		`id`, the page's identity across versions.
`hide_table_of_contents: true`	`outline: false`	`outline: false`
`toc_min_heading_level`, `toc_max_heading_level`	`outline: [2, 3]`	`outline: [2, 3]`
`custom_edit_url`	`editLink: false`	`editLink`, a URL or `false`
`keywords`, `image`	`head`	`head.meta.keywords` and `head.og.image` (see Front matter)
`draft: true`		`draft: true`
`unlisted: true`		`navigation: hidden`
	`layout: home` with `hero` and `features`	`layout: home`, with the hero and feature cards written as Markdown (see Home page).
	`lastUpdated`	The date comes from git for every page.

An unknown front matter field fails the build, naming the file and the field, so the first build lists every field left to convert.

Markdown

Docusaurus or VitePress	Markupress
`:::note[Title]` or `:::tip Title`	`::: tip [Title]`. The tones are note, tip, info, important, warning and danger, and `caution` is danger.
`> [!NOTE]` GitHub alerts	`::: note` containers.
`::: details Title`	`::: details [Title]`
`<Tabs groupId="pm">` with `<TabItem label="npm">`	Adjacent `::: tab [npm] {group=pm}` containers, one per panel.
VitePress `::: code-group` with ```sh [npm]	A `::: tab [npm]` container holding a fenced `sh` code block.
```js title="app.js" or ```js [app.js]	```js {title="app.js"}
`{1,3-5}` line highlights	`{highlight="1,3-5"}` in the code fence.
`// highlight-next-line` or `// [!code highlight]`	Keep the code literal; put selected lines in the fence's `highlight` attribute.
`showLineNumbers` or `:line-numbers`	`{show-line-numbers}` in the code fence.
VitePress `<<< @/snippets/app.js{2}`, or Docusaurus's raw import into `<CodeBlock>`	An embed link: `[app.js](../snippets/app.js "{embed highlight=2}")` (see Embedded files).
A live demo beside its source	`[Demo](../examples/demo.html "{embed=example}")` (see Live examples).
`## Heading {#id}`	The same.
MDX or Vue components	HTML Next components in `app/components/`, linked from a page with `<link rel="component" href="@/app/components/name.html">` (see Components).
`@site/` imports	`@/`, the project root.

See Markdown and Code blocks for everything a page can hold.

Site configuration

Docusaurus or VitePress	Markupress
`title`	`title`
`baseUrl` or `base`	`base`
`url`	`origin`, which also writes `sitemap.xml`.
Navbar items, or VitePress's `nav`	The sections come from top-level folders; the `nav` option adds links, with an optional icon.
Footer links and copyright	`docs/_footer.md`: a heading per column and a list of links under each.
`navbar.logo`, `favicon`, or `logo`	`public/logo.svg`, `public/logo-dark.svg` and `public/favicon.svg`.
`editUrl` or `editLink.pattern`	The `editLink` option: a URL ending in `/` that each page's file path follows.
`customCss`	A stylesheet in MarkupKit's `css` option, with Looma and Markupress tokens (see Theme and tokens).
A swizzled or custom layout	`app/layouts/default.html` (see Layouts).

The configuration reference lists every option.

Versions

Each Docusaurus version in versioned_docs/version-<id>/ becomes a snapshot folder, versions/<id>/docs/, whose name is a URL slug of letters, digits, - and _, such as v1 or 1-0, with its static files in versions/<id>/public/. The folders in versions/ are the version list, newest first, or the versions option sets the list, the labels and the default version (see Versions). From then on, markupress snapshot <id> records each new version.

Check the result

markupress build checks every link in the site and fails on a link to a missing page, file or heading, listing each one. Fix those, then compare the pages with the old site.