Skip to content

docs: Clean up quickstart guide formatting and links #1464

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
+121 −112
Closed

docs: Clean up quickstart guide formatting and links #1464

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
233 changes: 121 additions & 112 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 @@ -3,149 +3,154 @@
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).

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

<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

Check warning on line 63 in fern/products/docs/pages/getting-started/quickstart.mdx

View workflow job for this annotation

GitHub Actions / vale 

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

Raw Output:
{"message": "[FernStyles.Current] Avoid time-relative terms like 'new' that become outdated", "location": {"path": "fern/products/docs/pages/getting-started/quickstart.mdx", "range": {"start": {"line": 63, "column": 52}}}, "severity": "WARNING"}

Check warning on line 63 in fern/products/docs/pages/getting-started/quickstart.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[FernStyles.We] Try to avoid using first-person plural like 'our'.

Raw Output:
{"message": "[FernStyles.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "fern/products/docs/pages/getting-started/quickstart.mdx", "range": {"start": {"line": 63, "column": 32}}}, "severity": "INFO"}
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.
```markdown
---
title: "Page Title"
description: "Subtitle (optional)"
---

Hello world!
```
<Accordion title="Add content">
Add content with MDX files.

```markdown
---
title: "Page Title"
description: "Subtitle (optional)"
---

Hello world!
```

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

```
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
- section: Overview
contents:
- page: QuickStart
path: docs/pages/hello-world.mdx
```

```yml
navigation:
- page: Hello World
path: docs/pages/hello-world.mdx
- section: Overview
contents:
- page: QuickStart
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
```

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"
```
</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,45 +165,49 @@

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. [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`).
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="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`).

Check failure on line 195 in fern/products/docs/pages/getting-started/quickstart.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Foreign] Use 'for example' instead of 'e.g. '.

Raw Output:
{"message": "[Microsoft.Foreign] Use 'for example' instead of 'e.g. '.", "location": {"path": "fern/products/docs/pages/getting-started/quickstart.mdx", "range": {"start": {"line": 195, "column": 21}}}, "severity": "ERROR"}
Please reach out to the Fern team at [[email protected]](mailto:[email protected]) to configure this.

Check warning on line 196 in fern/products/docs/pages/getting-started/quickstart.mdx

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[FernStyles.Please] Avoid using 'Please' in technical documentation.

Raw Output:
{"message": "[FernStyles.Please] Avoid using 'Please' in technical documentation.", "location": {"path": "fern/products/docs/pages/getting-started/quickstart.mdx", "range": {"start": {"line": 196, "column": 5}}}, "severity": "WARNING"}
</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.

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