Fix broken internal links, keep zh links in-locale, and clarify fern export - #6543
Open
ctondreau wants to merge 2 commits into
Open
Fix broken internal links, keep zh links in-locale, and clarify fern export#6543ctondreau wants to merge 2 commits into
fern export#6543ctondreau wants to merge 2 commits into
Conversation
…back Addresses issues surfaced by reader feedback and 404 analytics on buildwithfern.com/learn over the last 30 days. Broken /learn links (596 links across 158 files) Two readers reported that Ask AI handed them links that 404 — one noting the links were "missing the `/learn` subdomain that is present in all Fern docs links." The root cause is in the source: internal links were written product-root-relative (`/sdks/...`, `/docs/...`) instead of site-absolute (`/learn/sdks/...`). Docs are served under `/learn`, so these 404 for readers and get cited verbatim by Ask AI. Verified against the live site before and after: 404 https://buildwithfern.com/sdks/deep-dives/testing 200 https://buildwithfern.com/learn/sdks/deep-dives/testing All 136 distinct rewritten targets were confirmed to return 200. Links inside fenced code blocks and inline code spans are left alone, since those are illustrative — the ElevenLabs sample content in developer-tools/cursor.mdx and the pet/plant store demo API links are examples, not live cross-references. 404: /learn/api-definitions/protobuf Third most-hit 404. Protobuf content lives under gRPC, so this now redirects to /learn/api-definitions/grpc/overview. `fern export` code block marked unhelpful The flagged block listed the `.yml` and `.json` invocations on consecutive lines, reading as two commands to run rather than one choice of output format, and never said the path argument is the file being written. Both pages now state that the path is the output file and present the formats as alternatives. Also documents `--indent` (added in CLI 3.42.x, previously only in the changelog) and fixes the broken indentation that was rendering the export-openapi.mdx code block inside a stray blockquote. Co-Authored-By: Claude <noreply@anthropic.com>
Links in the Chinese pages pointed at /learn/..., which drops readers back
into the English site mid-navigation. They now point at /learn/zh/... so a
reader who starts in Chinese stays in Chinese.
Canonicalize legacy paths first
The redirects in docs.yml are declared with /learn/... sources, so they do
not fire under the /learn/zh/ locale prefix. Ten links were relying on a
redirect — harmless in English, a hard 404 once the locale segment is
added. Those now point at their canonical destination:
/learn/ask-fern/getting-started/what-is-ask-fern
-> /learn/docs/ai-features/ask-fern/overview
/learn/docs/writing-content/markdown
-> /learn/docs/writing-content/markdown-basics
...and eight more, listed in the rewrite table.
Fern serves English content at a zh URL when a page has not been
translated, so partial translation coverage is not a problem — only these
redirect-dependent paths were.
Also fixes two genuinely broken links
- publishing-your-docs.md 404'd in English and Chinese: the page lives
under preview-publish, and the link carried a stray .md extension.
- Two "Full reference" links to site-level-settings.md resolved, but .md
is Fern's view-as-raw-markdown feature — a prose link should open the
rendered page, not the source.
Verified: all 540 distinct /learn targets in the repo return 200, checked
against the live site. The two remaining bare /learn links in zh are
inside an mdx code fence demonstrating link syntax, so they are left as-is.
Co-Authored-By: Claude <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
|
|
||
| <Warning>This page is empty. Please visit the [AsyncAPI Definition](/api-definitions/asyncapi/overview) page for more information.</Warning> No newline at end of file | ||
| <Warning>This page is empty. Please visit the [AsyncAPI Definition](/learn/api-definitions/asyncapi/overview) page for more information.</Warning> No newline at end of file |
Contributor
There was a problem hiding this comment.
[FernStyles.Please] Avoid using 'Please' in technical documentation.
|
|
||
|
|
||
| <Warning>This page is empty. Please visit the [Fern Definition](/api-definitions/ferndef/overview) page for more information.</Warning> No newline at end of file | ||
| <Warning>This page is empty. Please visit the [Fern Definition](/learn/api-definitions/ferndef/overview) page for more information.</Warning> No newline at end of file |
Contributor
There was a problem hiding this comment.
[FernStyles.Please] Avoid using 'Please' in technical documentation.
|
|
||
|
|
||
| <Warning>This page is empty. Please visit the [gRPC Definition](/api-definitions/grpc/overview) page for more information.</Warning> No newline at end of file | ||
| <Warning>This page is empty. Please visit the [gRPC Definition](/learn/api-definitions/grpc/overview) page for more information.</Warning> No newline at end of file |
Contributor
There was a problem hiding this comment.
[FernStyles.Please] Avoid using 'Please' in technical documentation.
|
|
||
|
|
||
| <Warning>This page is empty. Please visit the [OpenAPI Definition](/api-definitions/openapi/overview) page for more information.</Warning> No newline at end of file | ||
| <Warning>This page is empty. Please visit the [OpenAPI Definition](/learn/api-definitions/openapi/overview) page for more information.</Warning> No newline at end of file |
Contributor
There was a problem hiding this comment.
[FernStyles.Please] Avoid using 'Please' in technical documentation.
|
|
||
|
|
||
| <Warning>This page is empty. Please visit the [OpenRPC Definition](/api-definitions/openrpc/overview) page for more information.</Warning> No newline at end of file | ||
| <Warning>This page is empty. Please visit the [OpenRPC Definition](/learn/api-definitions/openrpc/overview) page for more information.</Warning> No newline at end of file |
Contributor
There was a problem hiding this comment.
[FernStyles.Please] Avoid using 'Please' in technical documentation.
| </ParamField> | ||
|
|
||
| <ParamField path="header" type="string" required={false} toc={true}> | ||
| 自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 的默认页头。组件必须有默认导出。了解更多关于[自定义页头和页脚组件](/learn/docs/customization/header-and-footer)的信息。 | ||
| 自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 的默认页头。组件必须有默认导出。了解更多关于[自定义页头和页脚组件](/learn/zh/docs/customization/header-and-footer)的信息。 |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'TSX' has no definition.
| </ParamField> | ||
|
|
||
| <ParamField path="footer" type="string" required={false} toc={true}> | ||
| 自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 的默认页脚。组件必须有默认导出。了解更多关于[自定义页头和页脚组件](/learn/docs/customization/header-and-footer)的信息。 | ||
| 自定义 React 组件文件（TSX 或 JSX）的路径，用于替换 Fern 的默认页脚。组件必须有默认导出。了解更多关于[自定义页头和页脚组件](/learn/zh/docs/customization/header-and-footer)的信息。 |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'TSX' has no definition.
| </Info> | ||
|
|
||
| ## 配置 SDK 包设置 | ||
|
|
||
| 您需要更新 `generators.yml` 文件来配置包名称、输出位置和客户端名称，以便 NuGet 发布。您的 `generators.yml` [应该放在您的源代码仓库中](/sdks/overview/project-structure)（或本地机器上），而不是包含 C#/.NET SDK 代码的仓库中。 | ||
| 您需要更新 `generators.yml` 文件来配置包名称、输出位置和客户端名称，以便 NuGet 发布。您的 `generators.yml` [应该放在您的源代码仓库中](/learn/zh/sdks/overview/project-structure)（或本地机器上），而不是包含 C#/.NET SDK 代码的仓库中。 |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.Uppercase] Don't use all uppercase for emphasis.
| - [Python](/learn/zh/sdks/generators/python/quickstart): 生成 Python SDK 的快速开始指南。 | ||
| - [Go](/learn/zh/sdks/generators/go/quickstart): 生成 Go SDK 的快速开始指南。 | ||
| - [Java](/learn/zh/sdks/generators/java/quickstart): 生成 Java SDK 的快速开始指南。 | ||
| - [.NET](/learn/zh/sdks/generators/csharp/quickstart): 生成 .NET SDK 的快速开始指南。 |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.Uppercase] Don't use all uppercase for emphasis.
| - [Go](/learn/zh/sdks/generators/go/quickstart): 生成 Go SDK 的快速开始指南。 | ||
| - [Java](/learn/zh/sdks/generators/java/quickstart): 生成 Java SDK 的快速开始指南。 | ||
| - [.NET](/learn/zh/sdks/generators/csharp/quickstart): 生成 .NET SDK 的快速开始指南。 | ||
| - [PHP](/learn/zh/sdks/generators/php/quickstart): 生成 PHP SDK 的快速开始指南。 |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Microsoft.Uppercase] Don't use all uppercase for emphasis.
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes issues surfaced by reader feedback and 404 analytics on
buildwithfern.com/learnover the last 30 days.1. Internal links missing the
/learnprefix (596 links, 158 files)Two readers reported that Ask AI handed them links that 404, one noting the links were "missing the
/learnsubdomain that is present in all Fern docs links."The root cause is in the source, not in Ask AI: internal links were written product-root-relative (
/sdks/...,/docs/...) rather than site-absolute (/learn/sdks/...). Docs serve under/learn, so these 404 for readers directly, and Ask AI cites them verbatim.Links inside fenced code blocks and inline code spans are deliberately left alone — the ElevenLabs sample content in
developer-tools/cursor.mdxand the pet/plant-store demo API links are illustrative, not live cross-references.2. zh translations now stay in-locale
Chinese pages linked to
/learn/..., dropping readers back into the English site mid-navigation. They now link to/learn/zh/....This required canonicalizing legacy paths first. The redirects in
docs.ymlare declared with/learn/...sources, so they don't fire under the locale prefix — ten links were relying on a redirect, which is harmless in English but a hard 404 once/zh/is added. Those now point at their canonical destination, e.g.:/learn/ask-fern/getting-started/what-is-ask-fern/learn/docs/ai-features/ask-fern/overview/learn/docs/writing-content/markdown/learn/docs/writing-content/markdown-basics/learn/docs/enterprise/self-hosted/learn/docs/self-hosted/overviewPartial translation coverage turned out not to be a concern: Fern serves English content at a zh URL when a page isn't translated. Only the redirect-dependent paths broke.
3. 404:
/learn/api-definitions/protobufThird most-hit 404 in analytics. Protobuf content lives under gRPC, so this now redirects to
/learn/api-definitions/grpc/overview.4.
fern exportcode block voted unhelpfulThe flagged block listed the
.ymland.jsoninvocations on consecutive lines, reading as two commands to run rather than one choice of output format, and never stated that the path argument is the file being written. Both pages now say so and present the formats as alternatives. Also documents--indent(added in CLI 3.42.x, previously only in the changelog) and fixes indentation that was rendering one block inside a stray blockquote.5. Two genuinely broken links
publishing-your-docs.md404'd in both languages — the page lives underpreview-publish, and the link carried a stray.md.site-level-settings.mdresolved, but.mdis Fern's view-as-raw-markdown feature; a prose link should open the rendered page.Verification
Every distinct
/learntarget in the repo — 540 of them — was checked against the live site. All return 200.Note for reviewers
The English pages still contain the same legacy redirect-dependent paths that I canonicalized on the zh side (they work, via redirect). I left them alone to keep this diff scoped, but pointing both trees at canonical destinations would be worth a follow-up.
Generated with Claude Code