Writing Docs
Every page is a .doc.md, .doc.mdx, or .doc.tsx file, discovered recursively wherever
config.docs points (.documints/content/ by default - see
Configuration). Where you put the file makes no difference to
your site's structure - only its frontmatter does. This page, for example, lives at
guides/writing-docs.doc.md on disk purely for your own organizational convenience; moving
it to the content root wouldn't change its route or its place in the nav at all.
File naming
The .doc. suffix (.doc.md, .doc.mdx, .doc.tsx) is the one required convention -
it's how documints tells your actual content apart from anything else the glob might
otherwise match (a stray .md file, a component that isn't meant to be a page, etc).
Beyond that suffix, names and folders are free-form; only frontmatter drives routing.
title - required
A slash-delimited path that determines both the page's nav placement and its URL:
---
title: Guides/Writing Docs
---Each segment becomes a nested nav section. The last segment is the page's display title,
and every segment gets slugified into the URL - this page is /guides/writing/writing-docs.
A file whose title is a prefix of others (e.g. title: Guides on its own) becomes that
section's index page, shown when a visitor navigates to /guides directly - see this
section's own index page.
slug - optional
Overrides just the auto-slugified last URL segment, without touching the displayed title:
---
title: Reference/CLI
slug: cli-reference
---Routes to /reference/cli-reference, but still displays as "CLI" in the nav.
home - optional
Marks a page as the site's root, served at /:
---
title: Welcome
home: true
---There should be exactly one of these per site. It's excluded from the nav tree, matching how most docs sites treat their landing page as separate from the sidebar.
description - optional
A one-line summary of the page:
---
title: Guides/Introduction/Deploy
description: Build and deploy a static documints site to Cloudflare, Netlify, Vercel, GitHub Pages, or AWS.
---Not required, and nothing breaks without it - it's surfaced in docs-manifest.json and the
page's own .json sibling (see Using Documints with AI),
so an agent or external tool can tell what a page is about without fetching it first. One
field, no separate "AI description" to keep in sync.
related / prerequisites - optional
Route paths of other docs worth knowing about, for anything the route graph can't already derive on its own:
---
title: Guides/Introduction/Deploy
prerequisites:
- /guides/introduction/getting-started
------
title: Guides/Introduction/Getting Started
related:
- /guides/introduction/deploy
---Both are validated at build time the same way internal links in your content are - a path
that doesn't resolve to a real route fails the build with the same "broken internal link"
error, not a silent typo. There's no parent/previous/next frontmatter to set alongside
these - that hierarchy already comes for free from your route graph and order (see below),
so only add related/prerequisites for connections that genuinely aren't structural.
MDX
Anything that needs interactivity beyond Markdown can use .doc.mdx instead - it supports
embedding React components directly in the document.
TSX pages
For a page that's real React from top to bottom - not Markdown with the occasional
component dropped in - use .doc.tsx. A literal --- frontmatter block isn't valid TSX
syntax, so the same YAML instead lives inside a leading block comment:
/**
---
title: Guides/Writing/Playground
---
*/
import { useState } from "react";
export default function Playground() {
const [count, setCount] = useState(0);
return (
<button type="button" onClick={() => setCount((c) => c + 1)}>
Clicked {count} {count === 1 ? "time" : "times"}
</button>
);
}The comment block is parsed as plain text to discover the route, the same way
.doc.md/.doc.mdx frontmatter is - documints never has to execute the file (and resolve
its real imports) just to figure out where it belongs. See the live
Playground page for the full source.