Merge branch 'main' into docs-polish

Author: devalog

.github/workflows/check-links.yml

@@ -0,0 +1,82 @@
+name: Check Links
+
+on:
+  # Run monday mornings
+  schedule:
+    - cron: '0 12 * * MON'
+  workflow_dispatch:
+jobs:
+  check-links:
+    name: Check links
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        site:
+        - name: Fern Docs
+          url: "buildwithfern.com/learn"
+    steps:
+      - name: Install link checker
+        run: pip install linkchecker
+      - name: Create config
+        run: echo -e "[csv]\nseparator=,\n[filtering]\nignore=\n\texample.com\n\tus.i.posthog.com\n\tc.vialoops.com/CL0\n[output]\nignoreerrors=\n  ^http ^403 Forbidden" > lcconfig
+      - name: Check ${{ matrix.site.name }} Links
+        run: |
+          set +e
+          cat lcconfig
+          linkchecker https://${{ matrix.site.url }} --check-extern --no-status --no-warnings --config lcconfig -F csv/utf-8/link_report.csv
+
+          if [ $? -ne 0 ]; then
+            echo "Bad links found. Please see report."
+          else
+            echo "Check completed. No issues found."
+            exit 0
+          fi
+
+          echo "Scan done, generating summary"
+
+          started=false
+          shouldfail=false
+          while read p; do
+            # skip comments (top and bottom)
+            if [[ $p == \#* ]]; then
+              continue
+            fi
+            # make sure first line after comments is skipped
+            if [[ "$started" = false ]]; then
+              started=true
+              continue
+            fi
+            
+            IFS=',' read -r -a array <<< "$p"
+
+            ret=$(curl -I -s "${array[0]}" -o /dev/null -w "%{http_code}\n")
+            if [[ $ret == 200 ]]; then
+              echo "Site now seems to be working, we should continue here"
+              continue
+            else
+              echo "There is still an issue with ${array[0]}"
+            fi
+
+            shouldfail=true
+
+            if [[ ${array[10]} == '' ]]; then
+              echo "::error::URL: ${array[0]} on page: ${array[1]} is returning a ${array[3]}"
+            else
+              echo "::error::URL: ${array[0]} linked from '${array[10]}' on page: ${array[1]} is returning a ${array[3]}"
+            fi
+
+          done < link_report.csv
+
+          if [[ "$shouldfail" = false ]]; then
+            exit 0
+          fi
+            
+          exit 1
+
+      - name: Upload report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: Report - ${{ matrix.site.name }}
+          path: link_report.csv

fern/docs.yml

@@ -325,7 +325,7 @@ redirects:
     destination: https://buildwithfern.com/customers
     permanent: true
   - source: /learn/docs/getting-started/global-configuration
-    destination: /learn/docs/customization/what-is-docs-yml
+    destination: /learn/docs/configuration/what-is-docs-yml
     permanent: true
   - source: /learn/docs/getting-started/development
     destination: /learn/docs/preview-publish/previewing-changes-locally
@@ -378,7 +378,7 @@ redirects:
     destination: /learn/docs/customization/custom-css-js
     permanent: true
   - source: /learn/docs/building-and-customizing-your-docs/custom-domain
-    destination: /learn/docs/getting-started/setting-up-your-domain
+    destination: /learn/docs/preview-publish/setting-up-your-domain
     permanent: true
   - source: /learn/docs/building-and-customizing-your-docs/rbac
     destination: /learn/docs/authentication/rbac
@@ -549,7 +549,7 @@ redirects:
     destination: https://buildwithfern.com/customers
     permanent: true
   - source: /learn/ask-fern/citations
-    destination: /learn/ask-fern/configuration/citations
+    destination: /learn/ask-fern/features/citations
     permanent: true
   - source: /learn/ask-fern/custom-prompting
     destination: /learn/ask-fern/configuration/custom-prompting

fern/products/api-def/openapi-pages/extensions/overview.md

@@ -14,10 +14,10 @@ The table below shows all available extensions and links to detailed documentati
 | [`x-fern-audiences`](./audiences) | Filter endpoints, schemas, and properties by audience |
 | [`x-fern-availability`](./availability) | Mark availability status (beta, generally-available, deprecated) |
 | [`x-fern-base-path`](./base-path) | Set base path prepended to all endpoints |
-| [`x-fern-enum`](./enums) | Add descriptions and custom names to enum values |
-| [`x-fern-examples`](./examples) | Associate request and response examples |
+| [`x-fern-enum`](./enum-descriptions-and-names) | Add descriptions and custom names to enum values |
+| [`x-fern-examples`](./request-response-examples) | Associate request and response examples |
 | [`x-fern-global-headers`](./global-headers) | Configure headers used across all endpoints |
-| [`x-fern-ignore`](./ignore) | Skip reading specific endpoints or schemas |
+| [`x-fern-ignore`](./ignoring-elements) | Skip reading specific endpoints or schemas |
 | [`x-fern-sdk-method-name`](./method-names) | Customize SDK method names |
 | [`x-fern-sdk-group-name`](./method-names) | Organize methods into SDK groups |
 | [`x-fern-parameter-name`](./parameter-names) | Customize parameter variable names |
@@ -33,4 +33,4 @@ The table below shows all available extensions and links to detailed documentati
 
 ### FastAPI
 
-FastAPI allows you to add extensions directly in your route decorators and models. See our [FastAPI integration guide](/api-definition/openapi/frameworks/fastapi) for detailed examples.
+FastAPI allows you to add extensions directly in your route decorators and models. See our [FastAPI integration guide](/learn/api-definitions/openapi/frameworks/fastapi) for detailed examples.

fern/products/api-def/pages/project-structure.mdx

@@ -1,5 +1,5 @@
 ---
-title: The Fern Folder
+title: Project structure
 description: Describes the Fern folder structure
 ---
 
@@ -15,22 +15,15 @@ fern/
   ├─ fern.config.json # Root-level config for entire Fern project
   ├─ generators.yml # Defines SDKs and docs to generate
   └─ spec-folder/ # definition, openapi, asyncapi, etc.
-    └─ spec-file.yml # API specification file
+    └─ spec-file.yml # API definition file
 ```
 
-<Info>
-  For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information. 
-
-  For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. 
-</Info>
-
-<AccordionGroup>
-<Accordion title="What is the fern.config.json file?">
+### `fern.config.json file`
 
 Every fern folder has a single `fern.config.json` file. This file stores the organization and
 the version of the Fern CLI that you are using. 
 
-```json
+```json title="fern.config.json"
 {
     "organization": "your-organization",
     "version": "0.31.2"
@@ -39,35 +32,22 @@ the version of the Fern CLI that you are using.
 
 Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure 
 determinism. 
-</Accordion>
-<Accordion title="What is the generators.yml file?">
 
-The `generators.yml` file includes information about where your API definition file is located. It also configures the SDKs you're generating for your API. 
+### `generators.yml`
+
+The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/github) you're generating for your API. 
 
-```yaml
+```yaml title="generators.yml"
 api: 
   path: ./path/to/openapi.yml
 ```
-</Accordion>
-</AccordionGroup>
 
-## Multiple APIs
+### API definition file
 
-The fern folder can house multiple API definitions. When you have multiple APIs, nest your definition files within an `apis` folder. 
+  For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information. 
 
-Each API must also have a separate `generators.yml` file that specifies the location of the API definition and configures SDK generation.
+  For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. 
 
-```bash
-fern/
-  ├─ fern.config.json
-  ├─ generators.yml # Optional: top-level configuration for all APIs
-  └─ apis/
-    └─ first-api/ # First API
-        ├─ generators.yml # Required: points to API spec
-        └─ openapi/
-          ├─ openapi.yml # API Definition file
-    └─ second-api/ # Second API
-        ├─ generators.yml # Required: points to API spec
-        └─ openapi/
-          ├─ openapi.yml # API Definition file
-```
+## Multiple API definitions
+
+<Markdown src="/snippets/multiple-apis.mdx" />

fern/products/ask-fern/pages/getting-started/what-is-ask-fern.mdx

@@ -33,7 +33,7 @@ Fern AI Search indexes your documentation and provides an interface for your use
   <Card 
     title="Citations" 
     icon="regular quote-right"
-    href="/learn/ai-search/citations" 
+    href="/learn/ask-fern/features/citations" 
     >
     Point users to the exact source of the answer. 
   </Card>

fern/products/docs/pages/changelog/2025-05-23.mdx

@@ -2,4 +2,4 @@
 
 We've added a `max-toc-depth` frontmatter option to control the depth of the table of contents. Use this to limit the heading ranks included in the table of contents.
 
-You can read more about this feature in the [frontmatter documentation](/learn/docs/content/frontmatter#max-depth).
+You can read more about this feature in the [frontmatter documentation](/learn/docs/configuration/page-level-settings#max-depth).

fern/products/docs/pages/component-library/custom-components/custom-css-js.mdx

@@ -56,7 +56,7 @@ css:
 
 <Note>
 For customizing the background, logo, font, and layout of your Docs via Fern's built-in styling, 
-check out the [Global Configuration](/learn/docs/getting-started/global-configuration). 
+check out the [Global Configuration](/learn/docs/configuration/what-is-docs-yml). 
 </Note>
 
 ### Common use cases

fern/products/docs/pages/component-library/default-components/code-blocks.mdx

@@ -306,9 +306,16 @@ The `CodeBlocks` component allows you to display multiple code blocks in a tabbe
   </Tab>
 </Tabs>
 
-## Example of Synchronized Blocks
+## Language synchronization
 
-Multiple `CodeBlocks` on a page automatically synchronize, showing the same language across all blocks.
+Multiple `CodeBlocks` on a documentation site automatically synchronize. This
+means when a user selects a `CodeBlock` with a specific language, all other
+`CodeBlocks` across your documentation site with the same language will
+automatically sync and switch to match. Language preferences are stored in
+client-side local storage and persist across browser sessions.
+
+The example below demonstrates language sync in action – choosing a language in
+either set of code blocks will automatically update both sets to match:
 
 <CodeBlocks>
   ```python title="Python"
@@ -362,6 +369,10 @@ Multiple `CodeBlocks` on a page automatically synchronize, showing the same lang
   ```
 </CodeBlocks>
 
+<Note title="Tabs and CodeBlocks integration">
+  `CodeBlocks` automatically synchronize with [`<Tab>` components that have a `language` property](/docs/writing-content/components/tabs#language-synchronization).
+</Note>
+
 ### Override synchronization
 
 You can override the synchronization of code blocks by setting the `for` prop.