facebook/docusaurus · warning · Error

Docusaurus MDX partial files should not contain front matter

Error message

Docusaurus MDX partial files should not contain front matter.
Those partial files use the _ prefix as a convention by default, but this is configurable.
File at ${filePath} contains front matter that will be ignored:
${JSON.stringify(frontMatter, null, 2)}

What it means

Thrown by the MDX loader when an MDX partial (a file whose path the isMDXPartial callback marks as partial, by default files/folders prefixed with _) contains YAML front matter. Partials are meant to be reusable fragments without their own metadata, so front matter is silently ignored - Docusaurus escalates to a hard error in CI and test environments (NODE_ENV==='test' || CI) to catch mistakes early, and only warns locally.

Source

Thrown at packages/docusaurus-mdx-loader/src/loader.ts:73

    options,
    compilerName,
  });

  const contentTitle = extractContentTitleData(result.data);

  // MDX partials are MDX files starting with _ or in a folder starting with _
  // Partial are not expected to have associated metadata files or front matter
  const isMDXPartial = options.isMDXPartial?.(filePath);
  if (isMDXPartial && hasFrontMatter) {
    const errorMessage = `Docusaurus MDX partial files should not contain front matter.
Those partial files use the _ prefix as a convention by default, but this is configurable.
File at ${filePath} contains front matter that will be ignored:
${JSON.stringify(frontMatter, null, 2)}`;

    if (!options.isMDXPartialFrontMatterWarningDisabled) {
      const shouldError = process.env.NODE_ENV === 'test' || process.env.CI;
      if (shouldError) {
        throw new Error(errorMessage);
      }
      logger.warn(errorMessage);
    }
  }

  const metadataPath = (function getMetadataPath() {
    if (!isMDXPartial) {
      return options.metadataPath?.(filePath);
    }
    return undefined;
  })();

  const assets =
    options.createAssets && !isMDXPartial
      ? options.createAssets({filePath, frontMatter})
      : undefined;

  const fileLoaderUtils = getFileLoaderUtils(compilerName === 'server');

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Remove the front matter block from the partial file (partials should not have one).
2. If the file is not actually a partial, rename it so it does not start with _ (and is not in a _ folder), or adjust your custom isMDXPartial callback.
3. If you genuinely want to suppress the warning everywhere, set the MDX loader option isMDXPartialFrontMatterWarningDisabled: true (advanced, via a custom plugin).

Example fix

// before: src/_partials/_intro.mdx
---
title: Intro
---
Hello.
// after
Hello.

import matter from 'gray-matter';
import fs from 'node:fs';
// in a pre-build script, scan partials for front matter:
function partialHasFrontMatter(file: string): boolean {
  return Object.keys(matter(fs.readFileSync(file, 'utf8')).data).length > 0;
}

When it happens

Trigger: Adding front matter (---\nkey: value\n---) to a file whose name starts with _ or that lives in a folder starting with _, then building/testing in CI or with NODE_ENV=test. The error fires from loadMDX when isMDXPartial(filePath) is truthy and hasFrontMatter is true.

Common situations: Renaming a regular doc to _partial.mdx but leaving its front matter in place; copy-pasting a full doc into the _partials folder; a custom isMDXPartial implementation that flags more files than intended.

Related errors

• MDX compilation failed for file ${logger.path(filePath)} Cau
• Processing of page source file path=${relativeSource} failed
• Failed to retrieve git history for "${file}" because git is
• Failed to retrieve the git history for file "${file}" with e
• A highlight range has been given in code block's metastring

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/f56820a70ca84d6c. Report an issue: GitHub.