Skip to content

Commit 787f02a

Browse files
devin-ai-integration[bot]devalog
devin-ai-integration[bot]
and
devalog
authored
Update file structures to use Files component with highlights and comments (#2042)
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: Devin Logan <devinannlogan@gmail.com>
1 parent 167b738 commit 787f02a

File tree

10 files changed

+308
-250
lines changed

10 files changed

+308
-250
lines changed

‎fern/products/api-def/ferndef-pages/overview.mdx‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,18 +21,20 @@ fern init
2121

2222
This will create the following folder structure in your project:
2323

24-
```bash
25-
fern/
26-
├─ fern.config.json # root-level configuration
27-
├─ generators.yml # generators you're using
28-
└─ definition/
29-
├─ api.yml # API-level configuration
30-
└─ imdb.yml # endpoints, types, and errors
31-
```
24+
<Files>
25+
<Folder name="fern" defaultOpen>
26+
<File name="fern.config.json" comment="Root-level configuration" />
27+
<File name="generators.yml" comment="Generators you're using" />
28+
<Folder name="definition" defaultOpen>
29+
<File name="api.yml" comment="API-level configuration" />
30+
<File name="imdb.yml" comment="Endpoints, types, and errors" />
31+
</Folder>
32+
</Folder>
33+
</Files>
3234

3335
## Definition file
3436

35-
Each **Fern Definition** file may define:
37+
Each Fern Definition file may define:
3638

3739
- **[Custom types](/learn/api-definition/fern/types)**. Use **custom types** to build your data model.
3840
- **[Endpoints](/learn/api-definition/fern/endpoints)**. A **service** is a set of related REST endpoints.

‎fern/products/api-def/openapi-pages/overview.mdx‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -155,12 +155,15 @@ fern init --openapi https://host/path/to/openapi
155155
```
156156
</CodeGroup>
157157

158-
This will initialize a directory like the following
159-
```
160-
fern/
161-
├─ fern.config.json
162-
├─ generators.yml
163-
└─ openapi/
164-
├─ openapi.yml
165-
```
158+
This will initialize a directory like the following:
159+
160+
<Files>
161+
<Folder name="fern" defaultOpen>
162+
<File name="fern.config.json" />
163+
<File name="generators.yml" />
164+
<Folder name="openapi" defaultOpen>
165+
<File name="openapi.yml" comment="Your spec"/>
166+
</Folder>
167+
</Folder>
168+
</Files>
166169

‎fern/products/api-def/pages/project-structure.mdx‎

Lines changed: 67 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,15 @@ Fern recommends a multi-repository structure with your fern folder in a source r
1212

1313
When you run `fern init` (for the Fern Definition) or `fern init --spec-type path/to/spec` (for other specs), your fern folder is initialized with the following files:
1414

15-
```bash
16-
fern/
17-
├─ fern.config.json # Root-level config for entire Fern project
18-
├─ generators.yml # Declares APIs and configures SDK generation
19-
└─ spec-folder/ # definition, openapi, asyncapi, etc.
20-
└─ spec-file.yml # API definition file
21-
```
15+
<Files>
16+
<Folder name="fern" defaultOpen>
17+
<File name="fern.config.json" comment="Root-level config for entire Fern project" />
18+
<File name="generators.yml" comment="Declares APIs and configures SDK generation" />
19+
<Folder name="spec-folder" defaultOpen comment="definition, openapi, asyncapi, etc.">
20+
<File name="spec-file.yml" comment="API definition file" />
21+
</Folder>
22+
</Folder>
23+
</Files>
2224

2325
## Core configuration files
2426

@@ -61,17 +63,21 @@ Use this approach when each API should generate its own independent set of SDKs.
6163

6264
Place each API into a separate subfolder of `fern/apis/`:
6365

64-
```bash
65-
fern/
66-
├─ fern.config.json
67-
└─ apis/
68-
├─ user-api/
69-
│ ├─ generators.yml # Configures user-api SDKs
70-
│ └─ openapi.yml
71-
└─ payments-api/
72-
├─ generators.yml # Configures payments-api SDKs
73-
└─ openapi.yml
74-
```
66+
<Files>
67+
<Folder name="fern" defaultOpen>
68+
<File name="fern.config.json" />
69+
<Folder name="apis" defaultOpen>
70+
<Folder name="user-api" defaultOpen highlighted>
71+
<File name="generators.yml" comment="Configures user-api SDKs" />
72+
<File name="openapi.yml" />
73+
</Folder>
74+
<Folder name="payments-api" highlighted defaultOpen>
75+
<File name="generators.yml" comment="Configures payments-api SDKs" />
76+
<File name="openapi.yml" />
77+
</Folder>
78+
</Folder>
79+
</Folder>
80+
</Files>
7581

7682
Each API must have its own `generators.yml` file:
7783

@@ -97,17 +103,20 @@ groups:
97103
This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). You can merge up to five APIs into a single SDK on the Pro plan, and unlimited APIs on the Enterprise plan. To get started, reach out to support@buildwithfern.com.
98104
</Warning>
99105

100-
Use this approach to merge multiple APIs into a single set of SDKs.
101-
102-
```bash
103-
fern/
104-
├─ fern.config.json
105-
├─ generators.yml # Single config for combined SDKs
106-
├─ user-api/
107-
│ └─ openapi.yml
108-
└─ payments-api/
109-
└─ openapi.yml
110-
```
106+
Use this approach to merge multiple APIs into a single set of SDKs. Place each API into a separate subfolder of `fern/apis/`:
107+
108+
<Files>
109+
<Folder name="fern" defaultOpen>
110+
<File name="fern.config.json" />
111+
<File name="generators.yml" highlighted comment="Single config for combined SDKs" />
112+
<Folder name="user-api" defaultOpen>
113+
<File name="openapi.yml" />
114+
</Folder>
115+
<Folder name="payments-api" defaultOpen>
116+
<File name="openapi.yml" />
117+
</Folder>
118+
</Folder>
119+
</Files>
111120

112121
List all APIs in a single `generators.yml`:
113122

@@ -136,17 +145,21 @@ When supporting multiple API versions, you can publish them as separate packages
136145

137146
Use this approach when you want each API version to be independently installable (e.g., `@company/sdk-v1`, `@company/sdk-v2`). This use case follows the [Separate SDKs for each API](#separate-sdks-for-each-api) pattern.
138147

139-
```bash
140-
fern/
141-
├─ fern.config.json
142-
└─ apis/
143-
├─ v1/
144-
│ ├─ generators.yml # Configures v1 SDKs
145-
│ └─ openapi.yml
146-
└─ v2/
147-
├─ generators.yml # Configures v2 SDKs
148-
└─ openapi.yml
149-
```
148+
<Files>
149+
<Folder name="fern" defaultOpen>
150+
<File name="fern.config.json" />
151+
<Folder name="apis" defaultOpen>
152+
<Folder name="v1" defaultOpen>
153+
<File name="generators.yml" highlighted comment="Configures v1 SDKs" />
154+
<File name="openapi.yml" />
155+
</Folder>
156+
<Folder name="v2" defaultOpen>
157+
<File name="generators.yml" highlighted comment="Configures v2 SDKs" />
158+
<File name="openapi.yml" />
159+
</Folder>
160+
</Folder>
161+
</Folder>
162+
</Files>
150163

151164
Each API must have its own `generators.yml` file:
152165

@@ -166,16 +179,20 @@ groups:
166179

167180
If you prefer a single package with multiple API versions, use namespaces. This generates clients like `client.v1` and `client.v2` within the same package. Note that this increases package size as all versions are bundled together.
168181

169-
```bash
170-
fern/
171-
├─ fern.config.json
172-
├─ generators.yml # Single config for all versions
173-
└─ apis/
174-
├─ v1/
175-
│ └─ openapi.yml
176-
└─ v2/
177-
└─ openapi.yml
178-
```
182+
<Files>
183+
<Folder name="fern" defaultOpen>
184+
<File name="fern.config.json" />
185+
<File name="generators.yml" highlighted comment="Single config for all versions" />
186+
<Folder name="apis" defaultOpen>
187+
<Folder name="v1">
188+
<File name="openapi.yml" />
189+
</Folder>
190+
<Folder name="v2">
191+
<File name="openapi.yml" />
192+
</Folder>
193+
</Folder>
194+
</Folder>
195+
</Files>
179196

180197
List all API versions in a single `generators.yml` with namespaces:
181198

‎fern/products/docs/pages/api-references/generate-webhook-ref.mdx‎

Lines changed: 45 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -40,15 +40,19 @@ Your webhooks should be defined in a dedicated folder within your Fern project:
4040
4141
<Tabs>
4242
<Tab title="OpenAPI">
43-
```bash
44-
fern/
45-
└── apis/
46-
├── webhooks-v1/ # Webhook definition
47-
│ ├── openapi/
48-
│ │ └── openapi.yml
49-
│ └── generators.yml
50-
└── api-v1/ # Regular API endpoints
51-
```
43+
<Files>
44+
<Folder name="fern" defaultOpen>
45+
<Folder name="apis" defaultOpen>
46+
<Folder name="webhooks-v1" defaultOpen highlighted comment="Webhook definition">
47+
<Folder name="openapi" defaultOpen>
48+
<File name="openapi.yml" />
49+
</Folder>
50+
<File name="generators.yml" />
51+
</Folder>
52+
<Folder name="api-v1" comment="Regular API endpoints" />
53+
</Folder>
54+
</Folder>
55+
</Files>
5256
5357
If you're using OpenAPI, your `generators.yml` file should point to your OpenAPI specification:
5458

@@ -60,16 +64,20 @@ api:
6064
You can read more about how to define webhooks in your OpenAPI specification [here](/learn/api-definitions/openapi/endpoints/webhooks).
6165
</Tab>
6266
<Tab title="Fern Definition">
63-
```bash
64-
fern/
65-
└── apis/
66-
├── webhooks-v1/ # Webhook definition
67-
│ ├── definition/
68-
│ │ ├── api.yml
69-
│ │ └── webhooks.yml
70-
│ └── generators.yml
71-
└── api-v1/ # Regular API endpoints
72-
```
67+
<Files>
68+
<Folder name="fern" defaultOpen>
69+
<Folder name="apis" defaultOpen>
70+
<Folder name="webhooks-v1" defaultOpen highlighted comment="Webhook definition">
71+
<Folder name="definition" defaultOpen>
72+
<File name="api.yml" />
73+
<File name="webhooks.yml" />
74+
</Folder>
75+
<File name="generators.yml" />
76+
</Folder>
77+
<Folder name="api-v1" comment="Regular API endpoints" />
78+
</Folder>
79+
</Folder>
80+
</Files>
7381

7482
You can read more about how to define webhooks in your Fern Definition [here](/learn/api-definition/fern/webhooks).
7583
</Tab>
@@ -88,18 +96,24 @@ navigation:
8896

8997
When using multiple webhook definitions, organize them in separate directories within your Fern project:
9098

91-
```bash
92-
fern/
93-
└── apis/
94-
├── payment-webhooks/ # Payment webhook definitions
95-
│ ├── openapi/
96-
│ │ └── openapi.yml # Payment webhook OpenAPI spec
97-
│ └── generators.yml
98-
└── order-webhooks/ # Order webhook definitions
99-
├── openapi/
100-
│ └── openapi.yml # Order webhook OpenAPI spec
101-
└── generators.yml
102-
```
99+
<Files>
100+
<Folder name="fern" defaultOpen>
101+
<Folder name="apis" defaultOpen>
102+
<Folder name="payment-webhooks" defaultOpen highlighted comment="Payment webhook definitions">
103+
<Folder name="openapi">
104+
<File name="openapi.yml" comment="Payment webhook OpenAPI spec" />
105+
</Folder>
106+
<File name="generators.yml" />
107+
</Folder>
108+
<Folder name="order-webhooks" defaultOpen highlighted comment="Order webhook definitions">
109+
<Folder name="openapi">
110+
<File name="openapi.yml" comment="Order webhook OpenAPI spec" />
111+
</Folder>
112+
<File name="generators.yml" />
113+
</Folder>
114+
</Folder>
115+
</Folder>
116+
</Files>
103117

104118
### Create individual documentation pages for each webhook event
105119

‎fern/products/docs/pages/component-library/default-components/files.mdx‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -171,33 +171,33 @@ Use the `highlighted` property to highlight specific files or folders with an ac
171171

172172
<div className="highlight-frame">
173173
<Files>
174-
<Folder name="components" defaultOpen highlighted >
174+
<Folder name="components" defaultOpen highlighted>
175175
<File name="accordion.mdx" comment="Collapsible content sections"/>
176176
<File name="button.mdx" />
177177
<File name="card.mdx" />
178-
<File name="tabs.mdx" />
178+
<File name="tabs.mdx" highlighted/>
179179
</Folder>
180180
<Folder name="assets">
181-
<File name="styles.css" comment="Customize theme colors" />
181+
<File name="styles.css" comment="Customize theme colors"/>
182182
</Folder>
183-
<File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
184-
<File name="README.md" highlighted comment="Contribute to the docs" />
183+
<File name="markdown.mdx" href="/learn/docs/writing-content/markdown"/>
184+
<File name="README.md" highlighted comment="Contribute to the docs"/>
185185
</Files>
186186
</div>
187187

188-
```jsx Markdown maxLines=10 {2-3, 9, 12}
188+
```jsx Markdown maxLines=10
189189
<Files>
190-
<Folder name="components" defaultOpen highlighted >
190+
<Folder name="components" defaultOpen highlighted>
191191
<File name="accordion.mdx" comment="Collapsible content sections"/>
192192
<File name="button.mdx" />
193193
<File name="card.mdx" />
194-
<File name="tabs.mdx" />
194+
<File name="tabs.mdx" highlighted/>
195195
</Folder>
196196
<Folder name="assets">
197-
<File name="styles.css" comment="Customize theme colors" />
197+
<File name="styles.css" comment="Customize theme colors"/>
198198
</Folder>
199-
<File name="markdown.mdx" href="/learn/docs/writing-content/markdown" />
200-
<File name="README.md" highlighted comment="Contribute to the docs" />
199+
<File name="markdown.mdx" href="/learn/docs/writing-content/markdown"/>
200+
<File name="README.md" highlighted comment="Contribute to the docs"/>
201201
</Files>
202202
```
203203

0 commit comments

Comments
 (0)