{"record":{"id":"02152cac8fc65466","repo":"facebook/docusaurus","slug":"invalid-syntax-value-options-syntax-valid","errorCode":null,"errorMessage":"Invalid --syntax value \"${options.syntax}\". Valid values: ${validSyntaxValues.join(', ')}","messagePattern":"Invalid --syntax value \"(.+?)\"\\. Valid values: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/commands/writeHeadingIds.ts","lineNumber":68,"sourceCode":"}\n\n/**\n * We only handle the \"paths to watch\" because these are the paths where the\n * markdown files are. Also we don't want to transform the site md docs that do\n * not belong to a content plugin. For example ./README.md should not be\n * transformed\n */\nasync function getPathsToWatch(siteDir: string): Promise<string[]> {\n  const context = await loadContext({siteDir});\n  const plugins = await initPlugins(context);\n  return plugins.flatMap((plugin) => plugin.getPathsToWatch?.() ?? []);\n}\n\n// TODO Docusaurus v4 - Upgrade commander, use choices() API?\nfunction validateOptions(options: WriteHeadingIDOptions) {\n  const validSyntaxValues: HeadingIdSyntax[] = ['classic', 'mdx-comment'];\n  if (options.syntax && !validSyntaxValues.includes(options.syntax)) {\n    throw new Error(\n      `Invalid --syntax value \"${\n        options.syntax\n      }\". Valid values: ${validSyntaxValues.join(', ')}`,\n    );\n  }\n  if (options.overwrite && options.migrate) {\n    throw new Error(\n      \"Options --overwrite and --migrate cannot be used together.\\nThe --overwrite already re-generates IDs in the target syntax, so the --migrate option wouldn't have any effect.\",\n    );\n  }\n}\n\nexport async function writeHeadingIds(\n  siteDirParam: string = '.',\n  files: string[] = [],\n  options: WriteHeadingIDOptions = {},\n): Promise<void> {\n  validateOptions(options);","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/commands/writeHeadingIds.ts#L50-L86","documentation":"Thrown by `writeHeadingIds`'s `validateOptions` when the `--syntax` flag is set to anything other than `'classic'` or `'mdx-comment'`. These are the only two heading-ID syntaxes Docusaurus knows how to emit. The TODO comment notes this manual validation should be replaced with commander's `choices()` API in v4.","triggerScenarios":"Running `docusaurus write-heading-ids --syntax=<value>` with `<value>` not in `['classic', 'mdx-comment']` (e.g. a typo, a made-up value, or a future syntax not yet supported).","commonSituations":"Typo like `--syntax=clasisc`; passing an unsupported value seen in an unrelated tool; copy-pasting a flag from an old/newer Docusaurus version with a different syntax set.","solutions":["Use one of the two supported values: `--syntax=classic` or `--syntax=mdx-comment`.","Omit `--syntax` entirely to use the default syntax.","Check the installed Docusaurus version's `--help` output for the current valid syntax list."],"exampleFix":"# before\ndocusaurus write-heading-ids docs --syntax=clasisc  # typo\n# after\ndocusaurus write-heading-ids docs --syntax=classic","handlingStrategy":"validation","validationCode":"const valid: HeadingIdSyntax[] = ['classic', 'mdx-comment'];\nif (options.syntax && !valid.includes(options.syntax)) {\n  throw new Error(`--syntax must be one of: ${valid.join(', ')}`);\n}","typeGuard":"function isValidSyntax(v: unknown): v is 'classic' | 'mdx-comment' {\n  return v === 'classic' || v === 'mdx-comment';\n}","tryCatchPattern":null,"preventionTips":["Restrict the CLI surface with commander's `choices()` API (planned for v4).","Provide an enum type for `syntax` in shared option parsing.","Print valid values in `--help`."],"tags":["write-heading-ids","cli","validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}