Skip to content

Commit 732aaba

Browse files
devalogdevalog
committed
add another diagram, expand deployment section
1 parent 56b656b commit 732aaba

File tree

1 file changed

+100
-10
lines changed

1 file changed

+100
-10
lines changed

‎fern/products/docs/pages/getting-started/how-it-works.mdx‎

Lines changed: 100 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ description: Learn how Fern transforms your API specifications and documentation
55

66
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 documentation site hosted on Vercel.
77

8-
This process is built around two major workflows: editing and deploying your documentation.
8+
This process is built around two major workflows: **editing** and **deploying** your documentation.
99

10-
## Editing workflow
10+
## Content workflows
1111

1212
You can update your documentation in two ways:
1313

@@ -16,17 +16,40 @@ You can update your documentation in two ways:
1616

1717
After the update goes through your review process, an approver can merge it.
1818

19-
## Deployment workflow
19+
## Deployment workflows
2020

21-
When a pull request is merged into your docs repository:
21+
When a pull request is merged into your docs repository, an automated pipeline transforms your content into a live documentation site and syncs it with your API changes in three main stages:
2222

23-
1. **GitHub Action triggers and fetches API specs**: The merged PR triggers a Fern GitHub Action. The action retrieves your API specification from a separate repository using secure token authentication. The GitHub Action only has access to the specific docs repository from which it's running.
24-
2. **Fern CLI generates updated documentation**: [The Fern CLI](/learn/cli-api-reference/cli-reference/overview) runs `fern generate --docs` to merge API specs with your documentation and process it into a static site. During this process, Fern also indexes your content to enable search functionality across your documentation. The CLI uses a Fern token to authenticate and run the generation process.
25-
3. **Deploy to hosting platform**: The Fern CLI deploys your generated content to the Fern Docs Server, which is hosted on Vercel.
23+
<Steps>
2624

27-
This automated pipeline ensures your documentation stays synchronized with your API changes while maintaining a smooth developer workflow.
25+
### Trigger GitHub Action and fetch API specs
2826

29-
<Accordion title="Architecture diagram">
27+
The merged PR triggers a Fern GitHub Action. The action retrieves your API specification from a separate repository using secure token authentication. The GitHub Action only has access to the specific docs repository from which it's running.
28+
29+
### Generate and process content
30+
[The Fern CLI](/learn/cli-api-reference/cli-reference/overview) runs `fern generate --docs` to merge your API specs with documentation content. Behind the scenes, this process involves several key components:
31+
32+
- **Input processing**: The system combines your API specification files, `docs.yml` configuration file, `.mdx` files, and media content.
33+
- **Core infrastructure**: The generation process runs on Fern's AWS VPC infrastructure, where the Fern Docs microservice acts as the central orchestrator. This microservice coordinates content processing while connecting to a database for storing indexed content and S3 for asset storage.
34+
- **Content indexing**: During generation, Fern automatically indexes your documentation content to enable search functionality across your entire site. This indexing integrates with external services: [Algolia](/learn/docs/customization/search) for advanced search capabilities, UpStash for caching, PostHog for analytics, TurboPuffer for vector storage, and AI inference services (Bedrock, Claude) for intelligent content processing.
35+
36+
### Deploy to hosting platform
37+
38+
The processed content is deployed to Vercel as a documentation site with an embedded [API explorer](/learn/docs/api-references/api-explorer/overview) that allows users to test endpoints directly within the documentation.
39+
40+
Vercel Edge middleware handles the underlying routing, authentication, and performance optimization.
41+
42+
The deployed documentation site integrates with external systems like Cloudflare for CORS management and WorkOS for enterprise authentication.
43+
44+
45+
</Steps>
46+
47+
## Diagrams
48+
49+
<AccordionGroup>
50+
<Accordion title="Editing and deployment workflows">
51+
52+
This diagram shows how content flows from editing to deployment.
3053

3154
```mermaid
3255
flowchart TD
@@ -50,4 +73,71 @@ flowchart TD
5073
GA == ③ Triggers doc regeneration ==> CLI
5174
CLI == ④ Deploys updated docs ==> Server[Fern Docs Server]
5275
```
53-
</Accordion>
76+
</Accordion>
77+
78+
<Accordion title="System architecture">
79+
80+
This diagram shows the technical infrastructure that powers the documentation generation process.
81+
82+
```mermaid
83+
flowchart TD
84+
%% Input sources at the top
85+
subgraph inputs ["Input Sources"]
86+
API["API Specs"]
87+
DOCS["Docs.yml"]
88+
MDX["MDX files"]
89+
MEDIA["Media content"]
90+
end
91+
92+
%% Generation process
93+
GENERATE[["fern generate<br/>--docs"]]
94+
95+
%% AWS VPC section
96+
subgraph vpc ["Fern AWS VPC"]
97+
direction LR
98+
MICROSERVICE["Fern Docs<br/>microservice"]
99+
DATABASE[("Database")]
100+
S3[("S3")]
101+
end
102+
103+
%% External services
104+
SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]
105+
106+
%% Vercel hosting
107+
subgraph vercel ["Vercel"]
108+
direction LR
109+
STATIC["Static site"]
110+
EXPLORER["API explorer"]
111+
EDGE["Vercel Edge<br/>(Middleware)"]
112+
end
113+
114+
%% External connections as hexagons
115+
CLOUDFLARE{{"Cloudflare (CORS)"}}
116+
WORKOS{{"WorkOS"}}
117+
CUSTOMER{{"Customer API"}}
118+
119+
USER(("User"))
120+
121+
%% Vertical flow connections
122+
API --> GENERATE
123+
DOCS --> GENERATE
124+
MDX --> GENERATE
125+
MEDIA --> GENERATE
126+
127+
GENERATE --> MICROSERVICE
128+
MICROSERVICE --> SERVICES
129+
SERVICES <--> STATIC
130+
131+
STATIC --> CLOUDFLARE
132+
EXPLORER <--> CLOUDFLARE
133+
EDGE <--> WORKOS
134+
135+
CLOUDFLARE --> CUSTOMER
136+
EDGE <--> USER
137+
138+
%% Internal connections
139+
MICROSERVICE -.-> DATABASE
140+
MICROSERVICE -.-> S3
141+
```
142+
</Accordion>
143+
</AccordionGroup>

0 commit comments

Comments
 (0)