From 9083351af30e789e53f9e1deeca8ad2995d85503 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 4 Aug 2025 14:51:55 -0400 Subject: [PATCH 1/2] move project structure doc --- fern/products/docs/docs.yml | 4 +- .../pages/customization/project-structure.mdx | 166 ------------------ fern/products/home/pages/welcome.mdx | 10 +- 3 files changed, 7 insertions(+), 173 deletions(-) delete mode 100644 fern/products/docs/pages/customization/project-structure.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 59e8e42a1..835af3ef3 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -5,6 +5,8 @@ navigation: path: ./pages/getting-started/overview.mdx - page: Quickstart path: ./pages/getting-started/quickstart.mdx + - page: Project Structure + path: ./pages/getting-started/project-structure.mdx - link: Customer Showcase href: https://buildwithfern.com/customers - section: Writing Content @@ -87,8 +89,6 @@ navigation: contents: - page: What is docs.yml path: ./pages/customization/what-is-docs-yml.mdx - - page: Project Structure - path: ./pages/customization/project-structure.mdx - page: Frontmatter path: ./pages/customization/frontmatter.mdx - page: Search diff --git a/fern/products/docs/pages/customization/project-structure.mdx b/fern/products/docs/pages/customization/project-structure.mdx deleted file mode 100644 index b7241618b..000000000 --- a/fern/products/docs/pages/customization/project-structure.mdx +++ /dev/null @@ -1,166 +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 configuration file that defines the navigation, theme, and hosting details of your documentation. You can customize the appearance and behavior of your documentation by editing this file. - - -```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. - - ```bash - openapi - └─ openapi.yaml # OR openapi.json - ``` - - - 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. - - ```bash - definition - ├─ pets.yaml - ├─ owners.yaml - ├─ stores.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. For example: - - ```bash - apis - ├─ admin - │ └─ openapi.json - ├─ user - │ └─ openapi.yaml - ``` - - - To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). - - - - - -## `fern.config.json` - -The `fern.config.json` file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization's details. - - -```json -{ - "organization": "my-organization", - "version": "" -} -``` - diff --git a/fern/products/home/pages/welcome.mdx b/fern/products/home/pages/welcome.mdx index 10c7d7ab4..167d3acc9 100644 --- a/fern/products/home/pages/welcome.mdx +++ b/fern/products/home/pages/welcome.mdx @@ -148,6 +148,11 @@ import { FernFooter } from "../../../components/FernFooter"; Quickstart Arrow right light Arrow right light + + + Set up your project structure + Arrow right light + Arrow right light See all available components @@ -164,11 +169,6 @@ import { FernFooter } from "../../../components/FernFooter"; Arrow right light Arrow right light - - Setup your project structure - Arrow right light - Arrow right light - Control role-based access Arrow right light From 3b4f4726da68a6c9f059312cf64bf137272d25c6 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 4 Aug 2025 14:54:30 -0400 Subject: [PATCH 2/2] remove old redirect --- fern/docs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index d0944cc93..b7110be9c 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -325,9 +325,6 @@ redirects: - source: /learn/docs/getting-started/global-configuration destination: /learn/docs/customization/what-is-docs-yml permanent: true - - source: /learn/docs/getting-started/project-structure - destination: /learn/docs/customization/project-structure - permanent: true - source: /learn/docs/getting-started/development destination: /learn/docs/preview-publish/previewing-changes-locally permanent: true