Skip to content

[Bug]: MDX safety check does not cover contributor docs #1147

Description

@pdmack

Bug Description

tools/check-docs-mdx scopes its checks to docs/user/ and docs/integrator/ only. Since PR #1143 added contributor docs to the Fern sidebar, docs/contributor/ is now rendered through Fern's MDX parser but is not covered by the safety check.

docs/contributor/validator.md currently has 14 bare <word> patterns (e.g., <phase>, <name>, <runID>, <component>) that break the MDX parser with:

Failed to parse ../docs/contributor/validator.md: Unexpected character `/` (U+002F)
before local name, expected a character that can start a name, such as a letter, `$`,
or `_` (note: to create a link in MDX, use `[text](url)`)

Two fixes needed

  1. Escape the bare < patterns in validator.md — wrap placeholder names in backticks or use &lt; (14 occurrences across lines 11, 13, 30, 91, 119, 137, 185, 413, 433, 434, 461, 513).

  2. Expand tools/check-docs-mdx scope — add docs/contributor/ to SEARCH_DIRS (line 25) and add a new check for bare <word> patterns outside code fences/inline code. The existing checks (void HTML elements, bare braces, HTML comments) don't catch this pattern class.

Steps to Reproduce

cd fern && fern docs dev
# 500 error rendering docs/contributor/validator.md

Or grep for the patterns:

grep -n '<[a-zA-Z]' docs/contributor/validator.md | grep -v '```\|<!--'

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions