Source: https://nishanth-fern-test.docs-staging.pageloop.ai/home/get-started/developer-guide

# Developer guide

DEVGUIDE Fern Editor is the fastest way to make changes, but when you need full control you can work with the source files directly.

## Project structure

Your docs project is organized like this:

For details on each file, see the [project structure documentation](https://buildwithfern.com/learn/docs/getting-started/project-structure).

## Configure with docs.yml

`docs.yml` is the single file that controls your site's look, feel, and structure — no custom code needed. Here's what you can adjust:

- [Colors](https://buildwithfern.com/learn/docs/configuration/site-level-settings#colors-configuration)

  Brand colors for light and dark modes
- [Typography](https://buildwithfern.com/learn/docs/configuration/site-level-settings#typography-configuration)

  Fonts for headings and body text
- [Logo and favicon](https://buildwithfern.com/learn/docs/configuration/site-level-settings#logo-configuration)

  Your brand logo and browser icon
- [Layout](https://buildwithfern.com/learn/docs/configuration/site-level-settings#layout-configuration)

  Page width, sidebar, and tabs placement
- [Navigation](https://buildwithfern.com/learn/docs/configuration/navigation)

  Sections, pages, tabs, and versioning
- [Navbar links](https://buildwithfern.com/learn/docs/configuration/site-level-settings#navbar-links-configuration)

  Links and buttons in your header

For the full reference, see the [site-level settings documentation](https://buildwithfern.com/learn/docs/configuration/site-level-settings).

## Writing pages in MDX

Pages are MDX files — Markdown with support for Fern [components](/components). Each page starts with frontmatter:

```markdown title="docs/pages/my-page.mdx"
---
title: Page title
subtitle: Optional subtitle
slug: my-page
---

Your content here. Use **bold**, *italic*, `code`, and standard Markdown.

## Headings create sections

Add components like <Note>, <Card>, and <Tabs> alongside your Markdown.
```

After creating a page, add it to `docs.yml` to include it in your navigation.

## Editing, previewing, and publishing

Clone the repository and open it in your editor of choice. Install the Fern CLI to preview changes locally as you work:

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

This starts a local dev server with hot-reloading at <http://localhost:3000>. Edit MDX files, update `docs.yml`, and see changes instantly.

### When you open a pull request

When you're ready, push your changes and open a pull request. This repository has GitHub Actions workflows (in `.github/workflows/`) that take it from there — your docs are validated, a shareable preview link is posted as a comment on your PR, and once merged to `main`, your docs are published to production automatically.

| Workflow           | Trigger                  | What it does                                                                                                                                                                              |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `check.yml`        | PRs and pushes to `main` | Runs `fern check` to validate your API spec and docs configuration                                                                                                                        |
| `preview-docs.yml` | Pull requests            | Generates a [preview URL](https://buildwithfern.com/learn/docs/preview-publish/previewing-changes#preview-links) and posts it as a PR comment so reviewers can see changes before merging |
| `publish-docs.yml` | Push to `main`           | [Publishes your docs](https://buildwithfern.com/learn/docs/preview-publish/publishing-your-docs) to production automatically                                                              |

These workflows require a `FERN_TOKEN` [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). Generate one with `fern token` and add it in your repository's **Settings → Secrets and variables → Actions**.

## Going further

- [Custom CSS and JavaScript](https://buildwithfern.com/learn/docs/customization/custom-css-js)

  Add custom styles and scripts to your site
- [Custom React components](https://buildwithfern.com/learn/docs/customization/custom-react-components)

  Build interactive components for your docs
- [SEO and metadata](https://buildwithfern.com/learn/docs/seo/setting-seo-metadata)

  Configure page-level SEO with frontmatter
- [CLI reference](https://buildwithfern.com/learn/cli-api-reference/cli-reference/overview)

  Full list of CLI commands and options