Your First Whitepaper
Walk through publishing a paper end-to-end, from frontmatter to deployed URL.
This guide takes a single whitepaper from blank file to live URL. The whole loop should take about ten minutes.
The structure of a whitepaper
A paper lives as an MDX file under a topic folder in content/docs/ — for example content/docs/security/. Pick a filename that reads well in a URL — consensus-under-network-partitions.mdx is better than paper3.mdx.
Create the file
touch content/docs/security/your-paper-slug.mdxAdd frontmatter
Every MDX file starts with a YAML block between --- markers. Two fields are required: title and description. The title becomes the <h1> and the search index entry; the description shows under the title and in social previews.
---
title: Consensus Under Network Partitions
description: A re-examination of CAP trade-offs in modern cloud topologies.
---Don't add a # Title heading in the body — Fumadocs renders the title from frontmatter. A second <h1> will duplicate it.
Write the abstract
The first paragraph is the abstract. Keep it tight — 150 words or less — and treat it as the only paragraph anyone might actually read.
The CAP theorem is often invoked to justify availability over consistency,
but the trade-off looks different when the partition probability is small
and the cost of inconsistency is large. This paper argues for...Break the body into sections
Use ## for top-level sections and ### for sub-sections. The right-hand TOC populates automatically from these. Aim for sections of 200–600 words each — longer than that, and readers lose the thread.
## Background
Prior work on consensus falls into three camps...
### Paxos and its descendants
...
### CRDTs and eventual consistency
...Drop in components where they earn their keep
Diagrams, tables, code blocks, and callouts make papers easier to skim. Don't sprinkle them everywhere — use one when the prose can't do the job alone.
import { Callout } from "fumadocs-ui/components/callout";
<Callout type="info" title="Aside">
Lamport's original Paxos paper is famously hard to read. Stoppable Paxos
(2008) is the version most implementations follow.
</Callout>Preview locally
If the dev server is running, the new file appears in the sidebar within a second of saving. Click through and check:
- The title and description look right
- Headings nest correctly in the TOC
- Code blocks have the right syntax highlighting
- Links resolve
Deploy
Push to your main branch. Whatever's configured in your CI — Vercel, Netlify, your own runner — picks up the change and rebuilds. The static export means the new page is live within a couple of minutes.
Editorial conventions
A few rules we follow to keep the collection coherent:
- Cite primary sources. Link directly to papers, not summary blog posts.
- One claim per section. If a section needs a sub-heading to introduce a second claim, split it.
- Quantify everything. "Significantly faster" is meaningless. "37% lower p99 latency on a 16-core box" is useful.
- Acknowledge limitations. Every paper has a "Discussion" section covering what the analysis doesn't cover.
Ready to publish?
Once your paper is in good shape, open a pull request. The editorial team reviews for clarity and factual accuracy — usually a 2-3 day turnaround.
How is this guide?