Skip to content

(docs) Clarify reference path structure, restructure some sections #1830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 6, 2025
+23 −11
Merged

(docs) Clarify reference path structure, restructure some sections #1830

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
34 changes: 23 additions & 11 deletions fern/products/docs/pages/component-library/custom-components/reusable-markdown.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,12 @@ Keep your documentation DRY (Don't Repeat Yourself) by defining a reusable Markd

Reusable snippets work well for constants (API limits, subscription prices, version numbers), repeated warnings or notes, and standardized formatting blocks.

## Create a reusable snippet
<Steps>
<Step title="Create file structure">

To use reusable snippets, start by creating a new folder in your `fern` project called `snippets`. Inside the `snippets` folder, create a new Markdown file for each snippet you want to define.

For example:
Create a folder called `snippets` anywhere in your `fern` project. Inside the `snippets` folder, create a new Markdown file for each snippet you want to define.

```bash {3, 6-8}
```bash Example file structure {3, 6-8}
fern
└─ pages
└─ my-tutorial.mdx
Expand All @@ -23,16 +22,17 @@ fern
├─ peace-lily.mdx
└─ trees.mdx
```

In each snippet file, define the content you want to reuse. For example, `peace-lily.mdx` might contain:
</Step>
<Step title="Create snippet">
In each snippet file, define the content you want to reuse.

```mdx title="snippets/peace-lily.mdx"
<Warning> Remember to water your plant at least twice a week. </Warning>
```
</Step>
<Step title="Use a snippet">

## Use a reusable snippet

To use a snippet in your documentation, reference it by its file path (including the `.mdx` extension) in your content. For example, to include the `peace-lily` snippet in your content, use:
To use a snippet in your documentation, reference it by its file path (including the `.mdx` extension). For example, to include the `peace-lily` snippet from the folder structure above:

<Tabs>
<Tab title="Markdown">
Expand All @@ -50,4 +50,16 @@ To use a snippet in your documentation, reference it by its file path (including

<Markdown src="/snippets/peace-lily.mdx" />
</Tab>
</Tabs>
</Tabs>

<Note title="File paths">
The `src` path is an absolute path that takes the `fern` folder as the root. The path is the same no matter which page you're referencing it from:

| Folder structure | Reference |
| --- | --- |
| `fern/snippets/peace-lily.mdx` | `src="/snippets/peace-lily.mdx"` |
| `fern/docs/snippets/peace-lily.mdx` | `src="/docs/snippets/peace-lily.mdx"` |
| `fern/docs/guides/snippets/peace-lily.mdx` | `src="/docs/guides/snippets/peace-lily.mdx"` |
</Note>
</Step>
</Steps>