From f5afa84a65c786e6e1efc1998bfb300270fef121 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sun, 12 Oct 2025 17:06:49 -0400 Subject: [PATCH 1/3] clean up formatting, add defaults and toc --- .../pages/customization/what-is-docs-yml.mdx | 165 +++++++++--------- .../reference/generators-yml-reference.mdx | 19 +- .../products/sdks/snippets/readme-options.mdx | 2 +- .../sdks/snippets/reviewers-params.mdx | 12 +- 4 files changed, 101 insertions(+), 97 deletions(-) diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx index a6e029ddf..2532f201d 100644 --- a/fern/products/docs/pages/customization/what-is-docs-yml.mdx +++ b/fern/products/docs/pages/customization/what-is-docs-yml.mdx @@ -2,6 +2,7 @@ title: "Docs.yml" subtitle: "Customize your documentation using the docs.yml file" description: "Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more." +max-toc-depth: 2 --- The `docs.yml` file is your primary tool for customizing your documentation site, including colors, typography, layout, analytics, and more. Start here for most customization needs before considering [custom CSS and JavaScript](/docs/customization/custom-css-js) for advanced use cases. @@ -49,64 +50,64 @@ navbar-links: href: "https://support.stripe.com" ``` - + A string that is used as the tab bar title. - - Learn more about the [`logo` configuration](/learn/docs/getting-started/global-configuration#logo-configuration). + + Set a custom logo for your site. Learn more about the [`logo` configuration](/learn/docs/getting-started/global-configuration#logo-configuration). - + Relative filepath to the favicon. - - Configure the `primaryAccent` and `background` colors. Learn more about the [`colors` configuration](/learn/docs/getting-started/global-configuration#colors-configuration). + + Configure the `primaryAccent` and `background` colors. Learn more about the [`colors` configuration](/learn/docs/getting-started/global-configuration#colors-configuration). - - An array of paths you want to configure to permanently redirect to another path. Learn more about the + + An array of paths you want to configure to permanently redirect to another path. Learn more about the [`redirects` configuration](/learn/docs/getting-started/global-configuration#redirects-configuration). - - Array of names and urls of links you want to include as a call to action. Learn more about the + + Array of names and urls of links you want to include as a call to action. Learn more about the [`navbar-links` configuration](/learn/docs/getting-started/global-configuration#navbar-links-configuration). - - Set a custom background image to be displayed behind every page. Learn more about the + + Set a custom background image to be displayed behind every page. Learn more about the [`background-image` configuration](/learn/docs/getting-started/global-configuration#background-image-configuration). - + Customize the fonts used in your documentation website. Learn more about the [`typography` configuration](/learn/docs/getting-started/global-configuration#typography-configuration). - - Customize the layout of your documentation website. Learn more about the + + Customize the layout of your documentation website. Learn more about the [`layout` configuration](/learn/docs/getting-started/global-configuration#layout-configuration). - - Customize the settings of your documentation website. Learn more about the + + Customize the settings of your documentation website. Learn more about the [`settings` configuration](/learn/docs/getting-started/global-configuration#settings-configuration). - - Creates a landing page for your documentation website. Learn more about the + + Creates a landing page for your documentation website. Learn more about the [`landing-page` configuration](/learn/docs/getting-started/global-configuration#landing-page-configuration). - - Sets the default language displayed by code snippets in the API Reference. - + + Sets the default language displayed by code snippets in the API Reference. + Options include: `typescript`, `python`, `java`, `go`, `ruby`, `csharp`, `curl` - - Configure SEO metadata for your documentation website. Learn more about the + + Configure SEO metadata for your documentation website. Learn more about the [`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration). @@ -120,19 +121,19 @@ instances: custom-domain: docs.plantstore.com ``` - + Configure one or more documentation websites. - + The URL where your Fern documentation is deployed. Must contain the suffix `docs.buildwithfern.com`. - - The custom domain where your documentation is hosted. Learn more about [setting up a custom domain](/learn/docs/preview-publish/setting-up-your-domain). + + The custom domain where your documentation is hosted. Learn more about [setting up a custom domain](/learn/docs/preview-publish/setting-up-your-domain). - + If specified, adds an "Edit this page" link to the bottom of each page that links to the given public GitHub repository. Learn more about the [`edit-this-page` configuration](#github-configuration). @@ -165,32 +166,32 @@ colors: dark: "#1f2937" ``` - + The primary brand color used for interactive elements like links, buttons, and highlighted text. Configure separate colors for light and dark modes to ensure proper contrast and visibility. - + The main background color for all documentation pages. Choose colors that provide good contrast with text and complement your brand colors. Dark mode colors should reduce eye strain. - + Used for dividing lines, borders around elements, and visual separators. Choose subtle colors that create clear boundaries without being too prominent. - + Background color for the navigation sidebar. When specified, includes a 1px border on the right side. If omitted, the sidebar uses a transparent background without a border. - + Background color for the top navigation header. When specified, includes a 1px solid border on the bottom. If omitted, the header uses a transparent background with a subtle gradient border. - + Background color for cards, code blocks, and other contained elements. Should be slightly different from the main background to create visual hierarchy while maintaining readability. @@ -204,15 +205,15 @@ logo: light: assets/images/logo-light.svg ``` - + The URL that users will be directed to when clicking the logo. Typically your company's homepage or app. - + Path to your dark mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: `assets/images/logo-dark.svg` - + Path to your light mode logo file, relative to the docs root. SVG format is recommended for optimal quality. Example: `assets/images/logo-light.svg` @@ -235,31 +236,31 @@ navbar-links: value: https://github.com/example-company/fern ``` - + One of `outlined`, `minimal`, `filled`, or `github`. This value controls the styling of the button. - + The URL once you click on the button. Example: https://buildwithfern.com/contact - + The URL to a GitHub repository. Similar to `href`, but specifically for GitHub repository links. This field is used when `type` is set to `github`. Example: https://github.com/example-company/fern - + Text inside the button. - + When `true`, the border radius of the button will be fully rounded. - + The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **left** of the text content. Pro and Brand Icons from Font Awesome are supported. - + The [Font Awesome icon](https://fontawesome.com/icons) to be used in the button. This icon will appear to the **right** of the text content. Pro and Brand Icons from Font Awesome are supported. By default, the `rightIcon` for a `filled` button is set to `arrow-right`. @@ -273,11 +274,11 @@ background-image: dark: ./path/to/bg-dark.svg ``` - + Relative filepath to the light-mode background image. - + Relative filepath to the dark-mode background image. @@ -306,17 +307,17 @@ typography: path: ./fonts/JetBrains-Mono-Regular.woff2 ``` - + The font used for all body text including paragraphs, lists, and general content. For optimal performance, use WOFF2 format. - + The font used for headings, titles, and other prominent text elements. Can be the same as your body font if you prefer a unified look. Supports multiple weights for different heading levels. - + The font used for code blocks and inline code. Monospace fonts are recommended for better code readability. Popular choices include JetBrains Mono, Fira Code, and Source Code Pro. @@ -365,24 +366,24 @@ typography: - + The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS. - + The path to your font file, relative to your docs folder. Use this when you have a single font file. For multiple font files (like separate files for bold, italic etc), use `paths` instead. - + The weight of the font. Can be a number (400, 700) or a range for variable fonts (400 700). Common values: 400 (normal), 700 (bold). - + The font style, either "normal" or "italic". Defaults to "normal" if not specified. - + A list of font files for particular weights. Each element in the list includes a `path`, `weight`, and `style` property. @@ -401,53 +402,51 @@ layout: hide-feedback: true ``` - + Sets the height of the header. Defaults to `4rem` (`64px`). Valid options are `{number}rem` or `{number}px`. - + Sets the maximum width of the docs layout, including the sidebar and content. Defaults to `88rem` (`1408px`). Valid options are `{number}rem`, `{number}px`, or `full`. - + Sets the maximum width of the Markdown article content. Defaults to `44rem` (`704px`). Valid options are `{number}rem` or `{number}px`. - + Sets the width of the sidebar in desktop mode. Defaults to `18rem` (`288px`). Valid options are `{number}rem` or `{number}px`. - + Sets the placement of the searchbar. Can be one of `header`, `sidebar` or `header-tabs` (places the searchbar in the header but on the tabs row). - Defaults to `sidebar`. This setting is ignored when `disable-header` is set to true. - + Set the placement of the tabs. Can be one of `header` or `sidebar`. - Defaults to `sidebar`. This setting is ignored when `disable-header` is set to true. - + Set the alignment of the Markdown content. Can be one of `center` or `left`. Defaults to `center`. - + If set to true, the header will not be rendered. Instead, the logo will be rendered as part of the sidebar, and a 1px border will separate the sidebar from the content. - + If set to true, the navigation links (previous, next) at the bottom of the page will not be rendered. This can be overridden on a per-page basis using the [frontmatter](/learn/docs/configuration/page-level-settings#navigation-links). - + If set to true, the feedback form will not be rendered. This can be overridden on a per-page basis using the [frontmatter](/learn/docs/configuration/page-level-settings#on-page-feedback). @@ -464,35 +463,35 @@ settings: use-javascript-as-typescript: false ``` - + The text to display in the searchbar. - + If set to true, the searchbar will be disabled. Use this if you want to use a custom search solution. - + If set to true, the code blocks will be displayed in dark mode, regardless of the selected theme. - + By default (`false`), search will display results for pages across all products and versions. If set to true, search will display results for pages within the current product and version. - + If set to true, the HTTP snippets will be displayed in the API Reference. - + If set to true, when a user navigates to a page that does not exist, they will be redirected to the home page. By default, a 404 page will be displayed. - + If set to true, the TypeScript snippets will be displayed as JavaScript snippets in the API Reference. @@ -536,15 +535,15 @@ instances: The GitHub repository must be **public** for the "Edit this page" feature to work correctly. - + The GitHub organization that owns the documentation repository. - + The name of the GitHub repository containing your fern folder. - + The branch of the repository you would like the GitHub editor to open a PR to. Default is `main`. @@ -557,7 +556,7 @@ landing-page: slug: /welcome ``` - + The name of the landing page. @@ -565,7 +564,7 @@ landing-page: Relative filepath to the desired landing page Markdown file. - + The slug of the landing page. Defaults to the page name. The slug can also be overridden in the frontmatter of the landing page Markdown file. @@ -593,19 +592,19 @@ analytics: api-key: "phc_xxxxxxxxxxxx" ``` - + Your Google Analytics 4 measurement ID. Must start with "G-". - + Your Google Tag Manager container ID. Must start with "GTM-". - + Configuration for PostHog Analytics integration. - + Your PostHog project API key. Defaults to the api-host of "https://us.i.posthog.com". diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index a86c580b2..fab05b269 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -1,6 +1,7 @@ --- title: generators.yml configuration schema description: Reference for the generators.yml configuration +max-toc-depth: 2 --- The `generators.yml` file configures how Fern generates SDKs from your API @@ -128,11 +129,11 @@ api: staging: "https://api.staging.com" ``` - + Authentication configuration for the API. - + Global headers to include with all API requests. You can specify headers as simple string values or as objects with additional configuration for code generation. @@ -163,7 +164,7 @@ api: - + Environment configurations for different deployment targets. @@ -204,19 +205,19 @@ api: Namespace for the specification. - + AsyncAPI-specific generation settings. - + What version of message naming to use for AsyncAPI messages. Options: `v1`, `v2`. - + Whether to use the titles of schemas within an AsyncAPI definition as the names of types within Fern. - + Preserves nullable schemas in API definition settings. When false, nullable schemas are treated as optional. @@ -369,7 +370,7 @@ groups: - name: "sdk-team" ``` - + Target audiences for this generator group (e.g., "external", "internal") @@ -583,7 +584,7 @@ PyPI password (alternative to token authentication) Additional PyPI-specific metadata for the package - + Package keywords for PyPI search and discovery diff --git a/fern/products/sdks/snippets/readme-options.mdx b/fern/products/sdks/snippets/readme-options.mdx index a66798a53..272ac6127 100644 --- a/fern/products/sdks/snippets/readme-options.mdx +++ b/fern/products/sdks/snippets/readme-options.mdx @@ -55,7 +55,7 @@ readme: Sections to disable in the README. Supported values: `"contributing"`. - + Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints. diff --git a/fern/products/sdks/snippets/reviewers-params.mdx b/fern/products/sdks/snippets/reviewers-params.mdx index 331fab394..51103215e 100644 --- a/fern/products/sdks/snippets/reviewers-params.mdx +++ b/fern/products/sdks/snippets/reviewers-params.mdx @@ -9,14 +9,18 @@ reviewers: - name: "jane-smith" ``` - + GitHub team names that should review generated code. - + GitHub users that should review generated code. - -Name of a GitHub team or a user. + +Name of a GitHub team. + + + +Name of a GitHub user. \ No newline at end of file From b806081ee043382ed0b0fe85a8fd199be7cfd013 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sun, 12 Oct 2025 17:18:56 -0400 Subject: [PATCH 2/3] more fixes --- .../reference/generators-yml-reference.mdx | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index fab05b269..219983e68 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -727,15 +727,18 @@ groups: ``` +Name of your repository in GitHub. +Name of your branch in GitHub. - + +Software license for the generated SDK. @@ -758,18 +761,21 @@ groups: ``` +Name of your repository in GitHub. +Name of your branch in GitHub. - + +Software license for the generated SDK. - + Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). @@ -789,15 +795,18 @@ groups: branch: "your-branch-name" # required for `mode: push` ``` +Name of your repository in GitHub. +Name of your branch in GitHub. - + +Software license for the generated SDK. @@ -839,7 +848,7 @@ URL pointing to comprehensive documentation, API reference, or getting started g Name of the individual developer, team, or organization that created and maintains the SDK. - + Software license for the generated SDK. From b822ef405ef7803b8cd19c505057380e613854f7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Sun, 12 Oct 2025 17:21:13 -0400 Subject: [PATCH 3/3] readme fix --- fern/products/sdks/snippets/readme-options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/snippets/readme-options.mdx b/fern/products/sdks/snippets/readme-options.mdx index 272ac6127..0f5c7793c 100644 --- a/fern/products/sdks/snippets/readme-options.mdx +++ b/fern/products/sdks/snippets/readme-options.mdx @@ -51,7 +51,7 @@ readme: Name of the API that appears in the README. Will appear as `Your Api Name SDK` or `Your Api Name API` throughout the README. Defaults to organization name if not set. - + Sections to disable in the README. Supported values: `"contributing"`.