You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
With Fern, you can build beautiful developer documentation that matches your brand. Fern supports writing pages (written in Markdown) and generating API Reference documentation (from an OpenAPI Specification).
9
7
10
8
In this guide, we'll show you how to get started with Fern in under 5 minutes.
11
9
12
10
<Stepstoc={true}>
13
11
### Initialize your `fern` folder
14
-
15
-
All the configurations for your docs live in the `fern` folder. Inside, you'll
16
-
find a `docs.yml` file that contains all the settings for your documentation.
12
+
13
+
All the configurations for your docs live in the `fern` folder. Inside, you'll
14
+
find a `docs.yml` file that contains all the settings for your documentation.
17
15
18
16
<AccordionGrouptoc={true}>
19
-
<Accordiontitle='Clone the starter repository'>
20
-
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).
17
+
<Accordiontitle="Clone the starter repository">
18
+
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
51
+
</CodeBlock>
52
+
</CodeBlocks>
53
+
</Warning>
55
54
56
-
```bash
57
-
fern generate --docs
58
-
```
59
-
</Accordion>
60
-
<Accordion title='Use the Fern CLI'>
61
-
If you prefer, you can use our CLI to create a new project. Install the CLI
62
-
by running
55
+
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
63
56
64
-
```bash
65
-
npm install -g fern-api
66
-
```
57
+
```bash
58
+
fern generate --docs
59
+
```
60
+
</Accordion>
67
61
68
-
Then run
62
+
<Accordion title="Use the Fern CLI">
63
+
If you prefer, you can use our CLI to create a new project. Install the CLI
64
+
by running
69
65
70
-
```bash
71
-
fern init --docs
72
-
```
66
+
```bash
67
+
npm install -g fern-api
68
+
```
73
69
74
-
You will see a new `fern` folder in your project with the following structure:
70
+
Then run
75
71
76
-
```bash
77
-
fern
78
-
├─ docs.yml
79
-
└─ fern.config.json
80
-
```
81
-
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
72
+
```bash
73
+
fern init --docs
74
+
```
82
75
83
-
```bash
84
-
fern generate --docs
85
-
```
86
-
</Accordion>
76
+
You will see a new `fern` folder in your project with the following structure:
77
+
78
+
```bash
79
+
fern
80
+
├─ docs.yml
81
+
└─ fern.config.json
82
+
```
83
+
84
+
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
85
+
86
+
```bash
87
+
fern generate --docs
88
+
```
89
+
</Accordion>
87
90
88
91
</AccordionGroup>
89
92
90
93
### Update your docs
91
94
92
95
<Note>
93
96
We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it
94
-
[here](https://buildwithfern.com/contact).
97
+
[here](https://buildwithfern.com/contact).
98
+
95
99
</Note>
96
100
97
101
<AccordionGroup toc={true}>
98
-
<Accordion title='Add content' >
99
-
Add content with MDX files.
100
-
101
-
```markdown
102
-
---
103
-
title: "Page Title"
104
-
description: "Subtitle (optional)"
105
-
---
106
-
107
-
Hello world!
108
-
```
102
+
<Accordion title="Add content">
103
+
Add content with MDX files.
104
+
105
+
```markdown
106
+
---
107
+
title: "Page Title"
108
+
description: "Subtitle (optional)"
109
+
---
110
+
111
+
Hello world!
112
+
```
109
113
110
-
<Note title="Supported Syntax">
114
+
<Note title="Supported Syntax">
111
115
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required.
112
-
</Note>
116
+
</Note>
113
117
114
-
In order for the Markdown page to show up, you'll need to reference them from your `docs.yml` file. You
115
-
can reference the Markdown page within a section or as a standalone page.
118
+
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.
119
+
120
+
```
121
+
navigation:
122
+
- page: Hello World
123
+
path: docs/pages/hello-world.mdx
124
+
- section: Overview
125
+
contents:
126
+
- page: QuickStart
127
+
path: docs/pages/hello-world.mdx
128
+
```
116
129
117
-
```yml
118
-
navigation:
119
-
- page: Hello World
120
-
path: docs/pages/hello-world.mdx
121
-
- section: Overview
122
-
contents:
123
-
- page: QuickStart
124
-
path: docs/pages/hello-world.mdx
125
-
```
126
130
</Accordion>
127
-
<Accordion title='Add an API Reference' >
131
+
132
+
<Accordiontitle="Add an API Reference">
128
133
Add an API Reference by adding an OpenAPI Specification to your project.
129
134
130
135
```bash
131
136
fern init --openapi /path/to/openapi.yml
132
137
```
133
138
134
-
This will create an `openapi.yml` file in your project. You can reference this file in your
135
-
`docs.yml`file by adding an api block.
139
+
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.
136
140
137
-
```yml
141
+
```
138
142
navigation:
139
143
- api: "API Reference"
140
144
```
141
145
</Accordion>
142
-
<Accordion title='Brand your docs'>
146
+
147
+
<Accordiontitle="Brand your docs">
143
148
All of the branding for your docs can be configured in the `docs.yml` file.
144
149
145
-
For example, to set the logos, colors, and fonts for your docs, you can
146
-
add the following to your `docs.yml` file:
150
+
For example, to set the logos, colors, and fonts for your docs, you can
151
+
add the following to your `docs.yml` file:
147
152
148
-
<CodeBlock title="docs.yml">
153
+
<CodeBlocktitle="docs.yml">
149
154
```yml
150
155
colors:
151
156
accent-primary:
@@ -160,45 +165,49 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
160
165
161
166
favicon: docs/assets/favicon.svg
162
167
```
163
-
</CodeBlock>
168
+
</CodeBlock>
164
169
165
170
</Accordion>
166
-
167
171
</AccordionGroup>
168
-
172
+
169
173
### Preview your docs
174
+
170
175
<AccordionGroup toc={true}>
171
-
<Accordion title='Preview your docs locally'>
172
-
You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally).
173
-
</Accordion>
174
-
<Accordion title='Preview your docs in a PR'>
175
-
`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).
176
-
</Accordion>
176
+
<Accordion title="Preview your docs locally">
177
+
You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally).
178
+
</Accordion>
179
+
180
+
<Accordion title="Preview your docs in a PR">
181
+
`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).
182
+
</Accordion>
183
+
177
184
</AccordionGroup>
178
-
185
+
179
186
### Publish to production
180
187
181
188
<AccordionGroup toc={true}>
182
-
<Accordion title='Publishing your docs'>
183
-
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)
184
-
</Accordion>
185
-
<Accordion title='Host on a custom domain'>
186
-
Fern supports hosting your docs website on a custom domain or on a
187
-
custom subpath (e.g. `https://example.com/docs`).
188
-
Please reach out to the Fern team at [email protected] to configure this.
189
-
</Accordion>
190
-
<Accordion title='Configure analytics'>
191
-
Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,
192
-
Google Tag Manager, etc.
193
-
Find out more on this [page](/learn/docs/integrations/overview).
194
-
</Accordion>
189
+
<Accordion title="Publishing your docs">
190
+
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)
191
+
</Accordion>
192
+
193
+
<Accordion title="Host on a custom domain">
194
+
Fern supports hosting your docs website on a custom domain or on a
Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,
201
+
Google Tag Manager, etc.
202
+
Find out more on this [page](/learn/docs/integrations/overview).
203
+
</Accordion>
195
204
196
205
</AccordionGroup>
197
-
198
206
</Steps>
199
207
208
+
200
209
[View examples of documentation websites](https://buildwithfern.com/customers) that have been published using Fern.
201
210
202
211
<Info>
203
212
Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members (add or remove), and Fern CLI version. You can also view page views and unique visitors to your site.
![fern-api[bot]](https://avatars.githubusercontent.com/in/244756?v=4&size=40){kind=avatar}
0 commit comments