From 0a3b79a219a50b9dca0eb3f12bc325e321048161 Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Sat, 9 May 2026 11:50:16 -0400 Subject: [PATCH] fix(templates): emit only top-level README.mdx, not whole tree Previous approach (commits 229acac, 84cbf4e on origin) renamed every .md in the auto-generated tree to .mdx and rewrote in-content link targets. The wholesale rename tripped Mintlify's broken-links validation with 3832 broken-link errors because Mintlify rejects explicit `.mdx` extensions in in-content links (treats them as static-asset references rather than page references). The previous attempt to fix the link form (strip .md from targets, leave them extensionless) didn't help either: Mintlify's broken-links also requires nav registration for any non-.md link. Scope the rename to ONLY the three files Mintlify's nav resolver actually looks for: - TypeScript: add a tiny `mv README.md README.mdx` step at the end (typedoc-plugin-markdown emits the README itself, so we rename the result rather than redirecting the generator). - .NET: change the `Write top-level index` step's redirect target from `README.md` to `README.mdx`. - Python: same as .NET. Submodule pages stay .md. Mintlify treats their `(path.md)` in-content links as page references and resolves them on disk regardless of extension, so they continue to render correctly. Pairs with resq-software/docs#21 (one-shot rename of the same three READMEs in the existing tree). --- .../source-repo-templates/api-docs.dotnet.yml | 14 ++++++++++---- .../source-repo-templates/api-docs.python.yml | 10 ++++++++-- .../api-docs.typescript.yml | 18 ++++++++++++++++-- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/automation/source-repo-templates/api-docs.dotnet.yml b/automation/source-repo-templates/api-docs.dotnet.yml index bde56ae2..34c17b99 100644 --- a/automation/source-repo-templates/api-docs.dotnet.yml +++ b/automation/source-repo-templates/api-docs.dotnet.yml @@ -152,9 +152,15 @@ jobs: fi - name: Write top-level index - # xmldocmd emits one tree per assembly. Assemble a small - # README.md at the top of the api/ folder linking to each - # so a single nav entry can drive into all packages. + # DefaultDocumentation emits one tree per assembly. Assemble + # a small README.mdx at the top of the api/ folder linking + # to each so a single nav entry can drive into all packages. + # Emit .mdx (not .md) because Mintlify's docs.json nav + # resolver only matches .mdx for page ids; without this, + # mint dev warns "is referenced in the docs.json navigation + # but the file does not exist". Submodule pages stay .md + # since they are linked from content (where both extensions + # resolve) rather than from nav. run: | { echo "# ResQ .NET SDK" @@ -169,7 +175,7 @@ jobs: echo "- [$proj]($proj/$proj)" fi done - } > "$OUTPUT_DIR/README.md" + } > "$OUTPUT_DIR/README.mdx" - name: Prefix bare-filename intra-page links with ./ # Same pattern as the TypeScript template: Mintlify rejects diff --git a/automation/source-repo-templates/api-docs.python.yml b/automation/source-repo-templates/api-docs.python.yml index 04d79c08..91757c6b 100644 --- a/automation/source-repo-templates/api-docs.python.yml +++ b/automation/source-repo-templates/api-docs.python.yml @@ -195,11 +195,17 @@ jobs: - name: Write top-level index # pydoc-markdown emits an overview.md per package. Stitch a - # small README.md at the top of the api/ folder linking to + # small README.mdx at the top of the api/ folder linking to # each so a single nav entry can drive into all packages. # Package list is sorted alphabetically by directory name so # it stays in sync with `_pages.json` (which `find ... | sort` # produces below) regardless of PUBLIC_PACKAGES env order. + # Emit .mdx (not .md) because Mintlify's docs.json nav + # resolver only matches .mdx for page ids; without this, + # mint dev warns "is referenced in the docs.json navigation + # but the file does not exist". Submodule pages stay .md + # since they are linked from content (where both extensions + # resolve) rather than from nav. run: | { echo "# ResQ Python SDK" @@ -216,7 +222,7 @@ jobs: echo "- [\`$pkg_dir\`]($pkg_dir/overview)" fi done - } > "$OUTPUT_DIR/README.md" + } > "$OUTPUT_DIR/README.mdx" - name: Prefix bare-filename intra-page links with ./ # Mintlify rejects bare-filename .md links as broken; diff --git a/automation/source-repo-templates/api-docs.typescript.yml b/automation/source-repo-templates/api-docs.typescript.yml index f17b760a..b9b62d27 100644 --- a/automation/source-repo-templates/api-docs.typescript.yml +++ b/automation/source-repo-templates/api-docs.typescript.yml @@ -202,8 +202,7 @@ jobs: # Flat JSON array of generated Markdown paths (without # extension) so the docs repo can later splice them into # docs.json automatically. Mintlify resolves both .md and - # .mdx, and typedoc-plugin-markdown emits .md by default, - # so we keep the .md output and skip a rename step. + # .mdx for in-content links, so submodule files stay .md. working-directory: ${{ env.PKG_DIR }}/generated-docs run: | find . -name '*.md' -type f \ @@ -212,6 +211,21 @@ jobs: jq -R -s 'split("\n") | map(select(length > 0))' _pages.txt > _pages.json rm _pages.txt + - name: Rename top-level README -> .mdx (Mintlify nav) + # Mintlify's docs.json nav resolver only matches .mdx for + # page ids. Without this rename, mint dev warns: + # "sdks/typescript/api/README" is referenced in the + # docs.json navigation but the file does not exist. + # Scope is intentionally limited to the top-level entry + # file: in-content links to submodule .md files keep + # working as Mintlify treats those as page references and + # resolves them on-disk regardless of extension. + working-directory: ${{ env.PKG_DIR }}/generated-docs + run: | + if [ -f README.md ]; then + mv README.md README.mdx + fi + - name: Checkout docs repo uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: