diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx
index 642f8251d..0a5295d19 100644
--- a/fern/products/cli-api-reference/pages/commands.mdx
+++ b/fern/products/cli-api-reference/pages/commands.mdx
@@ -276,12 +276,14 @@ 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.
+ 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
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..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
@@ -55,14 +55,27 @@ 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:
-
-```mdx
-Read the [Introduction](/learn/sdks/overview/introduction).
+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 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.
```
+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).
+
+### 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 f0e84985b..d1d21cb0b 100644
--- a/fern/products/docs/pages/seo/redirects.mdx
+++ b/fern/products/docs/pages/seo/redirects.mdx
@@ -14,7 +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.
+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`.
## 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.