Skip to content

docs: Improve formatting and readability of docs.yml documentation #1147

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: Improve formatting and readability of docs.yml documentation #1147

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
162 changes: 82 additions & 80 deletions fern/products/docs/pages/customization/what-is-docs-yml.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Docs.yml"
subtitle: "Customize your documentation using the docs.yml file"
description: "Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more."
title: Docs.yml
subtitle: Customize your documentation using the docs.yml file
description: Learn how to configure your Fern documentation site with the docs.yml file. Customize colors, typography, layout, analytics and more.
---

The `docs.yml` file is your primary tool for customizing your documentation site, including colors, typography, layout, analytics, and more. Start here for most customization needs before considering [custom CSS and JavaScript](/docs/customization/custom-css-js) for advanced use cases.
Expand Down Expand Up @@ -276,7 +276,6 @@ background-image:
Relative filepath to the dark-mode background image.
</ParamField>


## Typography configuration

```yaml docs.yml
Expand Down Expand Up @@ -319,47 +318,50 @@ typography:
### Font configuration

<Tabs>
<Tab title="Single Weight">
```yaml
typography:
bodyFont:
name: Inter-Regular
path: fonts/Inter-Regular.woff2
style: normal
```
</Tab>

<Tab title="Variable Font">
```yaml
typography:
headingsFont:
name: Inter-Variable
paths:
- path: ./fonts/Inter-Variable.woff2
weight: 400 700 # Supports range of weights
style: normal
```
</Tab>
<Tab title="Single Weight">
```yaml
typography:
bodyFont:
name: Inter-Regular
path: fonts/Inter-Regular.woff2
style: normal
```
</Tab>

<Tab title="Variable Font">
```yaml
typography:
headingsFont:
name: Inter-Variable
paths:
- path: ./fonts/Inter-Variable.woff2
weight: 400 700 # Supports range of weights
style: normal
```

</Tab>

<Tab title="Multiple Files">
```yaml
typography:
headingsFont:
name: Inter
paths:
- path: ./fonts/Inter-Regular.woff2
weight: 400
style: normal
- path: ./fonts/Inter-Bold.woff2
weight: 700
style: normal
- path: ./fonts/Inter-Italic.woff2
weight: 400
style: italic
```

<Tab title="Multiple Files">
```yaml
typography:
headingsFont:
name: Inter
paths:
- path: ./fonts/Inter-Regular.woff2
weight: 400
style: normal
- path: ./fonts/Inter-Bold.woff2
weight: 700
style: normal
- path: ./fonts/Inter-Italic.woff2
weight: 400
style: italic
```
</Tab>
</Tab>
</Tabs>


<ParamField path="name" type="string" required={false}>
The name of the font. Defaults to a generated name that will be used to reference your custom font in the eventually injected CSS.
</ParamField>
Expand Down Expand Up @@ -415,19 +417,19 @@ layout:
</ParamField>

<ParamField path="layout.searchbar-placement" type="string" required={false}>
Sets the placement of the searchbar. Can be one of `header`, `sidebar` or `header-tabs` (places the searchbar in the header but on the tabs row).
Defaults to `sidebar`.
Sets the placement of the searchbar. Can be one of `header`, `sidebar` or `header-tabs` (places the searchbar in the header but on the tabs row). Defaults to `sidebar`.

<Note>This setting is ignored when `disable-header` is set to true.</Note>
</ParamField>


<ParamField path="layout.tabs-placement" type="string" required={false}>
Set the placement of the tabs. Can be one of `header` or `sidebar`.
Defaults to `sidebar`.
Set the placement of the tabs. Can be one of `header` or `sidebar`. Defaults to `sidebar`.

<Note>This setting is ignored when `disable-header` is set to true.</Note>
</ParamField>


<ParamField path="layout.content-alignment" type="string" required={false}>
Set the alignment of the Markdown content. Can be one of `center` or `left`.
Defaults to `center`.
Expand All @@ -449,39 +451,41 @@ layout:
## GitHub configuration

<Tabs>
<Tab title="Single Instance">
```yaml
instances:
- url: plantstore.docs.buildwithfern.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: main
```
</Tab>

<Tab title="Multiple Instances">
```yaml
# Configure edit-this-page per instance
instances:
- url: plantstore.docs.buildwithfern.com
custom-domain: docs.plantstore.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: production
- url: plantstore-staging.docs.buildwithfern.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: staging
```
</Tab>
<Tab title="Single Instance">
```yaml
instances:
- url: plantstore.docs.buildwithfern.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: main
```
</Tab>

<Tab title="Multiple Instances">
```yaml
# Configure edit-this-page per instance
instances:
- url: plantstore.docs.buildwithfern.com
custom-domain: docs.plantstore.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: production
- url: plantstore-staging.docs.buildwithfern.com
edit-this-page:
github:
owner: fern
repo: plant-store-docs
branch: staging
```

</Tab>
</Tabs>


<Warning>
The GitHub repository must be **public** for the "Edit this page" feature to work correctly.
</Warning>
Expand Down Expand Up @@ -557,7 +561,7 @@ analytics:

<ParamField path="analytics.posthog.api-key" type="string" required={false}>
Your PostHog project API key. Defaults to the api-host of "https://us.i.posthog.com".
</ParamField>
</ParamField>

## Dynamic snippets configuration

Expand All @@ -569,5 +573,3 @@ Enable dynamic snippets in `docs.yml`, then configure them by [following the SDK
experimental:
dynamic-snippets: true
```