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 5f5bee683..d9de4eef1 100644 --- a/fern/products/docs/pages/getting-started/how-it-works.mdx +++ b/fern/products/docs/pages/getting-started/how-it-works.mdx @@ -5,80 +5,86 @@ description: Learn how Fern transforms your API specifications and documentation Fern combines your API specifications, static Markdown files (like how-to guides and tutorials), media assets (images, videos, etc.), and custom settings defined in your `docs.yml` file to generate a beautiful, interactive hosted documentation site. + + + Content + + + 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. + + ``` + 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. @@ -115,29 +121,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. + + ``` + 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] + ``` +