Skip to content

DO NOT MERGE #4347

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

Draft
fern-api wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

DO NOT MERGE #4347

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
301 changes: 160 additions & 141 deletions fern/products/docs/pages/getting-started/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,200 +23,217 @@ Or, follow this guide to get started with Fern using the CLI.

<Steps toc={true}>
<Step title="Install the CLI">
Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line:

Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line:
```bash
npm install -g fern-api
```

```bash
npm install -g fern-api
```
### Just testing!
</Step>
<Step title="Initiate your docs">

All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch
<Step title="Initiate your docs">
All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch

<AccordionGroup>
<Accordion title="Use the starter template">
Use the `fern-api/docs-starter` repository as a template for your site:

Use the `fern-api/docs-starter` repository as a template for your site:
1. Navigate to [fern-api/docs-starter](https://github.com/fern-api/docs-starter) and click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub.
2. Choose the option to **create a new repository**. Name it `fern-docs`.
3. Clone your newly created repository and open it in your favorite code editor (e.g., Cursor, VS Code).
1. Navigate to [fern-api/docs-starter](https://github.com/fern-api/docs-starter) and click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub.
2. Choose the option to **create a new repository**. Name it `fern-docs`.
3. Clone your newly created repository and open it in your favorite code editor (e.g., Cursor, VS Code).

<CodeBlocks>
```bash title="SSH"
git clone git@github.com:fern-api/docs-starter.git
```

<CodeBlocks>
```bash title="SSH"
git clone git@github.com:fern-api/docs-starter.git
```
```bash title="HTTPS"
git clone https://github.com/fern-api/docs-starter.git
```
</CodeBlocks>

You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files.

<Files>
<Folder name="fern" defaultOpen>
<Folder name="docs" comment="Markdown content and assets">
<Folder name="pages">
<File name="welcome.mdx" />
<File name="sdks.mdx" />
<File name="light.mdx" />
<File name="concepts.mdx" />
<Folder name="tutorials" />
<Folder name="get-started" />
<Folder name="capabilities" />
</Folder>
<Folder name="changelog" comment="Version history and release notes"/>
<Folder name="assets" />
<Folder name="snippets" comment="Reusable content blocks">
<File name="note.mdx" />
```bash title="HTTPS"
git clone https://github.com/fern-api/docs-starter.git
```
</CodeBlocks>

You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files.

<Files>
<Folder name="fern" defaultOpen>
<Folder name="docs" comment="Markdown content and assets">
<Folder name="pages">
<File name="welcome.mdx" />

<File name="sdks.mdx" />

<File name="light.mdx" />

<File name="concepts.mdx" />

<Folder name="tutorials" />

<Folder name="get-started" />

<Folder name="capabilities" />
</Folder>

<Folder name="changelog" comment="Version history and release notes" />

<Folder name="assets" />

<Folder name="snippets" comment="Reusable content blocks">
<File name="note.mdx" />
</Folder>
</Folder>

<File name="docs.yml" comment="Defines navigation, theme, and hosting details" />

<File name="fern.config.json" comment="Specifies org name and CLI version" />

<File name="generators.yml" comment="Configures SDK generation" />

<File name="openapi.yaml" comment="API definition" />
</Folder>
<File name="docs.yml" comment="Defines navigation, theme, and hosting details"/>
<File name="fern.config.json" comment="Specifies org name and CLI version"/>
<File name="generators.yml" comment="Configures SDK generation"/>
<File name="openapi.yaml" comment="API definition"/>
</Folder>
<File name="README.md" />
</Files>

<File name="README.md" />
</Files>
</Accordion>

<Accordion title="Start from scratch">
```bash
fern init --docs
```

```bash
fern init --docs
```
You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files):

You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files):
<Files>
<Folder name="fern" defaultOpen>
<File name="docs.yml" comment="Defines navigation, theme, and hosting details" />

<Files>
<Folder name="fern" defaultOpen>
<File name="docs.yml" comment="Defines navigation, theme, and hosting details"/>
<File name="fern.config.json" comment="Specifies org name and CLI version"/>
</Folder>
</Files>
<File name="fern.config.json" comment="Specifies org name and CLI version" />
</Folder>
</Files>
</Accordion>
</AccordionGroup>
</Step>
<Step title="Configure your organization">

Configure two settings (these values don't have to match):
</Step>

- **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/))
- **Docs URL** in `docs.yml`: Determines where your docs are published
<Step title="Configure your organization">
Configure two settings (these values don't have to match):

* **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/))
* **Docs URL** in `docs.yml`: Determines where your docs are published

<CodeBlock title="fern.config.json">
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
}
```
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
}
```
</CodeBlock>

<CodeBlock title="docs.yml">
```yml {2}
instances:
- url: {{YOUR_DOMAIN}}.docs.buildwithfern.com
```
```yml {2}
instances:
- url: {{YOUR_DOMAIN}}.docs.buildwithfern.com
```
</CodeBlock>

<Note>
Use only alphanumeric characters, hyphens, and underscores for both values.
Use only alphanumeric characters, hyphens, and underscores for both values.
</Note>

</Step>
<Step title="Customize your docs">

Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).)
<Step title="Customize your docs">
Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).)
Copy link
Contributor

@github-actions github-actions bot Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [vale] reported by reviewdog 🐶
[FernStyles.Current] Avoid time-relative terms like 'Now' that become outdated


<AccordionGroup toc={true}>
<Accordion title='Add content' >

Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more.
<Accordion title="Add content">
Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more.

<Note>
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages.
</Note>
<Note>
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages.
</Note>

```markdown docs/pages/hello-world.mdx
---
title: "Page Title"
description: "Subtitle (optional)"
---
```markdown docs/pages/hello-world.mdx
---
title: "Page Title"
description: "Subtitle (optional)"
---

Hello world!
```
Hello world!
```

Reference your new pages from your `docs.yml` file. You can reference the
Markdown page within a section or as a standalone page.

```yml docs.yml
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
- section: Overview
contents:
- page: Getting Started
path: docs/pages/getting-started.mdx
```
Reference your new pages from your `docs.yml` file. You can reference the
Markdown page within a section or as a standalone page.

```yml docs.yml
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
- section: Overview
contents:
- page: Getting Started
path: docs/pages/getting-started.mdx
```
</Accordion>
<Accordion title='Add an API Reference' >

If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec:
<Accordion title="Add an API Reference">
If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec:

```bash
fern init --openapi /path/to/openapi.yml
```
```bash
fern init --openapi /path/to/openapi.yml
```

Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref):
Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref):

```yml docs.yml
navigation:
- api: "API Reference"
```
```yml docs.yml
navigation:
- api: "API Reference"
```
</Accordion>
<Accordion title='Brand your docs'>

[Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file.

<CodeBlock title="docs.yml">
```yml maxLines=7
colors:
accent-primary:
dark: "#f0c193"
light: "#af5f1b"

logo:
dark: docs/assets/logo-dark.svg
light: docs/assets/logo-light.svg
height: 40
href: https://buildwithfern.com/

favicon: docs/assets/favicon.svg
```
</CodeBlock>
<Accordion title="Brand your docs">
[Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file.

<CodeBlock title="docs.yml">
```yml maxLines=7
colors:
accent-primary:
dark: "#f0c193"
light: "#af5f1b"

logo:
dark: docs/assets/logo-dark.svg
light: docs/assets/logo-light.svg
height: 40
href: https://buildwithfern.com/

favicon: docs/assets/favicon.svg
```
</CodeBlock>
</Accordion>
</AccordionGroup>

</Step>
<Step title="Preview your docs">

Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links.
<Step title="Preview your docs">
Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links.

<Tabs>
<Tab title="Local preview">
Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files:

Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files:

```bash
fern docs dev
```
```bash
fern docs dev
```
</Tab>
<Tab title="Shareable preview link">

Generate a preview URL you can share with your team:
<Tab title="Shareable preview link">
Generate a preview URL you can share with your team:

```bash
fern generate --docs --preview
```
```bash
fern generate --docs --preview
```
</Tab>
</Tabs>

Expand All @@ -225,9 +242,9 @@ Or, follow this guide to get started with Fern using the CLI.
</Info>

</Step>
<Step title="Publish to production">

When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs):
<Step title="Publish to production">
When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs):

```bash
fern generate --docs
Expand All @@ -236,11 +253,13 @@ Or, follow this guide to get started with Fern using the CLI.
You'll be prompted to log in and connect your GitHub account. This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`).

<Info>
Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs.
Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs.
</Info>

</Step>
</Steps>


## Explore Fern's features

Now that your docs are live, explore these features to enhance them further.
Expand Down
Loading