Front Matter in Docusaurus, MkDocs and GitBook: Which Fields Carry Over

Docusaurus, MkDocs and GitBook each read a different set of front matter keys, so a field that controls something in one framework often has no documented meaning in another. When you move Markdown docs between them, check every front matter key against the target framework's documentation and remove or map the ones it does not use.

What each framework documents

Docusaurus documents 25 front matter fields for docs pages. They include id, title, description, slug, sidebar_label, sidebar_position, tags, keywords, image, hide_title, hide_table_of_contents, draft and unlisted. Several of them control the sidebar and navigation, for example sidebar_position, which sets a page's position in an autogenerated sidebar. The slug field sets the page's URL.

MkDocs documents two predefined front matter keys: template and title. Every other key is passed to the page template, so it only does something if the theme you use supports it. MkDocs decides a page's title in a fixed order: the nav setting first, then a title key in the page, then a level 1 heading, then the file name. Navigation lives in the nav setting, not in each page's front matter.

GitBook documents several front matter keys for Git Sync, among them hidden: true for pages hidden from the table of contents, description, and tags (a list that can mark one tag as primary). Navigation is defined separately, in a SUMMARY.md file.

Where fields do and do not line up

The pattern to notice is the last row. In Docusaurus a page can carry its own sidebar position, while MkDocs and GitBook keep navigation outside the page. A sidebar_position copied into a MkDocs page is not one of its predefined keys, so it does not reorder anything.

A common case: Jekyll to Docusaurus

Jekyll pages often declare permalink. Docusaurus's page-level front matter has no permalink field; the equivalent is slug. A converter that copies the key unchanged leaves the URL setting unused, and one that blindly renames every key can invent meanings the target does not have. In a test we ran, Pandoc 3.10 kept permalink as permalink and re-sorted the keys alphabetically.

What DocPatch does with front matter

DocPatch converts Markdown documentation into Docusaurus, MkDocs or GitBook output. Front matter fields are translated into the target framework's equivalent where a real equivalent exists: for example, a Jekyll permalink field becomes a Docusaurus slug field. A field with no equivalent in the target format is dropped rather than mistranslated. Links, bold and italic formatting, nested headings (H1 to H3) and tables are carried through as-is. The input is Markdown only.

A short migration checklist

1. List every front matter key your docs use.
2. For each key, find it in the target framework's documentation. Keep it if it is documented, map it if there is an equivalent, and drop it if there is none.
3. Handle navigation separately from front matter: sidebar_position for Docusaurus, the nav setting for MkDocs, SUMMARY.md for GitBook.
4. Build the site and look for pages whose title, description or URL changed.

Frequently asked questions

Does MkDocs read description from front matter?

Not as a predefined key. MkDocs predefines title and template, and passes other keys to the theme, which may or may not use them.

What is the Docusaurus equivalent of a Jekyll permalink?

The page-level slug field sets a Docusaurus page's URL; permalink is not one of its documented page front matter fields.

Will sidebar_position work in MkDocs or GitBook?

No. It is a Docusaurus field. MkDocs sets navigation in its nav setting and GitBook in SUMMARY.md.

What does DocPatch do with a field the target does not support?

It drops it instead of mistranslating it.

Sources

Field lists are from each project's documentation as read on October 10, 2026, and can change: the Docusaurus docs plugin page (docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs), the MkDocs "Writing your docs" guide (mkdocs.org/user-guide/writing-your-docs), and GitBook's page and Git Sync documentation (gitbook.com/docs).