Skip to content

Fix archive-providers/mdo-providers reference generator; emit MDX directly #149

Description

@digitaldiina

Tracking issue for a new Azure DevOps work item: fix the archive-providers/mdo-providers reference generator's known formatting defects at the source, and have it emit Mintlify MDX directly.

Current output: en/api/archive-providers/reference/ (373 files) and en/api/mdo-providers/reference/ (422 files), both .md, generated: true + envir: onsite, online frontmatter. Known defects were found and categorized while fixing Mintlify build errors on the documentation side — see #122 for the full breakdown — and are currently client-side patched by tools/fix-archive-providers-mdx.ps1 in this repo.

Acceptance criteria

Parallel generation

  • A new Mintlify archive-providers/mdo-providers MDX generation process is added.
  • The existing DocFX generation for this content continues to run unchanged.
  • Existing DocFX output in superoffice-docs is not overwritten, removed, renamed, or redirected.
  • The Mintlify generation is sufficiently isolated to be moved into its own pipeline and pull request later.

Files and locations

  • Generated archive-providers pages continue to land at en/api/archive-providers/reference/.
  • Generated mdo-providers pages continue to land at en/api/mdo-providers/reference/.
  • All generated pages use the .mdx extension.
  • Generated slugs use one consistent casing convention across both providers (current mdo-providers nav mixes cases).
  • config/nav-archive-providers.json / config/nav-mdo-providers.json continue to be generated as flat JSON arrays of page paths, index first, with corrected/consistent casing.

Known generator defects — fixed at the source, not patched after the fact

  • The hardcoded stray orphaned </p> after the "See also" line at end-of-file is no longer produced (357 instances, archive-providers).
  • The trailing | on the ## Supported Columns table header row is always present (358 instances / 248 files, archive-providers).
  • Unbalanced ( in column-description cells is handled wherever it occurs in the string, not just at the edges.

Frontmatter

  • Each generated page retains title, description, generated: true, content_type: reference, envir.

Legacy navigation

  • The generator does not create or update a legacy toc.yml for this content.
  • The generator does not modify docs.json directly — the nav files above are consumed via $ref, same as today.

Validation and testing

  • A representative sample of generated pages from both archive-providers and mdo-providers is tested locally in the Mintlify project.
  • Testing confirms none of the three known defect patterns above reproduce.
  • No MDX parsing errors are produced.

Cleanup tasks

  • Once the generator fix lands and is verified, delete tools/fix-archive-providers-mdx.ps1 (including its hardcoded lookup table) from this repo.
  • Normalize the already-present mixed-case slugs in config/nav-mdo-providers.json.

Metadata

Metadata

Assignees

Labels

Type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions