Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 90 additions & 88 deletions fern/products/docs/pages/getting-started/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,72 +7,74 @@ 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.

<Accordion title="System architecture">
TEST some content added

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<br/>--docs"]]

%% AWS VPC section
subgraph vpc ["Fern AWS VPC"]
direction LR
MICROSERVICE["Fern Docs<br/>microservice"]
DATABASE[("Database")]
S3[("S3")]
end

%% External services
SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]

%% Vercel hosting
subgraph vercel ["Vercel"]
direction LR
STATIC["Static site"]
EXPLORER["API explorer"]
EDGE["Vercel Edge<br/>(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
```
<Accordion title="System architecture">
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<br/>--docs"]]

%% AWS VPC section
subgraph vpc ["Fern AWS VPC"]
direction LR
MICROSERVICE["Fern Docs<br/>microservice"]
DATABASE[("Database")]
S3[("S3")]
end

%% External services
SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]

%% Vercel hosting
subgraph vercel ["Vercel"]
direction LR
STATIC["Static site"]
EXPLORER["API explorer"]
EDGE["Vercel Edge<br/>(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
```
</Accordion>


## Content workflows

You can update your documentation in two ways:
Expand Down Expand Up @@ -111,29 +113,29 @@ The deployed documentation site integrates with external systems like Cloudflare
</Steps>

<Accordion title="Editing and deployment workflows">

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]
```
</Accordion>