From 60342d58228abbc61dc7ac1daecf08741d0def75 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Mon, 30 Mar 2026 16:29:06 +0000
Subject: [PATCH 1/3] docs: document check.rules configuration for fern check
---
.../cli-api-reference/pages/commands.mdx | 21 ++++++++--
.../customization/site-level-settings.mdx | 39 +++++++++++++++++++
2 files changed, 56 insertions(+), 4 deletions(-)
diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx
index 82b88c350..d039d4de4 100644
--- a/fern/products/cli-api-reference/pages/commands.mdx
+++ b/fern/products/cli-api-reference/pages/commands.mdx
@@ -312,7 +312,11 @@ hideOnThisPage: true
fern check --warnings
```
- ### strict-broken-links
+ ### strict-broken-links (deprecated)
+
+
+ The `--broken-links` and `--strict-broken-links` flags are deprecated. Use `check.rules` in `docs.yml` instead. See [check configuration](/learn/docs/configuration/site-level-settings#check-configuration).
+
Use `--strict-broken-links` to fail the command if any broken links are found in your API docs.
@@ -320,9 +324,18 @@ hideOnThisPage: true
fern check --strict-broken-links
```
-
- For comprehensive link checking, use the [Fern Dashboard](https://dashboard.buildwithfern.com/), which validates both internal and external links on your live published site. This is recommended over `--strict-broken-links` because the Dashboard checks your actual published site and can verify external links that the CLI cannot.
-
+ ### Configuring rule severity
+
+ You can configure the severity of validation rules run by `fern check` in your `docs.yml` file using the `check.rules` property. Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking).
+
+ ```yaml docs.yml
+ check:
+ rules:
+ broken-links: error
+ example-validation: warn
+ ```
+
+ See [check configuration](/learn/docs/configuration/site-level-settings#check-configuration) for the full list of available rules and their defaults.
## Usage in a GitHub Action
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
index 441c76c4a..f651b58bb 100644
--- a/fern/products/docs/pages/customization/site-level-settings.mdx
+++ b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -1001,6 +1001,45 @@ ai-examples:
Instructions to guide the content and style of AI-generated examples in your API Reference. Use this to align examples with your brand or domain. Limited to 500 characters.
+## Check configuration
+
+Configure the severity of validation rules run by [`fern check`](/learn/cli-api/cli-reference/commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking).
+
+```yaml docs.yml
+check:
+ rules:
+ broken-links: error
+ example-validation: warn
+ no-non-component-refs: error
+ valid-local-references: warn
+ no-circular-redirects: error
+ valid-docs-endpoints: warn
+```
+
+
+ Severity for broken link detection. Defaults to `error` for broken internal links and `warn` for malformed URLs. Replaces the deprecated `--broken-links` and `--strict-broken-links` CLI flags.
+
+
+
+ Severity for OpenAPI example validation.
+
+
+
+ Severity for non-component OpenAPI reference validation. Flags `$ref` values that point outside the `#/components` section of an OpenAPI spec.
+
+
+
+ Severity for local OpenAPI reference validation. Checks that local `$ref` values resolve to existing definitions.
+
+
+
+ Severity for circular redirect validation. Detects redirect chains that loop back to a previously visited path.
+
+
+
+ Severity for docs endpoint URL validation. Checks that endpoint URLs referenced in `docs.yml` are well-formed.
+
+
## Experimental configuration
Configure experimental features in the `experimental` section of your `docs.yml`.
From 9b28bc94cc1d1f45ea88585c02fc4197c59df560 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Mon, 30 Mar 2026 16:31:32 +0000
Subject: [PATCH 2/3] fix: use single quotes in ParamField type attributes for
MDX compatibility
---
.../docs/pages/customization/site-level-settings.mdx | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
index f651b58bb..04a67bb40 100644
--- a/fern/products/docs/pages/customization/site-level-settings.mdx
+++ b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -1016,27 +1016,27 @@ check:
valid-docs-endpoints: warn
```
-
+
Severity for broken link detection. Defaults to `error` for broken internal links and `warn` for malformed URLs. Replaces the deprecated `--broken-links` and `--strict-broken-links` CLI flags.
-
+
Severity for OpenAPI example validation.
-
+
Severity for non-component OpenAPI reference validation. Flags `$ref` values that point outside the `#/components` section of an OpenAPI spec.
-
+
Severity for local OpenAPI reference validation. Checks that local `$ref` values resolve to existing definitions.
-
+
Severity for circular redirect validation. Detects redirect chains that loop back to a previously visited path.
-
+
Severity for docs endpoint URL validation. Checks that endpoint URLs referenced in `docs.yml` are well-formed.
From db3596c9b43f4e2e182c524dfb8f13a50f10cbca Mon Sep 17 00:00:00 2001
From: Devin Logan
Date: Tue, 31 Mar 2026 07:35:22 -0400
Subject: [PATCH 3/3] clarify text
---
.../cli-api-reference/pages/commands.mdx | 42 +++++++------------
.../docs/pages/changelog/2026-03-31.mdx | 18 ++++++++
.../customization/site-level-settings.mdx | 10 ++---
3 files changed, 36 insertions(+), 34 deletions(-)
create mode 100644 fern/products/docs/pages/changelog/2026-03-31.mdx
diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx
index d039d4de4..cf1a0be0d 100644
--- a/fern/products/cli-api-reference/pages/commands.mdx
+++ b/fern/products/cli-api-reference/pages/commands.mdx
@@ -286,9 +286,13 @@ hideOnThisPage: true
- Use `fern check` to validate your API definition and Fern configuration: [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`.
+
+ 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.
+
- When successfully executed, this command will not produce any output.
+ 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.
```bash
@@ -296,6 +300,15 @@ hideOnThisPage: true
```
+ You can configure the severity of the validation rules run by `fern check` in your `docs.yml` file [using the `check.rules` property](/learn/docs/configuration/site-level-settings#check-configuration).
+
+ ```yaml docs.yml
+ check:
+ rules:
+ broken-links: error
+ example-validation: warn
+ ```
+
### api
Use `--api ` to specify which API you'd like to check.
@@ -312,31 +325,6 @@ hideOnThisPage: true
fern check --warnings
```
- ### strict-broken-links (deprecated)
-
-
- The `--broken-links` and `--strict-broken-links` flags are deprecated. Use `check.rules` in `docs.yml` instead. See [check configuration](/learn/docs/configuration/site-level-settings#check-configuration).
-
-
- Use `--strict-broken-links` to fail the command if any broken links are found in your API docs.
-
- ```bash
- fern check --strict-broken-links
- ```
-
- ### Configuring rule severity
-
- You can configure the severity of validation rules run by `fern check` in your `docs.yml` file using the `check.rules` property. Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking).
-
- ```yaml docs.yml
- check:
- rules:
- broken-links: error
- example-validation: warn
- ```
-
- See [check configuration](/learn/docs/configuration/site-level-settings#check-configuration) for the full list of available rules and their defaults.
-
## Usage in a GitHub Action
diff --git a/fern/products/docs/pages/changelog/2026-03-31.mdx b/fern/products/docs/pages/changelog/2026-03-31.mdx
new file mode 100644
index 000000000..d0045bc4b
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-03-31.mdx
@@ -0,0 +1,18 @@
+---
+tags: ["configuration", "docs.yml"]
+---
+
+## Configure `fern check` rule severity
+
+You can now configure the severity of validation rules run by `fern check` directly in your `docs.yml` file using the `check.rules` property. Set individual rules to `"warn"` (non-blocking) or `"error"` (blocking) to control which checks fail your build.
+
+```yaml docs.yml
+check:
+ rules:
+ broken-links: error
+ example-validation: warn
+```
+
+The `--broken-links` and `--strict-broken-links` CLI flags are now deprecated in favor of this configuration.
+
+
diff --git a/fern/products/docs/pages/customization/site-level-settings.mdx b/fern/products/docs/pages/customization/site-level-settings.mdx
index 04a67bb40..1b5842f8f 100644
--- a/fern/products/docs/pages/customization/site-level-settings.mdx
+++ b/fern/products/docs/pages/customization/site-level-settings.mdx
@@ -1003,17 +1003,13 @@ ai-examples:
## Check configuration
-Configure the severity of validation rules run by [`fern check`](/learn/cli-api/cli-reference/commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking).
+Configure the severity of validation rules run by [`fern check`](/learn/cli-api-reference/cli-reference/commands#fern-check). Each rule can be set to `"warn"` (non-blocking) or `"error"` (blocking).
```yaml docs.yml
check:
rules:
- broken-links: error
- example-validation: warn
- no-non-component-refs: error
- valid-local-references: warn
- no-circular-redirects: error
- valid-docs-endpoints: warn
+ broken-links: warn
+ example-validation: error
```