# Your First Whitepaper
URL: https://whitepaper.designervenkat.online/docs/coding-tutorials/first-whitepaper
Markdown: https://whitepaper.designervenkat.online/llms.mdx/docs/coding-tutorials/first-whitepaper
Site: White Papers - Designer Venkat
Author: Designer Venkat
Language: en
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 [#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 [#create-the-file]
```bash
touch content/docs/security/your-paper-slug.mdx
```
### Add frontmatter [#add-frontmatter]
Every MDX file starts with a YAML block between `---` markers. Two fields are required: `title` and `description`. The title becomes the `` and the search index entry; the description shows under the title and in social previews.
```mdx
---
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 `` will duplicate it.
### Write the abstract [#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.
```mdx
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 [#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.
```mdx
## 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 [#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.
```mdx
import { Callout } from "fumadocs-ui/components/callout";
Lamport's original Paxos paper is famously hard to read. Stoppable Paxos
(2008) is the version most implementations follow.
```
### Preview locally [#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 [#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 [#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.
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.