diff --git a/fern/products/api-def/openapi/extensions/method-names.mdx b/fern/products/api-def/openapi/extensions/method-names.mdx index bc6696d78..245d4cfda 100644 --- a/fern/products/api-def/openapi/extensions/method-names.mdx +++ b/fern/products/api-def/openapi/extensions/method-names.mdx @@ -69,3 +69,29 @@ api: ``` `x-fern-sdk-group-name` and `x-fern-sdk-method-name` still take precedence, so you can group individual endpoints while ignoring tags elsewhere. Enabling `ignore-tags` avoids editing the spec or maintaining overlays when tags would otherwise produce awkward sub-clients, such as a `ConversationsV2Configuration` tag becoming a `conversations_v2_configuration` sub-client. + +### Namespacing schemas with `x-fern-sdk-namespace` + +`x-fern-sdk-namespace` namespaces the type IDs of every schema in a spec. When two specs both define a `Team` type, giving one spec `x-fern-sdk-namespace: entity_manager` makes Fern reference its `Team` as `entity_manager:Team` internally, so the two types no longer collide. + +`x-fern-sdk-group-name` and `x-fern-sdk-namespace` solve different problems. `x-fern-sdk-group-name` organizes endpoints into client sub-resources (`client.users.create()`). `x-fern-sdk-namespace` prevents schema name collisions when multiple API specs define types with the same name. + +The extension applies to a whole spec, not to individual endpoints. Set it at the root of the OpenAPI file: + +```yaml title="entity-manager.yaml" {2} +openapi: 3.1.0 +x-fern-sdk-namespace: entity_manager +info: + title: Entity Manager +``` + +Equivalently, set [`namespace`](/learn/sdks/reference/generators-yml#namespace) on the spec entry in `generators.yml`. This value takes precedence over the extension when both are present: + +```yaml title="generators.yml" {4, 6} +api: + specs: + - openapi: ./openapi/entity-manager.yaml + namespace: entity_manager + - openapi: ./openapi/task-manager.yaml + namespace: task_manager +``` diff --git a/fern/products/api-def/openapi/extensions/overview.md b/fern/products/api-def/openapi/extensions/overview.md index 18722d0bc..9ca38f76f 100644 --- a/fern/products/api-def/openapi/extensions/overview.md +++ b/fern/products/api-def/openapi/extensions/overview.md @@ -35,6 +35,7 @@ The table below shows all available extensions and links to detailed documentati | [`x-fern-pagination`](./pagination) | Configure auto-pagination for list endpoints | | [`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-sdk-namespace`](./method-names#namespacing-schemas-with-x-fern-sdk-namespace) | Namespace schemas to prevent name collisions when combining multiple API specs | | [`x-fern-sdk-variables`](./sdk-variables) | Set common path parameters across all requests | | [`x-fern-parameter-name`](./parameter-names) | Customize parameter variable names | | [`x-fern-property-name`](./property-names) | Customize object property variable names | diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index d58f9b40a..01d924d9c 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -670,6 +670,14 @@ layout: Customize the visual style of specific UI elements across your documentation site. + + The `theme` key styles UI elements (sidebar, body, tabs). It does not control the light/dark color mode. Fern follows the visitor's operating system preference, and no `docs.yml` key forces the site into dark or light mode for all visitors. The closest options are: + + - [`settings.dark-mode-code: true`](#settings-configuration) renders code blocks in dark mode regardless of the visitor's color mode. + - [``](/learn/docs/customization/header-and-footer) in a custom header lets visitors toggle between modes. + - [`colors`](#colors-configuration) with both `light` and `dark` values for `accent-primary` and other color keys keeps your brand consistent in both modes. + + ```yaml docs.yml theme: sidebar: minimal diff --git a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx index 61ba4d5f2..454830801 100644 --- a/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx +++ b/fern/products/docs/pages/preview-publish/preview-changes-locally.mdx @@ -122,6 +122,12 @@ If your docs use [role-based access control](/learn/docs/authentication/features Preview links persist indefinitely — Fern doesn't auto-expire them. Any organization member can use [`fern docs preview list`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-preview-list) to see active previews and [`fern docs preview delete`](/learn/cli-api-reference/cli-reference/docs-commands#fern-docs-preview-delete) to remove them when they're no longer needed. To clean up previews automatically when PRs merge, set up a [GitHub Actions workflow](#clean-up-preview-links-when-prs-merge). +Previews created without `--id` have no identifier to pass to `--id`. To delete one, pass its full preview URL instead: + +```bash +fern docs preview delete https://fern-preview-c973a36e-337b-44f5-ab83-aab.docs.buildwithfern.com +``` + ### Automate with GitHub Actions You can use a GitHub Actions workflow to automatically generate a preview URL when a pull request is opened. By passing `--id` with the branch name, every push to the same PR updates the same preview URL instead of creating a new one. The workflow posts a comment on the PR with the preview link and direct links to every page changed in the PR, so reviewers can jump straight to affected pages. @@ -351,3 +357,9 @@ jobs: fern docs preview delete --id "${{ github.head_ref }}" || echo "Preview deletion returned non-zero — it may already be gone" ``` + +## Deleting published production docs + +There is no single command to delete a production site. Published docs stay live as long as the site is configured in `docs.yml`. To take a site offline entirely, contact [support@buildwithfern.com](mailto:support@buildwithfern.com). + +To remove specific pages, delete them from the navigation in `docs.yml` (or mark them [`hidden: true`](/learn/docs/configuration/navigation#hiding-content) to keep them reachable by direct URL only) and republish with `fern generate --docs`. Pages removed from navigation are no longer reachable, so add a [redirect](/learn/docs/seo/redirects) from the old path to avoid broken links.