Skip to content

Commit e2f2363

Browse files
fern-api[bot]fern-api[bot]
authored
Fern Editor: Update
1 parent 4b8c4d3 commit e2f2363

File tree

1 file changed

+96
-90
lines changed

1 file changed

+96
-90
lines changed

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

Lines changed: 96 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -5,80 +5,86 @@ 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 hosted documentation site.
77

8+
9+
<Callout intent="info">
10+
Content
11+
</Callout>
12+
13+
814
This process is built around two major workflows: **editing** and **deploying** your documentation.
915

1016
<Accordion title="System architecture">
11-
12-
This diagram shows the technical infrastructure that powers the documentation generation process.
13-
14-
```mermaid
15-
flowchart TD
16-
%% Input sources at the top
17-
subgraph inputs ["Input Sources"]
18-
API["API Specs"]
19-
DOCS["Docs.yml"]
20-
MDX["MDX files"]
21-
MEDIA["Media content"]
22-
end
23-
24-
%% Generation process
25-
GENERATE[["fern generate<br/>--docs"]]
26-
27-
%% AWS VPC section
28-
subgraph vpc ["Fern AWS VPC"]
29-
direction LR
30-
MICROSERVICE["Fern Docs<br/>microservice"]
31-
DATABASE[("Database")]
32-
S3[("S3")]
33-
end
34-
35-
%% External services
36-
SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]
37-
38-
%% Vercel hosting
39-
subgraph vercel ["Vercel"]
40-
direction LR
41-
STATIC["Static site"]
42-
EXPLORER["API explorer"]
43-
EDGE["Vercel Edge<br/>(Middleware)"]
44-
end
45-
46-
%% External connections as hexagons
47-
CLOUDFLARE{{"Cloudflare (CORS)"}}
48-
WORKOS{{"WorkOS"}}
49-
CUSTOMER{{"Customer API"}}
50-
51-
USER(("User"))
52-
53-
%% Vertical flow connections
54-
API --> GENERATE
55-
DOCS --> GENERATE
56-
MDX --> GENERATE
57-
MEDIA --> GENERATE
58-
59-
GENERATE --> MICROSERVICE
60-
MICROSERVICE --> SERVICES
61-
SERVICES <--> STATIC
62-
63-
STATIC --> CLOUDFLARE
64-
EXPLORER <--> CLOUDFLARE
65-
EDGE <--> WORKOS
66-
67-
CLOUDFLARE --> CUSTOMER
68-
EDGE <--> USER
69-
70-
%% Internal connections
71-
MICROSERVICE -.-> DATABASE
72-
MICROSERVICE -.-> S3
73-
```
17+
This diagram shows the technical infrastructure that powers the documentation generation process.
18+
19+
```
20+
flowchart TD
21+
%% Input sources at the top
22+
subgraph inputs ["Input Sources"]
23+
API["API Specs"]
24+
DOCS["Docs.yml"]
25+
MDX["MDX files"]
26+
MEDIA["Media content"]
27+
end
28+
29+
%% Generation process
30+
GENERATE[["fern generate<br/>--docs"]]
31+
32+
%% AWS VPC section
33+
subgraph vpc ["Fern AWS VPC"]
34+
direction LR
35+
MICROSERVICE["Fern Docs<br/>microservice"]
36+
DATABASE[("Database")]
37+
S3[("S3")]
38+
end
39+
40+
%% External services
41+
SERVICES["External Services<br/>(UpStash, Algolia, PostHog,<br/>TurboPuffer, AI Inference)"]
42+
43+
%% Vercel hosting
44+
subgraph vercel ["Vercel"]
45+
direction LR
46+
STATIC["Static site"]
47+
EXPLORER["API explorer"]
48+
EDGE["Vercel Edge<br/>(Middleware)"]
49+
end
50+
51+
%% External connections as hexagons
52+
CLOUDFLARE{{"Cloudflare (CORS)"}}
53+
WORKOS{{"WorkOS"}}
54+
CUSTOMER{{"Customer API"}}
55+
56+
USER(("User"))
57+
58+
%% Vertical flow connections
59+
API --> GENERATE
60+
DOCS --> GENERATE
61+
MDX --> GENERATE
62+
MEDIA --> GENERATE
63+
64+
GENERATE --> MICROSERVICE
65+
MICROSERVICE --> SERVICES
66+
SERVICES <--> STATIC
67+
68+
STATIC --> CLOUDFLARE
69+
EXPLORER <--> CLOUDFLARE
70+
EDGE <--> WORKOS
71+
72+
CLOUDFLARE --> CUSTOMER
73+
EDGE <--> USER
74+
75+
%% Internal connections
76+
MICROSERVICE -.-> DATABASE
77+
MICROSERVICE -.-> S3
78+
```
7479
</Accordion>
7580

81+
7682
## Content workflows
7783

7884
You can update your documentation in two ways:
7985

80-
- **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).
81-
- **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.
86+
- **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).
87+
- **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.
8288

8389
After the update goes through your review process, an approver can merge it.
8490

@@ -115,29 +121,29 @@ The deployed documentation site integrates with external systems like Cloudflare
115121
</Steps>
116122

117123
<Accordion title="Editing and deployment workflows">
118-
119-
This diagram shows how content flows from editing to deployment.
120-
121-
```mermaid
122-
flowchart TD
123-
FE[Fern Editor]
124-
U[User]
125-
DR[Docs Repo]
126-
CLI[Fern CLI]
127-
Decision{Make a PR or edit in Fern Editor?}
128-
Spec((API Spec Repo))
129-
GA[GitHub Actions]
130-
131-
U ==> Decision
132-
Decision == Make edit ==> FE
133-
Decision == Open and Merge PR ==> DR
134-
135-
FE <== Fetches state and opens PR ==> DR
136-
DR == ① Merged PR triggers deployment flow ==> GA
137-
138-
Spec <-. ② Fetches and merges API spec .-> GA
139-
140-
GA == ③ Triggers doc regeneration ==> CLI
141-
CLI == ④ Deploys updated docs ==> Server[Fern Docs Server]
142-
```
124+
This diagram shows how content flows from editing to deployment.
125+
126+
```
127+
flowchart TD
128+
FE[Fern Editor]
129+
U[User]
130+
DR[Docs Repo]
131+
CLI[Fern CLI]
132+
Decision{Make a PR or edit in Fern Editor?}
133+
Spec((API Spec Repo))
134+
GA[GitHub Actions]
135+
136+
U ==> Decision
137+
Decision == Make edit ==> FE
138+
Decision == Open and Merge PR ==> DR
139+
140+
FE <== Fetches state and opens PR ==> DR
141+
DR == ① Merged PR triggers deployment flow ==> GA
142+
143+
Spec <-. ② Fetches and merges API spec .-> GA
144+
145+
GA == ③ Triggers doc regeneration ==> CLI
146+
CLI == ④ Deploys updated docs ==> Server[Fern Docs Server]
147+
```
143148
</Accordion>
149+

0 commit comments

Comments
 (0)