{"record":{"id":"f56820a70ca84d6c","repo":"facebook/docusaurus","slug":"docusaurus-mdx-partial-files-should-not-contain-fr","errorCode":null,"errorMessage":"Docusaurus MDX partial files should not contain front matter.\nThose partial files use the _ prefix as a convention by default, but this is configurable.\nFile at ${filePath} contains front matter that will be ignored:\n${JSON.stringify(frontMatter, null, 2)}","messagePattern":"Docusaurus MDX partial files should not contain front matter\\.\nThose partial files use the _ prefix as a convention by default, but this is configurable\\.\nFile at (.+?) contains front matter that will be ignored:\n(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/docusaurus-mdx-loader/src/loader.ts","lineNumber":73,"sourceCode":"    options,\n    compilerName,\n  });\n\n  const contentTitle = extractContentTitleData(result.data);\n\n  // MDX partials are MDX files starting with _ or in a folder starting with _\n  // Partial are not expected to have associated metadata files or front matter\n  const isMDXPartial = options.isMDXPartial?.(filePath);\n  if (isMDXPartial && hasFrontMatter) {\n    const errorMessage = `Docusaurus MDX partial files should not contain front matter.\nThose partial files use the _ prefix as a convention by default, but this is configurable.\nFile at ${filePath} contains front matter that will be ignored:\n${JSON.stringify(frontMatter, null, 2)}`;\n\n    if (!options.isMDXPartialFrontMatterWarningDisabled) {\n      const shouldError = process.env.NODE_ENV === 'test' || process.env.CI;\n      if (shouldError) {\n        throw new Error(errorMessage);\n      }\n      logger.warn(errorMessage);\n    }\n  }\n\n  const metadataPath = (function getMetadataPath() {\n    if (!isMDXPartial) {\n      return options.metadataPath?.(filePath);\n    }\n    return undefined;\n  })();\n\n  const assets =\n    options.createAssets && !isMDXPartial\n      ? options.createAssets({filePath, frontMatter})\n      : undefined;\n\n  const fileLoaderUtils = getFileLoaderUtils(compilerName === 'server');","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-mdx-loader/src/loader.ts#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the front matter block from the partial file (partials should not have one).","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.","If you genuinely want to suppress the warning everywhere, set the MDX loader option isMDXPartialFrontMatterWarningDisabled: true (advanced, via a custom plugin)."],"exampleFix":"// before: src/_partials/_intro.mdx\n---\ntitle: Intro\n---\nHello.\n// after\nHello.","handlingStrategy":"validation","validationCode":"import matter from 'gray-matter';\nimport fs from 'node:fs';\n// in a pre-build script, scan partials for front matter:\nfunction partialHasFrontMatter(file: string): boolean {\n  return Object.keys(matter(fs.readFileSync(file, 'utf8')).data).length > 0;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep front matter out of files/folders prefixed with _.","Run `docusaurus build` in CI (NODE_ENV/CI) so partial front-matter is caught before deploy.","If you intentionally want to silence it, set isMDXPartialFrontMatterWarningDisabled in a custom MDX loader config."],"tags":["mdx","front-matter","partial","ci"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}