Skip to content

docs: Update quickstart guide formatting and improve readability #1146

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
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Update quickstart guide formatting and improve readability #1146

Show file tree
Hide file tree
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
2 changes: 1 addition & 1 deletion fern/products/docs/pages/getting-started/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,4 +155,4 @@ subtitle: A website builder for beautiful agent and developer-friendly docs.
</div>
</a>
</CardGroup>
</div>
</div>
10 changes: 5 additions & 5 deletions fern/products/docs/pages/getting-started/project-structure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ The `pages` folder is organized into subfolders based on the sections of your do

The `assets` folder contains any images or videos used in your documentation. You can reference these assets in your MDX files using relative paths.

Hellooo this is deep!!

<CodeBlock title="fern/assets">
```bash
assets
Expand Down Expand Up @@ -166,11 +168,11 @@ title: Fern's Documentation
</AccordionGroup>

<Note>
If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation.
If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation.

If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec:

```yaml title="generators.yml"
```yaml
api:
specs:
- openapi: ../openapi/openapi.json
Expand All @@ -189,6 +191,4 @@ The `fern.config.json` file specifies your organization name and the version of
"version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
}
```
</CodeBlock>


</CodeBlock>
121 changes: 60 additions & 61 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 @@ -11,12 +11,12 @@ 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'>
<Accordion title="Clone the starter repository">
Get started by cloning the [starter template](https://github.com/fern-api/docs-starter).

<CodeBlocks>
Expand All @@ -31,35 +31,35 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
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.
Please edit the details `fern.config.json` and `docs.yml` with your organization name.

<CodeBlocks>
<CodeBlock title="fern.config.json">
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "0.x.x"
}
```
```json {2}
{
"organization": "{{YOUR_ORGANIZATION}}",
"version": "0.x.x"
}
```
</CodeBlock>
<CodeBlock title="docs.yml">
```yml {2}
instances:
- url: {{YOUR_ORGANIZATION}}.docs.buildwithfern.com
```
```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:

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

<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
npm install -g fern-api
Expand All @@ -78,13 +78,13 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
├─ 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
Expand All @@ -95,9 +95,9 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
</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 +108,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,80 +123,80 @@ 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
```

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">
```yml
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
```
```yml
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>

### Preview your docs

<AccordionGroup toc={true}>
<Accordion title='Preview your docs locally'>
<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'>

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

<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 support@buildwithfern.com to configure this.
Please reach out to the Fern team at [support@buildwithfern.com](mailto:support@buildwithfern.com) to configure this.
</Accordion>
<Accordion title='Configure analytics'>

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