Fix broken internal links, keep zh links in-locale, and clarify fern export

fern/docs.yml

@@ -695,6 +695,8 @@ redirects:
     destination: /learn/api-definitions/grpc/overview
   - source: /learn/grpc-definition/:slug*
     destination: /learn/api-definitions/grpc/:slug*
+  - source: /learn/api-definitions/protobuf
+    destination: /learn/api-definitions/grpc/overview
 
   # FernDef (specifics before catchall — comparison-with-open-api was shadowed)
   - source: /learn/api-definition/fern/comparison-with-open-api

fern/products/api-def/ferndef/api-yml/global-configuration.mdx

@@ -21,7 +21,7 @@ headers:
 ```
 </CodeBlock>
 
-When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/api-definitions/ferndef/examples#examples-with-headers).
+When you define global headers in your `api.yml`, you must [include them in your endpoint examples](/learn/api-definitions/ferndef/examples#examples-with-headers).
 
 ## Global path parameters
 

fern/products/api-def/ferndef/auth.mdx

@@ -247,7 +247,7 @@ service:
       response: TokenResponse
 ```
 
-<Info>If your OAuth server is hosted at a different URL than your main API, you can use [multi-URL environments](/api-definitions/ferndef/api-yml/environments#multiple-urls-per-environment) to specify separate base URLs for authentication and API calls.</Info>
+<Info>If your OAuth server is hosted at a different URL than your main API, you can use [multi-URL environments](/learn/api-definitions/ferndef/api-yml/environments#multiple-urls-per-environment) to specify separate base URLs for authentication and API calls.</Info>
 
 With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure these settings, your
 client will automatically retrieve an access token and refresh it as needed.

fern/products/api-def/ferndef/endpoints.mdx

@@ -33,7 +33,7 @@ Each service defines:
 
 ### Section display name
 
-By default, section names in your API Reference come from service file names (e.g., `user.yml` becomes "User"). To override the display name of a section, [use the `section` property in your `docs.yml`](/docs/api-references/customize-api-reference-layout#renaming-sections).
+By default, section names in your API Reference come from service file names (e.g., `user.yml` becomes "User"). To override the display name of a section, [use the `section` property in your `docs.yml`](/learn/docs/api-references/customize-api-reference-layout#renaming-sections).
 
 ### SDK method names
 

fern/products/api-def/ferndef/examples.mdx

@@ -321,7 +321,7 @@ errors:
 
 ### Examples with headers
 
-When you have [global headers defined in your `api.yml`](/api-definitions/ferndef/api-yml/global-headers#global-headers), you must include them in your examples:
+When you have [global headers defined in your `api.yml`](/learn/api-definitions/ferndef/api-yml/global-headers#global-headers), you must include them in your examples:
 
 ```yml {15-16}
 service:

fern/products/api-def/ferndef/export-openapi.mdx

@@ -7,16 +7,24 @@ noindex: true
 <Markdown src="/products/api-def/snippets/ferndef-support.mdx" />
 
 
-To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/cli-api-reference/cli-reference/commands#fern-export). 
+To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/learn/cli-api-reference/cli-reference/commands#fern-export). 
 
-If you have multiple APIs defined in your `fern/apis/` folder, use `--api` to specify which API to export.
+The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec.
+
+<CodeBlock title="terminal">
+```bash
+# Write the exported spec as YAML
+fern export path/to/openapi.yml
 
-    <CodeBlock title="terminal">
-    ```bash
-    fern export path/to/openapi.yml
-    fern export path/to/openapi.json
+# ...or as JSON
+fern export path/to/openapi.json
+```
+</CodeBlock>
+
+If you have multiple APIs defined in your `fern/apis/` folder, use `--api` to specify which API to export.
 
-    # Specify API to export
-    fern export --api public-api path/to/openapi.yml
-    ```
-    </CodeBlock>
+<CodeBlock title="terminal">
+```bash
+fern export --api public-api path/to/openapi.yml
+```
+</CodeBlock>

fern/products/api-def/ferndef/webhooks.mdx

@@ -87,7 +87,7 @@ navigation:
   - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}
 ```
 
-For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-ref).
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/learn/docs/api-references/generate-webhook-ref).
 
 ## SDK signature verification
 

fern/products/api-def/grpc/overview.mdx

@@ -202,7 +202,7 @@ fern/
 ```
 </Step>
 <Step title="Create a `generators.yml` file">
-Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files. See [gRPC generators.yml reference](/api-definitions/grpc/generators-yml-reference) for complete configuration options.
+Create a `generators.yml` file in your fern directory and add a reference to your gRPC proto files. See [gRPC generators.yml reference](/learn/api-definitions/grpc/generators-yml-reference) for complete configuration options.
 
 ```yaml title="generators.yml"
 # Your API definition

fern/products/api-def/openapi/automation.mdx

@@ -20,7 +20,7 @@ Automatically pull your latest OpenAPI spec from a publicly available URL into y
     ```
   </Step>
   <Step title="Add the GitHub Action">
-    Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. 
+    Create `.github/workflows/sync-openapi.yml` in your repository. This action uses [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) to pull the latest version of your OpenAPI spec from the `origin` field in your `generators.yml` file. 
 
     ```yml title=".github/workflows/sync-openapi.yml"
     name: Sync OpenAPI Specs # can be customized

fern/products/api-def/openapi/extensions/examples.mdx

@@ -20,7 +20,7 @@ The `request` and `response` values use different shapes:
 - `response` requires a nested `body` key containing the response body properties.
 
 <Tip>
-  Examples must include any headers declared with the [`x-fern-global-headers` extension](/api-definitions/openapi/extensions/global-headers). Place them under `headers` alongside `path-parameters` and `request`.
+  Examples must include any headers declared with the [`x-fern-global-headers` extension](/learn/api-definitions/openapi/extensions/global-headers). Place them under `headers` alongside `path-parameters` and `request`.
 </Tip>
 
 An endpoint with path parameters:

fern/products/api-def/openapi/extensions/global-headers.mdx

@@ -30,7 +30,7 @@ x-fern-global-headers:
 ```
 
 <Note>
-  When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/api-definitions/openapi/extensions/request-response-examples).
+  When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples).
 </Note>
 
 ### Default values

fern/products/api-def/openapi/overview.mdx

@@ -106,8 +106,8 @@ components:
 
 Follow these best practices to ensure your OpenAPI specification generates high-quality SDKs and documentation:
 
-- **Organize with proper project structure.** Follow the instructions at [Project structure](/api-definitions/overview/project-structure) to clearly organize the directories that contain your definition and other related files. 
-- **Add `operationId` to endpoints.** Include a clear `operationId` for each endpoint to control the function names generated in your SDKs. (Or use [extensions to customize group and method names](/api-definitions/openapi/extensions/method-names).)
+- **Organize with proper project structure.** Follow the instructions at [Project structure](/learn/api-definitions/overview/project-structure) to clearly organize the directories that contain your definition and other related files. 
+- **Add `operationId` to endpoints.** Include a clear `operationId` for each endpoint to control the function names generated in your SDKs. (Or use [extensions to customize group and method names](/learn/api-definitions/openapi/extensions/method-names).)
 - **Reference schemas instead of inlining.** Define reusable schemas in the `components/schemas` section and reference them with `$ref`. This promotes consistency, reduces duplication, and makes maintenance easier.
   <Accordion title="Example of referencing schemas">
     ```yaml title="openapi.yml" {8, 14, 17-25}
@@ -137,7 +137,7 @@ Follow these best practices to ensure your OpenAPI specification generates high-
               enum: [available, pending, sold]
     ```
   </Accordion>
-- **Use overlays and Fern extensions for customization.** Customize your specification using Fern [extensions](/api-definitions/openapi/extensions/overview) housed in an [overlay file](/api-definitions/openapi/overlays). This lets you modify generation behavior without changing your core OpenAPI definition.  
+- **Use overlays and Fern extensions for customization.** Customize your specification using Fern [extensions](/learn/api-definitions/openapi/extensions/overview) housed in an [overlay file](/learn/api-definitions/openapi/overlays). This lets you modify generation behavior without changing your core OpenAPI definition.  
 
 Once your OpenAPI spec follows these practices, you're ready to set up your fern folder. 
 

fern/products/api-def/openapi/webhooks.mdx

@@ -124,7 +124,7 @@ navigation:
   - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name}
 ```
 
-For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-ref).
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/learn/docs/api-references/generate-webhook-ref).
 
 ## SDK signature verification
 

fern/products/api-def/pages/asyncapi-empty.mdx

@@ -4,4 +4,4 @@ description: This is an empty page used to redirect to the AsyncAPI Definition p
 ---
 
 
-<Warning>This page is empty. Please visit the [AsyncAPI Definition](/api-definitions/asyncapi/overview) page for more information.</Warning>
+<Warning>This page is empty. Please visit the [AsyncAPI Definition](/learn/api-definitions/asyncapi/overview) page for more information.</Warning>

fern/products/api-def/pages/ferndef-empty.mdx

@@ -4,4 +4,4 @@ description: This is an empty page used to redirect to the Fern Definition pages
 ---
 
 
-<Warning>This page is empty. Please visit the [Fern Definition](/api-definitions/ferndef/overview) page for more information.</Warning>
+<Warning>This page is empty. Please visit the [Fern Definition](/learn/api-definitions/ferndef/overview) page for more information.</Warning>

fern/products/api-def/pages/grpc-empty.mdx

@@ -4,4 +4,4 @@ description: This is an empty page used to redirect to the gRPC Definition pages
 ---
 
 
-<Warning>This page is empty. Please visit the [gRPC Definition](/api-definitions/grpc/overview) page for more information.</Warning>
+<Warning>This page is empty. Please visit the [gRPC Definition](/learn/api-definitions/grpc/overview) page for more information.</Warning>

fern/products/api-def/pages/openapi-empty.mdx

@@ -4,4 +4,4 @@ description: This is an empty page used to redirect to the OpenAPI Definition pa
 ---
 
 
-<Warning>This page is empty. Please visit the [OpenAPI Definition](/api-definitions/openapi/overview) page for more information.</Warning>
+<Warning>This page is empty. Please visit the [OpenAPI Definition](/learn/api-definitions/openapi/overview) page for more information.</Warning>

fern/products/api-def/pages/openrpc-empty.mdx

@@ -4,4 +4,4 @@ description: This is an empty page used to redirect to the OpenRPC Definition pa
 ---
 
 
-<Warning>This page is empty. Please visit the [OpenRPC Definition](/api-definitions/openrpc/overview) page for more information.</Warning>
+<Warning>This page is empty. Please visit the [OpenRPC Definition](/learn/api-definitions/openrpc/overview) page for more information.</Warning>

fern/products/api-def/pages/overrides.mdx

@@ -22,7 +22,7 @@ Overrides are available for OpenAPI, AsyncAPI, and OpenRPC specifications.
 <Steps>
 <Step title="Create an overrides file">
 
-[Create an `overrides.yml` file](/cli-api-reference/cli-reference/commands#fern-write-overrides) in the folder that contains your API definition:
+[Create an `overrides.yml` file](/learn/cli-api-reference/cli-reference/commands#fern-write-overrides) in the folder that contains your API definition:
 
 ```bash {6}
 fern/

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

@@ -7,7 +7,7 @@ description: Describes the Fern folder structure
 Configuring fern starts with the `fern` folder, which contains your API definitions,
 SDK generators, and your CLI version.
 
-Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and [each generated SDK in its own separate repository](/sdks/overview/project-structure).
+Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and [each generated SDK in its own separate repository](/learn/sdks/overview/project-structure).
 
 ## Directory structure
 
@@ -41,7 +41,7 @@ The `fern.config.json` file stores your organization name and the Fern CLI versi
 ```
 
 <Info> 
-  When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.
+  When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/learn/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.
 </Info>
 
 ### `generators.yml`
@@ -54,18 +54,18 @@ api:
     - openapi: ./openapi/openapi.yml
 ```
 
-For SDK generation, `generators.yml` is required. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/sdks/overview/project-structure#generatorsyml) for details.
+For SDK generation, `generators.yml` is required. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/learn/sdks/overview/project-structure#generatorsyml) for details.
 
 ### API definition file
 
-For [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.
+For [OpenAPI](/learn/api-definitions/openapi/overview), [AsyncAPI](/learn/api-definitions/asyncapi/overview), [OpenRPC](/learn/api-definitions/openrpc/overview), and [gRPC](/learn/api-definitions/grpc/overview), you'll have a single self-contained specification file.
 
 ## Where to store your API definition
 
 There are four common ways to manage your API definition:
 
 - **Commit directly into your Fern repository (recommended).** Check your API definition file into the same repository that contains your Fern configuration. This is the simplest approach if you don't maintain the definition elsewhere.
-- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification).
+- **Sync from a source code repository.** Store your API definition in the same repo as your API source code and sync updates into your Fern repository. You can automate this with the [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) CLI command or the [sync-openapi GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification).
 - **Host at a public URL.** Serve the definition from a publicly accessible endpoint and configure the [`origin`](/learn/sdks/reference/generators-yml#openapi) field in `generators.yml` so Fern can fetch it. This is useful when you want a single canonical definition that multiple consumers can reference.
 - **Reference from a remote git repository.** Point [`openapi`](/learn/sdks/reference/generators-yml#openapi), [`asyncapi`](/learn/sdks/reference/generators-yml#asyncapi), or proto [`root`](/learn/sdks/reference/generators-yml#root) to a file in an external git repository using the `git` sub-object. The CLI shallow-clones the repository at generation time, using your local git credential configuration. This is useful when spec files live in a private repo you don't want to copy.
 

fern/products/api-def/pages/what-is-an-api-definition.mdx

@@ -273,28 +273,28 @@ you can regenerate these artifacts to ensure they are always up-to-date.
   <Card
     title="SDKs"
     icon="brands github"
-    href="/sdks/overview/introduction"
+    href="/learn/sdks/overview/introduction"
   >
     Client libraries in multiple languages that automatically stay in sync with your API.
   </Card>
   <Card
     title="Documentation"
     icon="regular browser"
-    href="/docs/getting-started/overview"
+    href="/learn/docs/getting-started/overview"
   >
     Interactive API docs with code examples and live testing capabilities.
   </Card>
   <Card
     title="Postman Collection"
     icon={<img src="https://cdn.worldvectorlogo.com/logos/postman.svg" alt="Postman logo"/>}
-    href="/docs/integrations/postman"
+    href="/learn/docs/integrations/postman"
   >
     Ready-to-use collection with pre-filled example requests and responses.
   </Card>
   <Card
     title="Server Boilerplate"
     icon={<img src="https://cdn.worldvectorlogo.com/logos/fastapi-1.svg" alt="FastAPI logo" />}
-    href="/api-definitions/openapi/frameworks/fastapi"
+    href="/learn/api-definitions/openapi/frameworks/fastapi"
   >
     Pydantic models for FastAPI or controllers for your Spring Boot application.
   </Card>

fern/products/cli-api-reference/pages/commands.mdx

@@ -155,10 +155,14 @@ hideOnThisPage: true
 
     Use `fern export` to generate an OpenAPI spec for your API. This is useful when you've defined your API in a format other than OpenAPI (such as the [Fern Definition](/learn/api-definitions/ferndef/overview)) and need to export it for integration with other tools or services.
 
+    The path argument is the **output file** to write. Use a `.yml` or `.json` extension to choose the format of the generated spec.
 
     <CodeBlock title="terminal">
     ```bash
+    # Write the exported spec as YAML
     fern export [--api <api>] path/to/openapi.yml
+
+    # ...or as JSON
     fern export [--api <api>] path/to/openapi.json
     ```
     </CodeBlock>
@@ -167,10 +171,19 @@ hideOnThisPage: true
 
     Use `--api` to specify which API to export when you have multiple APIs defined in your `fern/apis/` folder.
 
-        <CodeBlock title="terminal">
+    <CodeBlock title="terminal">
     ```bash
     fern export --api public-api path/to/openapi.yml
-    fern export --api public-api path/to/openapi.json
+    ```
+    </CodeBlock>
+
+    ### indent
+
+    Use `--indent` to set the indentation size, in spaces, of the generated spec.
+
+    <CodeBlock title="terminal">
+    ```bash
+    fern export --indent 4 path/to/openapi.yml
     ```
     </CodeBlock>
 
@@ -1037,7 +1050,7 @@ hideOnThisPage: true
 
   <Accordion title="fern api update">
   Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and
-  updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/api-definitions/openapi/sync-your-open-api-specification).
+  updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/learn/api-definitions/openapi/sync-your-open-api-specification).
 
   <CodeBlock title="terminal">
     ```bash

fern/products/docs/pages/api-references/customize-api-ref.mdx

@@ -123,7 +123,7 @@ navigation:
 ```
 
 <Note>
-  You can alternatively customize tag display names directly in your spec (or overlays file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names).
+  You can alternatively customize tag display names directly in your spec (or overlays file) using the [`x-displayName` extension](/learn/api-definitions/openapi/extensions/tag-display-names).
 </Note>
 
 ### Flattening sections