Project structure

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

• writedocs.json
• index.mdx
• docs
  • quickstart.mdx
  • guides
    • webhooks.mdx
    • webhook-flow.png
• images
  • logo-light.svg
  • logo-dark.svg
• snippets
  • beta-note.mdx
• openapi.yaml
• theme.css

Pages

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

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

A page’s slug frontmatter changes its address without moving the file - see Frontmatter.

.md files are plain Markdown. .mdx files can also use components and import snippets - see Markdown basics.

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 /:

![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:

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

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 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, and 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:

  .mintignore

  drafts/
  internal-notes.md

  ⧉

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

Where to go next