From cff1c1408f2ee44f9e8d4bdaa81575b3433e3824 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 16:01:01 +0000 Subject: [PATCH 1/6] Clarify link behavior, link checking, and redirects validation --- .../cli-api-reference/pages/commands.mdx | 2 + .../writing-content/markdown-basics.mdx | 46 ++++++++++++++++++- fern/products/docs/pages/seo/redirects.mdx | 20 ++++++++ fern/products/docs/snippets/redirects.mdx | 4 +- 4 files changed, 68 insertions(+), 4 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 642f8251d..567905e17 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -282,6 +282,8 @@ hideOnThisPage: true Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. + `fern check` validates against the navigation tree built from your **local** config — it does not crawl your live deployed site or follow external URLs. To check links on a published site (including external URLs), use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + ```bash fern check [--api ] [--warnings] diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index bd867092d..d99c9ba2c 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -55,14 +55,56 @@ Because the `

` is generated automatically, you should begin your page conten ## Links in Markdown ### Link format -Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows: - +To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your `docs.yml` and product YAML files (see [Navigation](/learn/docs/configuration/navigation)) — not the file's location on disk and not a path relative to the current Markdown file. + + ```mdx Read the [Introduction](/learn/sdks/overview/introduction). ``` +If your docs are hosted on a subpath (such as `buildwithfern.com/learn`), include the subpath. To link to a heading on another page, append `#anchor` to the path — for example, `/learn/docs/configuration/navigation#section-availability`. + + +File-relative paths like `./getting-started/overview` or `../shared.mdx` aren't supported for inter-page links — use the published site path instead. File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media), and for `path:` references inside YAML config. + + +### Links in versioned docs + +If your site has [versions](/learn/docs/configuration/versions), the path you write determines which version a reader lands on: + +- The **default version** publishes at unversioned paths (e.g. `/learn/docs/getting-started`). +- **Other versions** publish at versioned paths (e.g. `/learn/docs/v2/getting-started`). + +When the same page is referenced from multiple versions — for example, a shared file in a `common/` folder that each version's YAML pulls in — the file is published once per version, at the corresponding URL. Linking with the unversioned path always sends readers to the default version. To keep readers in a non-default version's context, link to that version's path explicitly: + +```mdx + +[Authentication](/learn/docs/authentication) + + +[Authentication](/learn/docs/v2/authentication) +``` + + +To switch content inline based on the active version without changing the link target, use the [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions) components. + + +### Validate links locally + +[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) — including the validation run that fires during `fern docs dev` — checks internal links against the navigation tree built from your **local** `docs.yml` and product YAML files. It does not crawl your live deployed site or follow external URLs. A link that works on the deployed site can still flag locally if your local config doesn't yet contain the destination's slug (and vice versa). + +To control noise — for example, during a docs migration — set the [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) to `warn` in `docs.yml`: + +```yaml docs.yml +check: + rules: + broken-links: warn +``` + +For checks against your live deployed site, including external URLs, use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/). + ### API link syntax diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index f0e84985b..9479027d9 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -16,6 +16,26 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir You can use [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) to automatically detect pages that were removed or moved without a redirect. Configure the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` to control its severity. +### How `missing-redirects` works + +The check compares the navigation tree built from your **local** config against the navigation tree of your most recently **published** site, then flags any previously-published URL that no longer resolves and is not covered by an entry in `redirects:`. Because it reads the published state, it requires authentication — run [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) first, or set the `FERN_TOKEN` environment variable. The check is skipped when authentication is missing, when the network is unavailable, or on a site's first publish. + +This means warnings reflect the diff against the last publish, not against your `main` branch or a specific commit. The check only knows about pages that were live the last time you ran `fern generate --docs`. + + +During a large migration where redirect warnings aren't actionable yet, downgrade the rule to a warning or skip it entirely: + +```yaml docs.yml +check: + rules: + missing-redirects: warn # or `error` once you're ready to enforce +``` + +You can also run `fern check` unauthenticated (without `fern login` and without `FERN_TOKEN`) to skip the check temporarily. Once the migration is stable, log back in and re-enable the rule. + + +If a moved file isn't being flagged, that's usually because it wasn't part of the last published navigation — the check only compares against the most recent publish, so files added and moved within the same un-published batch of changes won't appear. + ## Common errors diff --git a/fern/products/docs/snippets/redirects.mdx b/fern/products/docs/snippets/redirects.mdx index 88049b8d0..55032b68f 100644 --- a/fern/products/docs/snippets/redirects.mdx +++ b/fern/products/docs/snippets/redirects.mdx @@ -66,14 +66,14 @@ settings: -If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/getting-started/v2`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs. +If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/v2/getting-started`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs. Avoid redirecting from unversioned to versioned URLs: ```yaml title="docs.yml" redirects: - source: /docs/event-notifications - destination: /docs/event-notifications/v2 # Don't do this + destination: /docs/v2/event-notifications # Don't do this ``` Manually overriding the default versioning behavior can lead to unexpected redirect patterns. From 342bd394387508aa47c929d3b910c8f7185cdf52 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 20:03:13 +0000 Subject: [PATCH 2/6] Condense link/redirect clarifications and lean on cross-references --- .../writing-content/markdown-basics.mdx | 43 +++---------------- fern/products/docs/pages/seo/redirects.mdx | 22 +--------- 2 files changed, 9 insertions(+), 56 deletions(-) diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index d99c9ba2c..2a0d8cc13 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -56,7 +56,7 @@ Because the `

` is generated automatically, you should begin your page conten ### Link format -To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your `docs.yml` and product YAML files (see [Navigation](/learn/docs/configuration/navigation)) — not the file's location on disk and not a path relative to the current Markdown file. +To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your `docs.yml` and product YAML files (see [Navigation](/learn/docs/configuration/navigation)) — not from the file's location on disk. ```mdx @@ -64,47 +64,18 @@ Read the [Introduction](/learn/sdks/overview/introduction). ``` -If your docs are hosted on a subpath (such as `buildwithfern.com/learn`), include the subpath. To link to a heading on another page, append `#anchor` to the path — for example, `/learn/docs/configuration/navigation#section-availability`. +To link to a heading on another page, append `#anchor`: `/learn/docs/configuration/navigation#section-availability`. - -File-relative paths like `./getting-started/overview` or `../shared.mdx` aren't supported for inter-page links — use the published site path instead. File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media), and for `path:` references inside YAML config. + +Use the published site path instead. File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media) and for `path:` references inside YAML config. -### Links in versioned docs +In [versioned docs](/learn/docs/configuration/versions), the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. `/learn/docs/v2/getting-started`). For inline version-specific content within a single page, use [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions). -If your site has [versions](/learn/docs/configuration/versions), the path you write determines which version a reader lands on: - -- The **default version** publishes at unversioned paths (e.g. `/learn/docs/getting-started`). -- **Other versions** publish at versioned paths (e.g. `/learn/docs/v2/getting-started`). - -When the same page is referenced from multiple versions — for example, a shared file in a `common/` folder that each version's YAML pulls in — the file is published once per version, at the corresponding URL. Linking with the unversioned path always sends readers to the default version. To keep readers in a non-default version's context, link to that version's path explicitly: - -```mdx - -[Authentication](/learn/docs/authentication) - - -[Authentication](/learn/docs/v2/authentication) -``` - - -To switch content inline based on the active version without changing the link target, use the [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions) components. + +[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) — including the run inside `fern docs dev` — validates internal links against your local YAML, not your deployed site. Tune severity with [`check.rules.broken-links`](/learn/docs/configuration/site-level-settings#check-configuration), or use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to check links on a published site. -### Validate links locally - -[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) — including the validation run that fires during `fern docs dev` — checks internal links against the navigation tree built from your **local** `docs.yml` and product YAML files. It does not crawl your live deployed site or follow external URLs. A link that works on the deployed site can still flag locally if your local config doesn't yet contain the destination's slug (and vice versa). - -To control noise — for example, during a docs migration — set the [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) to `warn` in `docs.yml`: - -```yaml docs.yml -check: - rules: - broken-links: warn -``` - -For checks against your live deployed site, including external URLs, use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/). - ### API link syntax diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index 9479027d9..c911b0f62 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -14,27 +14,9 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir ## Catching missing redirects -You can use [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) to automatically detect pages that were removed or moved without a redirect. Configure the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` to control its severity. +[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) compares your local navigation against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. Because it reads the published state, it requires [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable, and is skipped on first publish or when unauthenticated. Pages added and moved within the same un-published batch aren't compared. -### How `missing-redirects` works - -The check compares the navigation tree built from your **local** config against the navigation tree of your most recently **published** site, then flags any previously-published URL that no longer resolves and is not covered by an entry in `redirects:`. Because it reads the published state, it requires authentication — run [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) first, or set the `FERN_TOKEN` environment variable. The check is skipped when authentication is missing, when the network is unavailable, or on a site's first publish. - -This means warnings reflect the diff against the last publish, not against your `main` branch or a specific commit. The check only knows about pages that were live the last time you ran `fern generate --docs`. - - -During a large migration where redirect warnings aren't actionable yet, downgrade the rule to a warning or skip it entirely: - -```yaml docs.yml -check: - rules: - missing-redirects: warn # or `error` once you're ready to enforce -``` - -You can also run `fern check` unauthenticated (without `fern login` and without `FERN_TOKEN`) to skip the check temporarily. Once the migration is stable, log back in and re-enable the rule. - - -If a moved file isn't being flagged, that's usually because it wasn't part of the last published navigation — the check only compares against the most recent publish, so files added and moved within the same un-published batch of changes won't appear. +Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`, or run `fern check` unauthenticated to skip it during a migration. ## Common errors From 31b8291a87997c18fcd97ad8b6478940ea818a8e Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 20:06:24 +0000 Subject: [PATCH 3/6] Clarify which check is skipped when running fern check unauthenticated --- fern/products/docs/pages/seo/redirects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index c911b0f62..b51c5a004 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -16,7 +16,7 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) compares your local navigation against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. Because it reads the published state, it requires [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable, and is skipped on first publish or when unauthenticated. Pages added and moved within the same un-published batch aren't compared. -Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`, or run `fern check` unauthenticated to skip it during a migration. +Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`, or run `fern check` unauthenticated to skip the `missing-redirects` check during a migration. ## Common errors From 1af28feb368c3bd209cb50d8d13850a5d2666c88 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 21:11:42 +0000 Subject: [PATCH 4/6] Scope fern check scope statements to specific rules --- fern/products/cli-api-reference/pages/commands.mdx | 2 +- .../component-library/writing-content/markdown-basics.mdx | 4 ++-- fern/products/docs/pages/seo/redirects.mdx | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 567905e17..039bc7316 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -282,7 +282,7 @@ hideOnThisPage: true Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. - `fern check` validates against the navigation tree built from your **local** config — it does not crawl your live deployed site or follow external URLs. To check links on a published site (including external URLs), use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`. To check links on a published site (including external URLs), use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. ```bash diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index 2a0d8cc13..3c141bb11 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -72,8 +72,8 @@ Use the published site path instead. File-relative paths are still correct for [ In [versioned docs](/learn/docs/configuration/versions), the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. `/learn/docs/v2/getting-started`). For inline version-specific content within a single page, use [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions). - -[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) — including the run inside `fern docs dev` — validates internal links against your local YAML, not your deployed site. Tune severity with [`check.rules.broken-links`](/learn/docs/configuration/site-level-settings#check-configuration), or use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to check links on a published site. + +The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. It does not crawl your deployed site or follow external URLs. To check links on a published site, use the [Fern Dashboard](https://dashboard.buildwithfern.com/). ### API link syntax diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index b51c5a004..5375e07fb 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -14,9 +14,9 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir ## Catching missing redirects -[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) compares your local navigation against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. Because it reads the published state, it requires [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable, and is skipped on first publish or when unauthenticated. Pages added and moved within the same un-published batch aren't compared. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. Because it reads the published state, this rule (unlike other `fern check` rules) makes a network call and requires [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable. It is skipped on first publish or when unauthenticated. -Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`, or run `fern check` unauthenticated to skip the `missing-redirects` check during a migration. +Tune severity with the rule's `warn` / `error` setting in `docs.yml`, or run `fern check` unauthenticated to skip the `missing-redirects` check during a migration. ## Common errors From 1e029a9c0562d6da45f8ebf92a1cc596c7449dc7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 13 May 2026 18:13:28 -0400 Subject: [PATCH 5/6] clean up text --- .../cli-api-reference/pages/commands.mdx | 6 ++--- .../writing-content/markdown-basics.mdx | 24 +++++++++---------- fern/products/docs/pages/seo/redirects.mdx | 6 +++-- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 567905e17..0a5295d19 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -276,13 +276,13 @@ hideOnThisPage: true The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead. - - You can also use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to validate both internal and external links on your live published site. Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output. - `fern check` validates against the navigation tree built from your **local** config — it does not crawl your live deployed site or follow external URLs. To check links on a published site (including external URLs), use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. + Most `fern check` rules — including [`broken-links`](/learn/docs/configuration/site-level-settings#check-configuration) — validate against the navigation tree built from your **local** config and do not crawl your live deployed site or follow external URLs. The exception is the [`missing-redirects` rule](/learn/docs/seo/redirects#catching-missing-redirects), which compares your local navigation against the previously published state and therefore requires `fern login` or `FERN_TOKEN`. + + To check links on a published site, use the link checker in the [Fern Dashboard](https://dashboard.buildwithfern.com/) instead. When all checks pass, the command produces no output. ```bash diff --git a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx index 2a0d8cc13..0e004e30d 100644 --- a/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx +++ b/fern/products/docs/pages/component-library/writing-content/markdown-basics.mdx @@ -56,25 +56,25 @@ Because the `

` is generated automatically, you should begin your page conten ### Link format -To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your `docs.yml` and product YAML files (see [Navigation](/learn/docs/configuration/navigation)) — not from the file's location on disk. +To link to another page on your docs site, write the destination's **published site path**, starting with a `/`. Fern builds this path from the slugs in your [`docs.yml` and product YAML files](/learn/docs/configuration/navigation), not from the file's location on disk. To link to a heading on another page, append `#anchor` to the path. + + + File-relative paths like `./` and `../` aren't supported for inter-page links — use the published site path instead. (File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media) and for `path:` references inside YAML config.) + -```mdx -Read the [Introduction](/learn/sdks/overview/introduction). +```mdx wordWrap +Learn about [how Fern SDKs work](/learn/sdks/overview/how-it-works). + +Configure [sidebar icons](/learn/docs/configuration/navigation#sidebar-icons) to add visual cues to your navigation. ``` -To link to a heading on another page, append `#anchor`: `/learn/docs/configuration/navigation#section-availability`. - - -Use the published site path instead. File-relative paths are still correct for [images and other media](/learn/docs/writing-content/markdown-media) and for `path:` references inside YAML config. - - In [versioned docs](/learn/docs/configuration/versions), the same path lands on a different version depending on whether you write the unversioned form (default version) or the versioned form (e.g. `/learn/docs/v2/getting-started`). For inline version-specific content within a single page, use [``](/learn/docs/writing-content/components/if#by-version) or [``](/learn/docs/writing-content/components/versions). - -[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) — including the run inside `fern docs dev` — validates internal links against your local YAML, not your deployed site. Tune severity with [`check.rules.broken-links`](/learn/docs/configuration/site-level-settings#check-configuration), or use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to check links on a published site. - +### Validating links + +The [`broken-links` rule](/learn/docs/configuration/site-level-settings#check-configuration) — run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), including during `fern docs dev` — validates each internal link against the navigation tree built from your **local** YAML. It does not crawl your deployed site or follow external URLs. To check links on a published site, use the [Fern Dashboard](https://dashboard.buildwithfern.com/). ### API link syntax diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index b51c5a004..15bb1d8d1 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -14,9 +14,11 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir ## Catching missing redirects -[`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check) compares your local navigation against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. Because it reads the published state, it requires [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable, and is skipped on first publish or when unauthenticated. Pages added and moved within the same un-published batch aren't compared. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), warns you when a previously-published URL no longer resolves and isn't covered by an entry in your `redirects` entry. This catches pages you've moved or removed before they start returning 404s for existing inbound links. -Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`, or run `fern check` unauthenticated to skip the `missing-redirects` check during a migration. +Unlike other `fern check` rules, `missing-redirects` compares your local navigation against the live published site, so it makes a network call and requires authentication via [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable. The rule is skipped on first publish and when unauthenticated — useful if you want to bypass the check during a large migration. + +Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`. ## Common errors From 82524da7ff53d871b41aae4a67ce4f54e23a093c Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 13 May 2026 18:22:01 -0400 Subject: [PATCH 6/6] update --- fern/products/docs/pages/seo/redirects.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/fern/products/docs/pages/seo/redirects.mdx b/fern/products/docs/pages/seo/redirects.mdx index 15bb1d8d1..d1d21cb0b 100644 --- a/fern/products/docs/pages/seo/redirects.mdx +++ b/fern/products/docs/pages/seo/redirects.mdx @@ -14,9 +14,7 @@ subtitle: Learn how to configure redirects in Fern Docs. Set up exact path redir ## Catching missing redirects -The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), warns you when a previously-published URL no longer resolves and isn't covered by an entry in your `redirects` entry. This catches pages you've moved or removed before they start returning 404s for existing inbound links. - -Unlike other `fern check` rules, `missing-redirects` compares your local navigation against the live published site, so it makes a network call and requires authentication via [`fern login`](/learn/cli-api-reference/cli-reference/commands#fern-login) or the `FERN_TOKEN` environment variable. The rule is skipped on first publish and when unauthenticated — useful if you want to bypass the check during a large migration. +The [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration), run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check), compares the navigation tree built from your local YAML against the most recently **published** state of your site and flags previously-published URLs that no longer resolve and aren't covered by an entry in `redirects:`. This catches pages you've moved or removed before they start returning 404s for existing inbound links. Tune severity with the [`missing-redirects` rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml`.