facebook/docusaurus · error · Error

Document id "${baseID}" cannot include slash.

Error message

Document id "${baseID}" cannot include slash.

What it means

Thrown by doProcessDocMetadata when the resolved base document id contains a '/'. baseID comes from frontMatter.id if present, else from the filename (after number-prefix stripping). The id must be a single path segment because the plugin itself joins the directory prefix with the baseID using '/'.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/docs.ts:147

    vcs,
  );

  // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
  const sourceFileNameWithoutExtension = path.basename(
    source,
    path.extname(source),
  );

  // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
  const sourceDirName = path.dirname(source);

  const {filename: unprefixedFileName, numberPrefix} = parseNumberPrefixes
    ? options.numberPrefixParser(sourceFileNameWithoutExtension)
    : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};

  const baseID: string = frontMatter.id ?? unprefixedFileName;
  if (baseID.includes('/')) {
    throw new Error(`Document id "${baseID}" cannot include slash.`);
  }

  // For autogenerated sidebars, sidebar position can come from filename number
  // prefix or front matter
  const sidebarPosition: number | undefined =
    frontMatter.sidebar_position ?? numberPrefix;

  // TODO legacy retrocompatibility
  // I think it's bad to affect the front matter id with the dirname?
  function computeDirNameIdPrefix() {
    if (sourceDirName === '.') {
      return undefined;
    }
    // Eventually remove the number prefixes from intermediate directories
    return parseNumberPrefixes
      ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
      : sourceDirName;
  }

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Remove any '/' from the front matter `id` field.
2. Use the `slug` front matter if you want a custom URL path with slashes.
3. Rely on directory structure for hierarchical ids rather than embedding slashes in id.

Example fix

---
# before
id: api/plugins
---
---
# after
id: plugins
slug: /api/plugins
---

const id = frontMatter.id ?? filename;
if (id.includes('/')) throw new Error(`Doc id '${id}' must not contain '/' (use 'slug' for URL paths)`);

const isSegmentId = (id: string): boolean => typeof id === 'string' && !id.includes('/');

When it happens

Trigger: Setting front matter `id: foo/bar`, or naming a doc file with a slash in its basename (rare). The check fires after frontMatter.id ?? unprefixedFileName.

Common situations: Manually setting an id with a slash to mirror a path, or migrating docs whose old ids contained slashes. Copy-paste of slug into the id field.

Related errors

• Error when loading ${doc.id} in ${doc.sourceDirName}: the pa
• Invalid sidebars file. The document with id "${docId}" was u
• Invalid sidebar items collection code=${JSON.stringify(sideb
• Doc with ID ${docId} wants to display sidebar ${sidebarName}
• Invalid sidebar file at "${toMessageRelativeFilePath(sidebar

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