# Project structure

> For the complete documentation index, see [llms.txt](https://preview.writedocs.io/llms.txt).

How a Writedocs project is laid out - which files become pages, where the home page is, and where images, snippets and styles go.

A Writedocs project is a folder with a `writedocs.json` file in it. Everything else - pages, images, snippets - goes wherever suits you.

<Tree>
  <Tree.File name="writedocs.json" highlight />
  <Tree.File name="index.mdx" />
  <Tree.Folder name="docs" defaultOpen>
    <Tree.File name="quickstart.mdx" />
    <Tree.Folder name="guides" defaultOpen>
      <Tree.File name="webhooks.mdx" />
      <Tree.File name="webhook-flow.png" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.Folder name="images">
    <Tree.File name="logo-light.svg" />
    <Tree.File name="logo-dark.svg" />
  </Tree.Folder>
  <Tree.Folder name="snippets">
    <Tree.File name="beta-note.mdx" />
  </Tree.Folder>
  <Tree.File name="openapi.yaml" />
  <Tree.File name="theme.css" />
</Tree>

| File or folder | What it is |
| --- | --- |
| `writedocs.json` | The site's name, colors, navigation and everything else - see [writedocs.json](https://preview.writedocs.io/docs/configuration/overview/). |
| `index.mdx` | The home page, served at `/`. |
| `docs/` | Pages. A convention, not a requirement - any folder works. |
| `images/` | Images and other files, referenced by their path: `/images/logo-light.svg`. |
| `snippets/` | Content shared between pages - see [Snippets](https://preview.writedocs.io/docs/content/snippets/). |
| `openapi.yaml` | An OpenAPI spec, for an [API reference](https://preview.writedocs.io/docs/openapi/overview/). |
| `theme.css` | Your own styles, loaded on every page - see [Custom CSS and scripts](https://preview.writedocs.io/docs/configuration/custom-code/). |

## Pages

A `.md` or `.mdx` file is a page when it starts with a frontmatter block, or when `writedocs.json`'s navigation lists it:

```mdx title="docs/guides/webhooks.mdx"
---
title: Webhooks
description: Get notified when something changes.
---

Webhooks send an HTTP request to your server when ...
```

Any other Markdown file - a README, notes - is left alone.

A page's **id** is its path from the project folder, without the extension. The navigation uses the id, and the page's address is built from it:

| File | Id in `writedocs.json` | Address |
| --- | --- | --- |
| `index.mdx` | `index` | `/` |
| `about.mdx` | `about` | `/about/` |
| `docs/guides/webhooks.mdx` | `docs/guides/webhooks` | `/docs/guides/webhooks/` |
| `docs/guides/index.mdx` | `docs/guides` or `docs/guides/index` | `/docs/guides/` |

A page's `slug` frontmatter changes its address without moving the file - see [Frontmatter](https://preview.writedocs.io/docs/content/frontmatter/#slug).

`.md` files are plain Markdown. `.mdx` files can also use [components](https://preview.writedocs.io/docs/content/components/) and import [snippets](https://preview.writedocs.io/docs/content/snippets/) - see [Markdown basics](https://preview.writedocs.io/docs/content/markdown/).

## The home page

The home page, at `/`, is `index.mdx` at the project root - or any page with `slug: /` in its frontmatter. An `index.mdx` inside a folder is that folder's page instead: `docs/index.mdx` is served at `/docs/`.

A site without a home page sends `/` to the first page in the navigation.

## Images and other files

Put images anywhere in the project and use them by their path from the project folder, starting with `/`:

```mdx
![Webhook flow](/docs/guides/webhook-flow.png)
```

In a Markdown image, a path relative to the page works too: `![Webhook flow](./webhook-flow.png)`.

### Other files

Files in the project are published where they are - a PDF to download, a data file, a `robots.txt`:

| File in the project | Address |
| --- | --- |
| `files/terms.pdf` | `/files/terms.pdf` |
| `data/rates.json` | `/data/rates.json` |
| `robots.txt` | `/robots.txt` |

Link to one by its address: `[Terms](/files/terms.pdf)`.

These kinds of file are published:

- **Images and fonts** - `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico`, `.woff`, `.woff2`, `.ttf`, `.otf`
- **Text and data** - `.txt`, `.xml`, `.json`, `.csv`, `.webmanifest`
- **Downloads and media** - `.pdf`, `.zip`, `.mp4`, `.webm`, `.mov`, `.mp3`, `.wav`, `.ogg`

> Every file of these kinds in the project is public once the site is built, whether or not a page links to it. Keep anything that isn't meant to be read - a draft PDF, an export with customer data - outside the project, or in a folder whose name starts with a dot (`.drafts/`).

What isn't published:

- **The files the site is built from** - `writedocs.json`, `package.json` and similar files at the project root, and an OpenAPI spec the [API reference](https://preview.writedocs.io/docs/openapi/overview/) reads.
- **Pages, snippets, and your CSS and JavaScript** - they're part of the pages, not files of their own.
- **Folders whose name starts with a dot**, `node_modules/` and `dist/`.
- **Any other kind of file** - a `.docx`, say.

To publish a file that's left out - the OpenAPI spec, for readers to download, or a kind of file not listed above - put it in a `public/` folder at the project root: `public/openapi.yaml` is published at `/openapi.yaml`. Everything in `public/` is published as it is, and when the same address exists in and outside `public/`, the one in `public/` is used.

A few files are written by the build when the project doesn't have them: [`robots.txt` and `sitemap.xml`](https://preview.writedocs.io/docs/configuration/seo-and-sitemap/#sitemap), and [`llms.txt`](https://preview.writedocs.io/docs/configuration/llms-txt/). Your own file at the project root replaces the generated one.

## Folders Writedocs skips

These are never scanned for pages:

- `node_modules/`, `dist/` and `public/` at the project root.
- Every folder whose name starts with a dot (`.git`, `.github`, ...).
- Anything listed in a `.mintignore` file at the project root - one pattern per line, in the same format as `.gitignore`:

  ```text title=".mintignore"
  drafts/
  internal-notes.md
  ```

`writedocs dev` doesn't write anything into your project: its working files live outside it.

## Where to go next

**[Navigation](https://preview.writedocs.io/docs/configuration/navigation-basics/)**

Put your pages in the sidebar, in groups, tabs and more.

**[Frontmatter](https://preview.writedocs.io/docs/content/frontmatter/)**

Every field a page's frontmatter accepts.