diff --git a/fern/products/docs/pages/getting-started/how-it-works.mdx b/fern/products/docs/pages/getting-started/how-it-works.mdx index a0de085b..4e188635 100644 --- a/fern/products/docs/pages/getting-started/how-it-works.mdx +++ b/fern/products/docs/pages/getting-started/how-it-works.mdx @@ -8,77 +8,77 @@ Fern combines your API specifications, static Markdown files (like how-to guides This process is built around two major workflows: **editing** and **deploying** your documentation. - -This diagram shows the technical infrastructure that powers the documentation generation process. - -```mermaid -flowchart TD - %% Input sources at the top - subgraph inputs ["Input Sources"] - API["API Specs"] - DOCS["Docs.yml"] - MDX["MDX files"] - MEDIA["Media content"] - end - - %% Generation process - GENERATE[["fern generate
--docs"]] - - %% AWS VPC section - subgraph vpc ["Fern AWS VPC"] - direction LR - MICROSERVICE["Fern Docs
microservice"] - DATABASE[("Database")] - S3[("S3")] - end - - %% External services - SERVICES["External Services
(UpStash, Algolia, PostHog,
TurboPuffer, AI Inference)"] - - %% Vercel hosting - subgraph vercel ["Vercel"] - direction LR - STATIC["Static site"] - EXPLORER["API explorer"] - EDGE["Vercel Edge
(Middleware)"] - end - - %% External connections as hexagons - CLOUDFLARE{{"Cloudflare (CORS)"}} - WORKOS{{"WorkOS"}} - CUSTOMER{{"Customer API"}} - - USER(("User")) - - %% Vertical flow connections - API --> GENERATE - DOCS --> GENERATE - MDX --> GENERATE - MEDIA --> GENERATE - - GENERATE --> MICROSERVICE - MICROSERVICE --> SERVICES - SERVICES <--> STATIC - - STATIC --> CLOUDFLARE - EXPLORER <--> CLOUDFLARE - EDGE <--> WORKOS - - CLOUDFLARE --> CUSTOMER - EDGE <--> USER - - %% Internal connections - MICROSERVICE -.-> DATABASE - MICROSERVICE -.-> S3 -``` + This diagram shows the technical infrastructure that powers the documentation generation process. + + ```mermaid + flowchart TD + %% Input sources at the top + subgraph inputs ["Input Sources"] + API["API Specs"] + DOCS["Docs.yml"] + MDX["MDX files"] + MEDIA["Media content"] + end + + %% Generation process + GENERATE[["fern generate
--docs"]] + + %% AWS VPC section + subgraph vpc ["Fern AWS VPC"] + direction LR + MICROSERVICE["Fern Docs
microservice"] + DATABASE[("Database")] + S3[("S3")] + end + + %% External services + SERVICES["External Services
(UpStash, Algolia, PostHog,
TurboPuffer, AI Inference)"] + + %% Vercel hosting + subgraph vercel ["Vercel"] + direction LR + STATIC["Static site"] + EXPLORER["API explorer"] + EDGE["Vercel Edge
(Middleware)"] + end + + %% External connections as hexagons + CLOUDFLARE{{"Cloudflare (CORS)"}} + WORKOS{{"WorkOS"}} + CUSTOMER{{"Customer API"}} + + USER(("User")) + + %% Vertical flow connections + API --> GENERATE + DOCS --> GENERATE + MDX --> GENERATE + MEDIA --> GENERATE + + GENERATE --> MICROSERVICE + MICROSERVICE --> SERVICES + SERVICES <--> STATIC + + STATIC --> CLOUDFLARE + EXPLORER <--> CLOUDFLARE + EDGE <--> WORKOS + + CLOUDFLARE --> CUSTOMER + EDGE <--> USER + + %% Internal connections + MICROSERVICE -.-> DATABASE + MICROSERVICE -.-> S3 + ``` + ## Content workflows You can update your documentation in two ways: -- **Direct editing**: Open a pull request directly in the [GitHub repository that contains your docs](/learn/docs/getting-started/project-structure) (including your `docs.yml` configuration and Markdown files). -- **Fern Editor**: Use the [Fern Editor](/learn/docs/writing-content/fern-editor) to modify your docs without touching code. The Fern GitHub App fetches the current state from your docs repository and passes it to the Fern Editor. When you submit changes, the Fern GitHub App automatically opens a pull request for review. +- **Direct editing**: Open a pull request directly in the [GitHub repository that contains your docs](/learn/docs/getting-started/project-structure) (including your `docs.yml` configuration and Markdown files). +- **Fern Editor**: Use the [Fern Editor](/learn/docs/writing-content/fern-editor) to modify your docs without touching code. The Fern GitHub App fetches the current state from your docs repository and passes it to the Fern Editor. When you submit changes, the Fern GitHub App automatically opens a pull request for review. After the update goes through your review process, an approver can merge it. @@ -111,29 +111,29 @@ The deployed documentation site integrates with external systems like Cloudflare - -This diagram shows how content flows from editing to deployment. - -```mermaid -flowchart TD - FE[Fern Editor] - U[User] - DR[Docs Repo] - CLI[Fern CLI] - Decision{Make a PR or edit in Fern Editor?} - Spec((API Spec Repo)) - GA[GitHub Actions] - - U ==> Decision - Decision == Make edit ==> FE - Decision == Open and Merge PR ==> DR - - FE <== Fetches state and opens PR ==> DR - DR == ① Merged PR triggers deployment flow ==> GA - - Spec <-. ② Fetches and merges API spec .-> GA - - GA == ③ Triggers doc regeneration ==> CLI - CLI == ④ Deploys updated docs ==> Server[Fern Docs Server] -``` + This diagram shows how content flows from editing to deployment. + + ```mermaid + flowchart TD + FE[Fern Editor] + U[User] + DR[Docs Repo] + CLI[Fern CLI] + Decision{Make a PR or edit in Fern Editor?} + Spec((API Spec Repo)) + GA[GitHub Actions] + + U ==> Decision + Decision == Make edit ==> FE + Decision == Open and Merge PR ==> DR + + FE <== Fetches state and opens PR ==> DR + DR == ① Merged PR triggers deployment flow ==> GA + + Spec <-. ② Fetches and merges API spec .-> GA + + GA == ③ Triggers doc regeneration ==> CLI + CLI == ④ Deploys updated docs ==> Server[Fern Docs Server] + ``` + diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index f1c0bd1e..60d01cf1 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -166,11 +166,11 @@ 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/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference 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/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" + ```yaml api: specs: - openapi: ../openapi/openapi.json @@ -189,6 +189,4 @@ The `fern.config.json` file specifies your organization name and the version of "version": "" } ``` - - - + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index a53c14f7..9fcbad2a 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -11,18 +11,19 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes. ### Initialize your `fern` folder - - All the configurations for your docs live in the `fern` folder. Inside, you'll - find a `docs.yml` file that contains all the settings for your documentation. + + All the configurations for your docs live in the `fern` folder. Inside, you'll + find a `docs.yml` file that contains all the settings for your documentation. - + Get started by cloning the [starter template](https://github.com/fern-api/docs-starter). ```bash title="SSH" git clone git@github.com:fern-api/docs-starter.git ``` + ```bash title="HTTPS" git clone https://github.com/fern-api/docs-starter.git ``` @@ -31,121 +32,124 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes. Next, please update the template settings to use your organization. - Please edit the details `fern.config.json` and `docs.yml` with your organization - name. + Please edit the details `fern.config.json` and `docs.yml` with your organization name. - ```json {2} - { - "organization": "{{YOUR_ORGANIZATION}}", - "version": "0.x.x" - } - ``` + ```json {2} + { + "organization": "{{YOUR_ORGANIZATION}}", + "version": "0.x.x" + } + ``` + - ```yml {2} - instances: - - url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com - ``` + ```yml {2} + instances: + - url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com + ``` + + Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation: ```bash fern generate --docs ``` - - If you prefer, you can use our CLI to create a new project. Install the CLI - by running - ```bash - npm install -g fern-api - ``` + + If you prefer, you can use our CLI to create a new project. Install the CLI by running - Then run + ```bash + npm install -g fern-api + ``` - ```bash - fern init --docs - ``` + Then run - You will see a new `fern` folder in your project with the following structure: + ```bash + fern init --docs + ``` - ```bash - fern - ├─ docs.yml - └─ fern.config.json - ``` - Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation: + You will see a new `fern` folder in your project with the following structure: - ```bash - fern generate --docs - ``` - + ```bash + fern + ├─ docs.yml + └─ fern.config.json + ``` + Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation: + + ```bash + fern generate --docs + ``` + + ### Update your docs We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it - [here](https://buildwithfern.com/contact). + [here](https://buildwithfern.com/contact). + - - Add content with MDX files. - - ```markdown - --- - title: "Page Title" - description: "Subtitle (optional)" - --- - - Hello world! - ``` + + Add content with MDX files. + + ```markdown + --- + title: "Page Title" + description: "Subtitle (optional)" + --- - + Hello world! + ``` + + Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. - + - In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You - can reference the Markdown page within a section or as a standalone page. + In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You can reference the Markdown page within a section or as a standalone page. - ```yml - navigation: - - page: Hello World - path: docs/pages/hello-world.mdx - - section: Overview - contents: - - page: QuickStart - path: docs/pages/hello-world.mdx - ``` - - - Add an API Reference by adding an OpenAPI Specification to your project. + ```yml + navigation: + - page: Hello World + path: docs/pages/hello-world.mdx + - section: Overview + contents: + - page: QuickStart + path: docs/pages/hello-world.mdx + ``` + - ```bash - fern init --openapi /path/to/openapi.yml - ``` + + Add an API Reference by adding an OpenAPI Specification to your project. - This will create an `openapi.yml` file in your project. You can reference this file in your - `docs.yml` file by adding an api block. + ```bash + fern init --openapi /path/to/openapi.yml + ``` - ```yml - navigation: - - api: "API Reference" - ``` - - - All of the branding for your docs can be configured in the `docs.yml` file. + This will create an `openapi.yml` file in your project. You can reference this file in your `docs.yml` file by adding an api block. - For example, to set the logos, colors, and fonts for your docs, you can - add the following to your `docs.yml` file: + ```yml + navigation: + - api: "API Reference" + ``` + - + + All of the branding for your docs can be configured in the `docs.yml` file. + + For example, to set the logos, colors, and fonts for your docs, you can add the following to your `docs.yml` file: + + ```yml colors: accent-primary: @@ -160,44 +164,48 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes. favicon: docs/assets/favicon.svg ``` - - - + + - + ### Preview your docs + - - You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally). - - - `PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. Learn more [here](/docs/preview-publish/previewing-changes-in-a-pr). - + + You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally). + + + + `PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. Learn more [here](/docs/preview-publish/previewing-changes-in-a-pr). + + - + ### Publish to production - - When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI. + + When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI. - [Read more.](/learn/docs/preview-publish/publishing-your-docs) - - - Fern supports hosting your docs website on a custom domain or on a - custom subpath (e.g. `https://example.com/docs`). + [Read more.](/learn/docs/preview-publish/publishing-your-docs) + - Please reach out to the Fern team at support@buildwithfern.com to configure this. - - - Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom, - Google Tag Manager, etc. - Find out more on this [page](/learn/docs/integrations/overview). - + + Fern supports hosting your docs website on a custom domain or on a + custom subpath (e.g. `https://example.com/docs`). - + Please reach out to the Fern team at [support@buildwithfern.com](mailto:support@buildwithfern.com) to configure this. + + + Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom, + Google Tag Manager, etc. + Find out more on this [page](/learn/docs/integrations/overview). + + + -[View examples of documentation websites](https://buildwithfern.com/customers) that have been published using Fern. \ No newline at end of file + +[View examples of documentation websites](https://buildwithfern.com/customers) that have been published using Fern.