When you convert documentation, what happens to dropped markdown frontmatter fields is that metadata keys with no semantic match in the destination framework are omitted from the output file rather than mistranslated. This prevents unsupported configuration lines from creating parser errors or silent build problems while keeping supported equivalents mapped directly into the new target structure.
Why frontmatter fields get dropped during documentation migrations
Static documentation tools rely on YAML frontmatter to determine navigation metadata, custom URLs, search rankings, and page layout properties. However, each system maintains its own schema. For instance, Docusaurus recognizes properties like sidebar_position, slug, pagination_prev, and custom_edit_url. MkDocs using the Material theme reads keys like status, icon, search.boost, and hide. GitBook handles custom variables and metadata according to its own structure.
When you migrate docs to docusaurus or convert markdown to mkdocs, you encounter metadata attributes that simply do not exist in the target system. In manual workflows, teams maintaining documentation across frameworks frequently lose track of how metadata changes between schemas. If a migration script forces an incompatible key into the destination file, one of two things happens:
- The parser throws an unrecognized key error and aborts the site build.
- The system ignores the line entirely, leaving orphaned data that bloats source files and confuses team members.
To prevent malformed configurations, migration pipelines drop frontmatter fields when no direct functional equivalent exists. This is exactly the kind of problem DocPatch is built to solve.
How to audit and handle omitted metadata fields
Understanding what happens to dropped markdown frontmatter fields requires an audit process to ensure you retain critical page behaviors without introducing invalid YAML. Follow this process when preparing files:
Inventory existing metadata keys: Extract all unique YAML keys from your current Markdown corpus. Categorize each property into layout settings (e.g., sidebar ordering), routing rules (e.g., custom paths or aliases), and thematic settings (e.g., tags, authors, or dark mode switches).
Map valid cross-framework targets: Cross-reference your inventory against target framework documentation. For example, if you maintain custom path variables, check whether the destination supports explicit slugs. If an exact equivalent exists, configure the translation mapping. If no equivalent exists, catalog the field as non-transferable.
Inspect rendered documents post-conversion: Verify that the dropped keys have not compromised page navigation or presentation. When keys controlling hidden tables of contents or navigation items are omitted, adjust the framework's global configuration file (such as docusaurus.config.js or mkdocs.yml) rather than relying on page-level overrides.
Validate output files with your framework CLI: Run the target framework's build command (npm run build or mkdocs build) to confirm that all remaining frontmatter compiles cleanly without schema warnings.
How DocPatch handles frontmatter during conversion
DocPatch converts Markdown documentation into Docusaurus, MkDocs, or GitBook output via a programmatic API. Input is Markdown only, accepting request bodies up to 10 MB.
When processing files, DocPatch semantically translates frontmatter fields between formats where a real equivalent exists. For example, a source permalink field translates directly into the Docusaurus slug field. A field with no target-format equivalent is dropped rather than mistranslated, ensuring your output files remain strictly compliant with target schemas.
Beyond metadata translation, DocPatch preserves content structure verbatim. Links, bold/italic formatting, nested headings (H1-H3), and tables are carried through as-is, without being rewritten or restructured.
To use DocPatch, send an HTTP request to POST /v1/docpatch/migrate with your Markdown payload and target framework selection, passing your API key in the x-api-key header. Each successful conversion uses one credit from the key's quota, and a key with no credits left receives a 402 error. Identical repeat requests may be returned from a short-lived cache without consuming additional credits.
You can integrate DocPatch into your toolchain using standard HTTP clients to manage metadata translation and framework conversions.
Frequently asked questions
What happens to internal links and headings when frontmatter is modified?
Internal links, bold/italic text, tables, and nested headings from H1 to H3 are preserved verbatim during conversion. They are carried through unchanged rather than rewritten or restructured.
Why are non-matching frontmatter fields omitted instead of retained?
Fields without target equivalents are dropped to avoid injecting invalid configuration keys into the new framework. This ensures that the destination build tools parse the YAML block without schema conflicts.
How does metadata translation work for supported keys?
Supported frontmatter keys are mapped directly to their semantic equivalents in the target framework schema, such as converting a permalink attribute to a slug attribute when targeting Docusaurus.
what happens to dropped markdown frontmatter fields · migrate docs to docusaurus · convert markdown to mkdocs · gitbook to docusaurus migration · keep documentation in sync across frameworks · docusaurus markdown converter