diff --git a/fern/docs.yml b/fern/docs.yml index 48bfbc35d..cca4ee73a 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -7,91 +7,75 @@ instances: owner: fern-api repo: docs branch: main - title: Fern Documentation - ai-search: location: - docs - metadata: og:image: https://fern-docs.s3.us-east-2.amazonaws.com/fern-docs-og_image-compressed.png twitter:image: https://fern-docs.s3.us-east-2.amazonaws.com/fern-docs-og_image-compressed.png canonical-host: buildwithfern.com - products: - display-name: Home path: ./products/home/home.yml image: ./images/product-switcher/product-switcher-home-light.png - slug: - subtitle: Products that elevate your developer experience - + slug: null + subtitle: Products that elevate your developer experience - display-name: SDKs path: ./products/sdks/sdks.yml icon: fa-brands fa-codepen image: ./images/product-switcher/product-switcher-sdks-light.png slug: sdks subtitle: Generate client libraries in multiple languages - - display-name: Docs path: ./products/docs/docs.yml icon: fa-regular fa-browser image: ./images/product-switcher/product-switcher-docs-light.png slug: docs subtitle: Generate beautiful, interactive documentation websites - - display-name: Ask Fern path: ./products/ask-fern/ask-fern.yml - icon: fa-regular fa-magnifying-glass + icon: fa-regular fa-magnifying-glass image: ./images/product-switcher/product-switcher-askfern-light.png slug: ask-fern subtitle: Let users find answers in your documentation instantly - - display-name: CLI Reference subtitle: Manage and configure your Fern projects path: ./products/cli-api-reference/cli-api-reference.yml icon: fa-regular fa-terminal image: ./images/product-switcher/product-switcher-cliapi-light.png slug: cli-api-reference - - display-name: API Definitions path: ./products/api-def/api-def.yml icon: fa-regular fa-book image: ./images/product-switcher/openapi-definition-light.png slug: api-definitions - - display-name: OpenAPI path: ./products/api-def/openapi-def.yml icon: fa-regular fa-book image: ./images/product-switcher/openapi-definition-light.png slug: openapi-definition - - display-name: AsyncAPI path: ./products/api-def/asyncapi-def.yml icon: fa-regular fa-bolt image: ./images/product-switcher/asyncapi-light.png slug: asyncapi-definition - - display-name: OpenRPC path: ./products/api-def/openrpc-def.yml icon: fa-regular fa-code image: ./images/product-switcher/openrpc-light.png slug: openrpc-definition - - display-name: gRPC path: ./products/api-def/grpc-def.yml icon: fa-regular fa-plug image: ./images/product-switcher/grpc-light.png slug: grpc-definition - - display-name: Fern Definition path: ./products/api-def/ferndef-def.yml icon: fa-regular fa-seedling image: ./images/product-switcher/fern-definition-light.png slug: fern-definition - css: ./assets/styles.css - navbar-links: - type: minimal text: Slack community @@ -102,7 +86,6 @@ navbar-links: - type: filled text: Book a demo url: https://buildwithfern.com/contact - typography: bodyFont: name: GT-Planar @@ -117,81 +100,56 @@ typography: name: GT-Planar-Bold path: ./assets/GT-Planar-Bold.woff2 weight: 600 700 - logo: - href: / + href: / light: ./images/logo-primary.svg dark: ./images/logo-white.svg height: 20 colors: accent-primary: - dark: "#70E155" - light: "#008700" + dark: '#70E155' + light: '#008700' background: - dark: "#111113" - light: "#FFFFFF" - border: - dark: "#393A40" - light: "#E0E1E6" + dark: '#111113' + light: '#FFFFFF' + border: + dark: '#393A40' + light: '#E0E1E6' header-background: - dark: "#111113" - light: "#FFFFFF" + dark: '#111113' + light: '#FFFFFF' card-background: - dark: "#222325" - light: "#FFFFFF" + dark: '#222325' + light: '#FFFFFF' favicon: ./images/favicon_32.png - layout: page-width: 1504px header-height: 75px searchbar-placement: header tabs-placement: header - settings: http-snippets: - curl - js: - path: ./footer-dist/output.js strategy: beforeInteractive - path: ./rive-animation.js strategy: afterInteractive - analytics: - # posthog: - # api-key: ${POSTHOG_API_KEY} gtm: container-id: GTM-55W3VNDW - experimental: mdx-components: - ./components - -# Redirects for new docs structure migration redirects: - - # ============================================================================ - # GENERAL REDIRECTS - # ============================================================================ - - # Main learn page redirect - source: /learn destination: /learn/home - source: /learn/welcome destination: /learn/home - - - # ============================================================================ - # SDK REDIRECTS - # ============================================================================ - - # SDK Features/Capabilities redirects - source: /learn/sdks/features destination: /learn/sdks/overview/capabilities - source: /learn/sdks/features/:slug* destination: /learn/sdks/overview/capabilities - - # SDK Deep Dives - specific overrides for newer destinations - source: /learn/sdks/capabilities/method-names destination: /learn/sdks/deep-dives/customize-method-names - source: /learn/sdks/guides/preview-your-sdk-locally @@ -202,8 +160,6 @@ redirects: destination: /learn/sdks/deep-dives/idempotency - source: /learn/sdks/capabilities/integration-tests destination: /learn/sdks/deep-dives/testing - - # SDK Package Managers redirects - source: /learn/sdks/guides/publish-to-package-managers/npm-type-script destination: /learn/sdks/generators/typescript/publishing - source: /learn/sdks/guides/publish-to-package-managers/pypi @@ -220,8 +176,6 @@ redirects: destination: /learn/sdks/generators/php/publishing - source: /learn/sdks/package-managers/:slug* destination: /learn/sdks/generators/typescript/publishing - - # SDK Introduction redirects - source: /learn/sdks/introduction/configuration destination: /learn/sdks/overview/introduction - source: /learn/sdks/introduction/language-support @@ -240,18 +194,16 @@ redirects: destination: /learn/sdks/generators/typescript/changelog/:slug* - source: /learn/sdks/introduction/changelog/python/:slug* destination: /learn/sdks/generators/python/changelog/:slug* - - source: /learn/sdks/introduction/changelog/csharp/:slug* + - source: /learn/sdks/introduction/changelog/csharp/:slug* destination: /learn/sdks/generators/csharp/changelog/:slug* - source: /learn/sdks/introduction/changelog/go/:slug* destination: /learn/sdks/generators/go/changelog/:slug* - - source: /learn/sdks/introduction/changelog/java/:slug* + - source: /learn/sdks/introduction/changelog/java/:slug* destination: /learn/sdks/generators/java/changelog/:slug* - source: /learn/sdks/introduction/changelog/ruby/:slug* destination: /learn/sdks/generators/ruby/changelog/:slug* - - source: /learn/sdks/introduction/changelog/php/:slug* + - source: /learn/sdks/introduction/changelog/php/:slug* destination: /learn/sdks/generators/php/changelog/:slug* - - # SDK Capabilities - remaining general redirects (after specific overrides above) - source: /learn/sdks/capabilities/idiomatic-method-names destination: /learn/sdks/deep-dives/customize-method-names - source: /learn/sdks/capabilities/o-auth-token-refresh @@ -264,12 +216,8 @@ redirects: destination: /learn/sdks/overview/custom-code - source: /learn/sdks/capabilities/merging-multiple-apis destination: /learn/sdks/capabilities/merging-apis - - # General SDK capabilities pattern (will catch any not specifically overridden above) - source: /learn/sdks/capabilities/:slug* destination: /learn/sdks/overview/introduction - - # SDK Guides - specific cases first, then general pattern - source: /learn/sdks/guides/generate-your-first-sdk destination: /learn/sdks/overview/quickstart - source: /learn/sdks/guides/publish-a-public-facing-sdk @@ -278,22 +226,12 @@ redirects: destination: /learn/sdks/generators/:slug* - source: /learn/sdks/reference/generators-yml-reference destination: /learn/sdks/reference/generators-yml - - # General SDK guides pattern - source: /learn/sdks/getting-started/:slug* destination: /learn/sdks/overview/introduction - source: /learn/sdks/guides/:slug* destination: /learn/sdks/overview/introduction - - # ============================================================================ - # DOCS REDIRECTS - # ============================================================================ - - # Building Your Docs redirects (older naming) - source: /learn/docs/building-your-docs/:slug* destination: /learn/docs/building-and-customizing-your-docs/:slug* - - # Getting Started page redirects - specific cases first - source: /learn/docs/getting-started/customer-showcase destination: https://buildwithfern.com/customers - source: /learn/docs/getting-started/global-configuration @@ -302,8 +240,6 @@ redirects: destination: /learn/docs/preview-publish/previewing-changes-locally - source: /learn/docs/getting-started/publish-your-docs destination: /learn/docs/preview-publish/publishing-your-docs - - # Building and Customizing Your Docs redirects - specific cases first - source: /learn/docs/building-and-customizing-your-docs/navigation destination: /learn/docs/configuration/navigation - source: /learn/docs/navigation/overview @@ -338,7 +274,6 @@ redirects: destination: /learn/docs/authentication/rbac - source: /learn/docs/building-and-customizing-your-docs/search destination: /learn/docs/customization/search - - source: /learn/docs/content/write-markdown destination: /learn/docs/writing-content/markdown - source: /learn/docs/content/components/:slug* @@ -359,10 +294,8 @@ redirects: destination: /learn/docs/writing-content/fern-editor - source: /learn/docs/writing-content/code-blocks destination: /learn/docs/writing-content/components/code-blocks - - source: /learn/docs/getting-started/changelog/:slug* destination: /learn/docs/changelog/:slug* - - source: /learn/docs/api-references/api-explorer destination: /learn/docs/api-references/api-explorer/overview - source: /learn/docs/api-references/api-playground/:slug* @@ -373,12 +306,6 @@ redirects: destination: /learn/docs/user-feedback - source: /learn/docs/customization/what-is-docs-yml destination: /learn/docs/configuration/what-is-docs-yml - - # ============================================================================ - # CLI & API REFERENCE REDIRECTS - # ============================================================================ - - # CLI & API Reference specific redirects first - source: /learn/cli-api/cli-reference/get-started-with-fern-cli destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-api/cli-reference/cli-overview @@ -395,7 +322,6 @@ redirects: destination: /learn/cli-api-reference/cli-reference/commands - source: /learn/cli-reference/options destination: /learn/cli-api-reference/cli-reference/options - # CLI patterns - source: /learn/cli-api/cli-reference/:slug* destination: /learn/cli-reference/:slug* - source: /learn/cli-api/cli/:slug* @@ -404,12 +330,6 @@ redirects: destination: /learn/cli-reference/:slug* - source: /learn/cli-reference/changelog/:slug* destination: /learn/cli-api-reference/cli-reference/changelog/:slug* - - # ============================================================================ - # API DEFINITION REDIRECTS - # ============================================================================ - - # # API Definition OpenAPI specific redirects first - source: /learn/api-definition/openapi/endpoints/:slug* destination: /learn/api-definitions/openapi/endpoints/:slug* - source: /learn/api-definition/openapi/extensions/:slug* @@ -430,26 +350,16 @@ redirects: destination: /learn/api-definitions/overview/overrides - source: /learn/api-definitions/openapi/automatic-updates destination: /learn/api-definitions/openapi/sync-your-open-api-specification - - # API Definition Fern specific redirects first - source: /learn/api-definition/fern/endpoints/:slug* destination: /learn/api-definitions/ferndef/endpoints/:slug* - source: /learn/api-definition/fern/api-yml/:slug* destination: /learn/api-definitions/ferndef/api-yml/:slug* - - source: /learn/api-definition/fern/:slug* + - source: /learn/api-definition/fern/:slug* destination: /learn/api-definitions/ferndef/:slug* - - # # API Definition Introduction redirects - source: /learn/api-definition/introduction/what-is-an-api-definition destination: /learn/api-definitions/overview/what-is-an-api-definition - source: /learn/api-definition/introduction/what-is-the-fern-folder destination: /learn/api-definitions/overview/project-structure - - # ============================================================================ - # ASK FERN (AI SEARCH) REDIRECTS - # ============================================================================ - - # Ask Fern specific redirects first - source: /learn/ai-search/customer-showcase destination: https://buildwithfern.com/customers - source: /learn/ai-search/overview @@ -468,8 +378,6 @@ redirects: destination: /learn/ask-fern/configuration/custom-prompts - source: /learn/ask-fern/configuration/locations-and-datasources destination: /learn/ask-fern/configuration/setup - - # General Ask Fern patterns - source: /learn/ai-search/getting-started/:slug* destination: /learn/ask-fern/:slug* - source: /learn/ai-search/features/:slug* @@ -478,20 +386,10 @@ redirects: destination: /learn/ask-fern/:slug* - source: /learn/ask-fern/api-reference/queries/:slug* destination: /learn/ask-fern/api-reference/overview - - # ============================================================================ - # API REFERENCE REDIRECTS (Fern Public API) - # ============================================================================ - - # Fern Public API Reference redirects - now redirect to CLI Reference - source: /learn/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-api-reference/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview - - # ============================================================================ - # API REFERENCE REDIRECTS - # ============================================================================ - source: /learn/openapi-definition/empty-page destination: /learn/api-definitions/openapi/overview - source: /learn/asyncapi-definition/empty-page @@ -512,8 +410,6 @@ redirects: destination: /learn/api-definitions/grpc/:slug* - source: /learn/fern-definition/:slug* destination: /learn/api-definitions/ferndef/:slug* - - # Redirect old others.mdx extension pages to overview pages - source: /learn/api-definitions/openapi/extensions/others destination: /learn/api-definitions/openapi/extensions/overview - source: /learn/api-definitions/asyncapi/extensions/others @@ -522,12 +418,6 @@ redirects: destination: /learn/api-definitions/openrpc/extensions/overview - source: /learn/api-definitions/grpc/extensions/:slug* destination: /learn/api-definitions/overview/overrides#definition-specific-extensions - - # ============================================================================ - # ADDITIONAL /LEARN/* REDIRECTS FROM CRAWLED URLS FROM GOOGLE SEARCH CONSOLE - # ============================================================================ - - # SDK specific redirects - source: /learn/sdks/generators/java/publishing-to-maven-central destination: /learn/sdks/generators/java/publishing - source: /learn/sdks/generators/php/publishing-to-packagist @@ -546,8 +436,6 @@ redirects: destination: /learn/sdks/overview/project-structure - source: /learn/sdks/alternatives/speakeasy destination: /learn/sdks/overview/introduction - - # Docs specific redirects - source: /learn/docs/customization/project-structure destination: /learn/docs/getting-started/project-structure - source: /learn/docs/alternatives/mintlify @@ -572,8 +460,6 @@ redirects: destination: /learn/docs/writing-content/components/tabs - source: /learn/docs/components/CustomCard destination: /learn/docs/writing-content/custom-react-components - - # API Definition redirects - source: /learn/api-definition/openapi/webhooks destination: /learn/api-definitions/openapi/endpoints/webhooks - source: /learn/api-definition/introduction @@ -604,16 +490,12 @@ redirects: destination: /learn/api-definitions/openrpc/extensions/retry-behavior - source: /learn/overview/define-your-api/openapi/extensions destination: /learn/api-definitions/openapi/extensions/overview - - # CLI & API Reference redirects - source: /learn/cli-api/cli-reference destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-api/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/api/api-reference/:slug* destination: /learn/cli-api-reference/cli-reference/overview - - # Ask Fern redirects - source: /learn/ask-fern/features/custom-fa-qs destination: /learn/ask-fern/features/citations - source: /learn/ai-search/getting-started/ai-search-customer-showcase @@ -622,13 +504,10 @@ redirects: destination: /learn/ask-fern/api-reference/overview - source: /learn/ask-fern/api-reference/queries/:slug* destination: /learn/ask-fern/api-reference/overview - - # V2 legacy paths (old version of docs) - source: /learn/v2/:slug* destination: /learn/:slug* - - # Misc legacy learn paths - source: /learn/snippets/:slug* destination: /learn/cli-api-reference/cli-reference/overview - source: /learn/cli-reference/path/to/file.pdf destination: /learn/cli-api-reference/cli-reference/overview +navigation: [] diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx deleted file mode 100644 index 33ccd22d7..000000000 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Project Structure -description: An overview of the file and folder structure of a Fern Docs project ---- - -This page provides an overview of the file and folder structure of a Fern Docs project. The following structure is recommended for organizing your documentation content, but is customizable to fit your needs. - -## Top-level folders - - -```bash - fern - ├─ pages - ├─ assets - ├─ docs.yml - ├─ openapi - └─ fern.config.json -``` - - -A Fern Docs project has the following top-level folders: - -- `pages`: Contains the Markdown (MDX) files that make up your documentation. -- `assets`: Contains any images or videos used in your documentation. -- `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation. -- `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation). -- `fern.config.json`: The configuration file specifying your organization name and CLI version. - -## Pages folder - -The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation. - - -```bash - pages - ├─ introduction - │ ├─ quickstart.mdx - │ ├─ project-structure.mdx - │ └─ showcase.mdx - ├─ building-your-docs - │ ├─ navigation - │ ├─ sections.mdx - │ ├─ tabs.mdx - │ └─ versions.mdx - └─ └─ configuration.mdx - -``` - - -The `pages` folder is organized into subfolders based on the sections of your documentation. Each subfolder contains the MDX files for the pages in that section. - -## Assets folder - -The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths. - - -```bash - assets - ├─ favicon.ico - ├─ product-screenshot.svg - ├─ demo-video.mp4 - ├─ logo-dark-mode.png - └─ logo-light-mode.png -``` - - -## `docs.yml` - -The `docs.yml` file is the heart of your Fern documentation site. This configuration file controls your documentation's navigation structure, visual design, site functionality, and hosting settings. - -For complete configuration options, see the [docs.yml reference](/docs/configuration/what-is-docs-yml). - - -```yml -instances: - - url: fern.docs.buildwithfern.com/learn - custom-domain: buildwithfern.com/learn - -navigation: - - section: Introduction - layout: - - page: QuickStart - path: pages/introduction/quickstart.mdx - - page: Project Structure - path: pages/introduction/project-structure.mdx - - page: Showcase - path: pages/introduction/showcase.mdx - -navbar-links: - - type: filled - text: Book a demo - url: https://buildwithfern.com/contact - -logo: - light: ./images/logo-primary.svg - dark: ./images/logo-white.svg - -colors: - accent-primary: - dark: "#ADFF8C" - light: "#209d63" - -favicon: ./images/favicon.ico - -title: Fern's Documentation -``` - - -## API Definitions - - - - The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder. - - In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. - - - ```bash - openapi - ├─ openapi.yaml # OR openapi.json - └─ overrides.yaml - ``` - - - To see this in practice, check out [Fluidstack's Fern configuration](https://github.com/fluidstackio/fern-config/tree/main/fern/openapi). - - - - The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder. - - In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. - - - ```bash - definition - ├─ pets.yaml - ├─ owners.yaml - ├─ stores.yaml - ├─ overrides.yaml - └─ api.yaml - ``` - - - To see this in practice, check out [Cartesia's Fern configuration](https://github.com/cartesia-ai/docs/tree/main/fern/apis/version-2025-04-16/definition). - - - - If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition and [(optional) overrides file](/api-definitions/overview/overrides). - - For example: - - ```bash - apis - ├─ admin - │ ├─ openapi.json - │ └─ overrides.yaml - ├─ user - │ ├─ openapi.yaml - │ └─ overrides.yaml - ``` - - - To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). - - - - - - 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/project-structure#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` - - - -