From 77158d498b4a8c2fb28c3cde3fd0d65d00fc8147 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 25 Aug 2025 10:58:12 -0400 Subject: [PATCH 1/2] add new page --- .../pages/api-references/docs-generators.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 fern/products/docs/pages/api-references/docs-generators.mdx diff --git a/fern/products/docs/pages/api-references/docs-generators.mdx b/fern/products/docs/pages/api-references/docs-generators.mdx new file mode 100644 index 000000000..fdc8074f3 --- /dev/null +++ b/fern/products/docs/pages/api-references/docs-generators.mdx @@ -0,0 +1,17 @@ +--- +title: Configure generators.yml file +subtitle: +--- + +Most configuration for your documentation site happens in docs.yml, including API reference configuration. However, you can customize how certain aspects of your SDK appears in your reference docs directly in the generators.yml file, the file that configure how your API outputs to SDKs. You can have separate configurations for SDKs and for docs. + +SNK snippets are configured in generators.yml and then references in docs.yml. See PAGE. + +## APi reference and docs only +If you're only using Fern for API reference and docs, not SDKs, your generators.yml should look very straightforward: + +``` +api: + specs: + - openapi: ../openapi/openapi.json +``` \ No newline at end of file From bd213b0b397ae2bed1ca97daad74b381259ee24f Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 25 Aug 2025 12:23:01 -0400 Subject: [PATCH 2/2] add info about using generators.yml for docs --- .../pages/api-references/docs-generators.mdx | 17 ----------------- .../docs/pages/api-references/sdk-snippets.mdx | 4 ++++ .../pages/getting-started/project-structure.mdx | 16 +++++++++++++++- 3 files changed, 19 insertions(+), 18 deletions(-) delete mode 100644 fern/products/docs/pages/api-references/docs-generators.mdx diff --git a/fern/products/docs/pages/api-references/docs-generators.mdx b/fern/products/docs/pages/api-references/docs-generators.mdx deleted file mode 100644 index fdc8074f3..000000000 --- a/fern/products/docs/pages/api-references/docs-generators.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Configure generators.yml file -subtitle: ---- - -Most configuration for your documentation site happens in docs.yml, including API reference configuration. However, you can customize how certain aspects of your SDK appears in your reference docs directly in the generators.yml file, the file that configure how your API outputs to SDKs. You can have separate configurations for SDKs and for docs. - -SNK snippets are configured in generators.yml and then references in docs.yml. See PAGE. - -## APi reference and docs only -If you're only using Fern for API reference and docs, not SDKs, your generators.yml should look very straightforward: - -``` -api: - specs: - - openapi: ../openapi/openapi.json -``` \ No newline at end of file diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index f0aa18021..2631bd69c 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -77,6 +77,10 @@ navigation: ``` + + To display different package names for SDK users versus documentation users, [use overrides files](/api-definitions/overview/overrides#separate-overrides-for-sdks-and-docs). + + ### Trigger generation As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will now appear via a drop-down! diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index d4ca8d041..e7690fa7a 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -165,6 +165,18 @@ title: Fern's Documentation + + If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/github#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation. + + If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec: + + ```yaml title="generators.yml" + api: + specs: + - openapi: ../openapi/openapi.json + ``` + + ## `fern.config.json` @@ -177,4 +189,6 @@ The `fern.config.json` file specifies your organization name and the version of "version": "" } ``` - \ No newline at end of file + + +