Skip to content

chore(ci): add duplicate anchor ID detection for composed MDX pages #273

@marythought

Description

@marythought

Problem

When multiple MDX files are imported into the same page (e.g. code_samples/tdf/encrypt_options.mdx imported into docs/sdks/tdf.mdx), headers from both files generate anchor IDs on the same rendered page. If two headers produce the same slug, TOC links jump to the wrong section.

This just bit us — ### Assertions in encrypt_options.mdx collided with ## Assertions in tdf.mdx, along with ### Data Attributes and ### Metadata.

Proposed solution

Add a script (e.g. src/openapi/check-duplicate-anchors.ts or similar) that:

  1. Parses each docs MDX file for import statements referencing code_samples/
  2. Collects all markdown headers from the doc file and its imports
  3. Slugifies them the same way Docusaurus does
  4. Fails if any duplicates are found

Run it in CI alongside check-vendored-yaml.

Context

Fixed in #268 by renaming encrypt option headers to use SDK option names (WithAssertions, WithDataAttributes, WithMetadata). Convention documented in AGENTS.md — but a CI check would catch future regressions.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions