Skip to content

docs: Polish quickstart guide formatting and links #1204

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

Closed
wants to merge 1 commit into from
Closed

docs: Polish quickstart guide formatting and links #1204

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
216 changes: 115 additions & 101 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 @@ -5,99 +5,107 @@ subtitle: Start building beautiful documentation in under 5 minutes

<img alt="Docs cascade" src="./images/docs-cascade.png" />

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).
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). and more!

In this guide, we'll show you how to get started with Fern in under 5 minutes.

EDIT

<Steps toc={true}>
### Initialize your `fern` folder
All the configurations for your docs live in the `fern` folder. Inside, you'll
find a `docs.yml` file that contains all the settings for your documentation.

All the configurations for your docs live in the `fern` folder. Inside, you'll
find a `docs.yml` file that contains all the settings for your documentation.

<AccordionGroup toc={true}>
<Accordion title='Clone the starter repository'>
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).
<Accordion title="Clone the starter repository">
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).

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

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

Next, please update the template settings to use your organization.
Next, please update the template settings to use your organization.

<Warning title="Edit template settings">
Please edit the details `fern.config.json` and `docs.yml` with your organization
name.
<Warning title="Edit template settings">
Please edit the details `fern.config.json` and `docs.yml` with your organization
name.

<CodeBlocks>
<CodeBlock title="fern.config.json">
```json {2}
<CodeBlocks>
<CodeBlock title="fern.config.json">
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "0.x.x"
}
```
</CodeBlock>
<CodeBlock title="docs.yml">
```yml {2}
</CodeBlock>

<CodeBlock title="docs.yml">
```yml {2}
instances:
- url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com
```
</CodeBlock>
</CodeBlocks>
</Warning>
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
</CodeBlock>
</CodeBlocks>
</Warning>

```bash
fern generate --docs
```
</Accordion>
<Accordion title='Use the Fern CLI'>
If you prefer, you can use our CLI to create a new project. Install the CLI
by running
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:

```bash
npm install -g fern-api
```
```bash
fern generate --docs
```
</Accordion>

Then run
<Accordion title="Use the Fern CLI">
If you prefer, you can use our CLI to create a new project. Install the CLI
by running

```bash
fern init --docs
```
```bash
npm install -g fern-api
```

You will see a new `fern` folder in your project with the following structure:
Then run

```bash
fern
├─ docs.yml
└─ fern.config.json
```
Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
```bash
fern init --docs
```

```bash
fern generate --docs
```
</Accordion>
You will see a new `fern` folder in your project with the following structure:

```bash
fern
├─ docs.yml
└─ fern.config.json
```

Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:

```bash
fern generate --docs
```
</Accordion>

</AccordionGroup>

### Update your docs

<Note>
We provide a white-glove migration service as part of our Enterprise plan. Interested? Request it
[here](https://buildwithfern.com/contact).
[here](https://buildwithfern.com/contact).

</Note>

<AccordionGroup toc={true}>
<Accordion title='Add content' >
Add content with MDX files.
<Accordion title="Add content">
Add content with MDX files.

```markdown
---
title: "Page Title"
Expand All @@ -108,13 +116,12 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
```

<Note title="Supported Syntax">
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required.
Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required.
</Note>

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.
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.

```yml
```
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
Expand All @@ -124,28 +131,31 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
path: docs/pages/hello-world.mdx
```
</Accordion>
<Accordion title='Add an API Reference' >

<Accordion title="Add an API Reference">
Add an API Reference by adding an OpenAPI Specification to your project.

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

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.
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.

```yml
navigation:
- api: "API Reference"
```

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

<Accordion title="Brand your docs">
All of the branding for your docs can be configured in the `docs.yml` file.

For example, to set the logos, colors, and fonts for your docs, you can
add the following to your `docs.yml` file:
For example, to set the logos, colors, and fonts for your docs, you can
add the following to your `docs.yml` file:

<CodeBlock title="docs.yml">
<CodeBlock title="docs.yml">
```yml
colors:
accent-primary:
Expand All @@ -160,44 +170,48 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.

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

</Accordion>

</AccordionGroup>

### Preview your docs

<AccordionGroup toc={true}>
<Accordion title='Preview your docs locally'>
You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally).
</Accordion>
<Accordion title='Preview your docs in a PR'>
`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).
</Accordion>
<Accordion title="Preview your docs locally">
You can preview your docs locally for testing purposes by following the instructions [here](/docs/preview-publish/previewing-changes-locally).
</Accordion>

<Accordion title="Preview your docs in a PR">
`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).
</Accordion>

</AccordionGroup>

### Publish to production

<AccordionGroup toc={true}>
<Accordion title='Publishing your docs'>
When you are ready for your docs to be publicly accessible, you can publish them using the Fern CLI.
<Accordion title="Publishing your docs">
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)
</Accordion>
<Accordion title='Host on a custom domain'>
Fern supports hosting your docs website on a custom domain or on a
custom subpath (e.g. `https://example.com/docs`).
[Read more.](/learn/docs/preview-publish/publishing-your-docs)
</Accordion>

Please reach out to the Fern team at [email protected] to configure this.
</Accordion>
<Accordion title='Configure analytics'>
Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,
Google Tag Manager, etc.
Find out more on this [page](/learn/docs/integrations/overview).
</Accordion>
<Accordion title="Host on a custom domain">
Fern supports hosting your docs website on a custom domain or on a
custom subpath (e.g. `https://example.com/docs`).

</AccordionGroup>
Please reach out to the Fern team at [[email protected]](mailto:[email protected]) to configure this.
</Accordion>

<Accordion title="Configure analytics">
Fern supports integrations with a variety of providers such as PostHog, Segment, Intercom,
Google Tag Manager, etc.
Find out more on this [page](/learn/docs/integrations/overview).
</Accordion>

</AccordionGroup>
</Steps>

[View examples of documentation websites](https://buildwithfern.com/customers) that have been published using Fern.

[View examples of documentation websites](https://buildwithfern.com/customers) that have been published using Fern.