How to Write Posts for the /i/ Route

What This Is

The /i/ route serves standalone MDX pages from the filesystem. These are SEO landing pages, reference docs, and evergreen content that lives outside the Payload CMS. Every .mdx file in apps/web/content/i/ becomes a page at /i/{filename}.

This article is the canonical reference for writing them.

Frontmatter

Every file starts with a YAML frontmatter block. Three fields are required. The rest are optional.

---
title: "Your Page Title"
description: "A concise meta description for SEO and social previews. Keep it under 160 characters."
publishedAt: "2026-02-09"
updatedAt: "2026-02-10"
image: "https://example.com/og-image.jpg"
tags:
  - topic-one
  - topic-two
---

Required Fields

• title — The h1 heading and the value used in <title>, OpenGraph, and JSON-LD. Keep it clear and direct. No clickbait.
• description — Appears below the title on the page, in search results, and in social card previews. One or two sentences. Under 160 characters is ideal.
• publishedAt — ISO date string (YYYY-MM-DD). Used for display, sorting, and datePublished in structured data.

Optional Fields

• updatedAt — ISO date string. If set, used as dateModified in JSON-LD. Useful for evergreen content you revise over time.
• image — Full URL to an OpenGraph image. When set, Twitter cards use summary_large_image instead of summary.
• tags — Array of lowercase strings. Displayed as badges below the article content. Use consistent tag names across posts so they group naturally.

File Naming

The filename becomes the URL slug. Use lowercase kebab-case.

| Filename | URL | |---|---| | best-gaming-headsets.mdx | /i/best-gaming-headsets | | how-to-host-a-tournament.mdx | /i/how-to-host-a-tournament | | writing-posts-for-llms.mdx | /i/writing-posts-for-llms |

Keep slugs short, descriptive, and permanent. Changing a filename breaks the old URL with no redirect.

Content Structure

Use standard markdown. The frontmatter title renders as the h1, so start your content with h2 (##) headings.

Heading Hierarchy

## Major Section
### Subsection
#### Detail (use sparingly)

Do not skip levels. Do not use h1 in the body. Screen readers and crawlers rely on a clean heading tree.

Paragraphs

Write short paragraphs. Two to four sentences each. A wall of text is hard to scan on screens and harder for an LLM to parse into distinct ideas.

Leave a blank line between every block element (paragraphs, lists, headings, code blocks). Markdown requires this for correct parsing, and it makes the source readable.

Lists

Use unordered lists for items with no sequence:

- First item
- Second item
- Third item

Use ordered lists when order matters:

1. Do this first
2. Then this
3. Finally this

Do not nest lists more than two levels deep. Flatten complex hierarchies into separate sections instead.

Links

Internal links (to other pages on the site) use relative paths:

[Check out the blog](/blog)

External links automatically open in a new tab with rel="noopener noreferrer":

[Discord](https://discord.gg/example)

Images

Use standard markdown image syntax. Images are rendered through Next.js Image for optimization:

![Alt text describing the image](https://example.com/image.jpg)

Always write meaningful alt text. Never leave it empty.

Code

Inline code uses single backticks: like this.

Code blocks use triple backticks with a language identifier:

```js
const x = 1;
```

Supported languages include js, ts, jsx, tsx, bash, yaml, json, css, html, python, sql, and many others. Always specify the language for syntax highlighting.

Tables

Markdown tables work and are styled by the prose classes:

| Column A | Column B |
|----------|----------|
| Value 1  | Value 2  |

Keep tables simple. If a table has more than four or five columns, consider restructuring the data as a list or multiple smaller tables.

Emphasis

Use bold for key terms or important callouts. Use italics for titles of works or subtle emphasis. Do not overuse either. If everything is bold, nothing stands out.

Blockquotes

Use blockquotes for callouts or attributed quotes:

> This is important context the reader should not skip.

Writing for LLM Readability

LLMs process these pages during retrieval-augmented generation, sitemap crawling, and when users paste content into chat. Structuring content well for LLMs also makes it better for humans.

Be Explicit

State things directly. Do not rely on visual formatting or surrounding context to convey meaning. Every section should make sense if read in isolation.

Bad:

## Settings
See above for details. The same applies here.

Good:

## Settings
Server settings are configured in the Discord server's admin panel under **Server Settings > Integrations**. Each bot must be assigned a role with the permissions it needs.

Use Descriptive Headings

Headings are the primary way LLMs segment and retrieve content. A heading like "Details" or "More Info" is nearly useless. A heading like "How to Configure Auto-Moderation Rules" tells the model exactly what follows.

Front-Load Key Information

Put the most important fact in the first sentence of each section. LLMs (and humans) often only read the opening line before deciding whether to continue. Do not bury the answer in paragraph three.

One Idea Per Section

Each section under a heading should cover one topic. If you find yourself writing "also" or "additionally" to pivot to a different subject, that is a signal to create a new heading.

Use Structured Data When Possible

Lists, tables, and key-value patterns are easier for LLMs to extract than prose. When presenting options, comparisons, or specifications, prefer structured formats:

Instead of this:

The bot supports three log levels. Debug mode logs everything including raw payloads. Info mode logs standard operations. Error mode only logs failures.

Write this:

| Log Level | What It Logs |
|-----------|-------------|
| `debug` | Everything including raw payloads |
| `info` | Standard operations |
| `error` | Failures only |

Avoid Ambiguous References

Do not use "it", "this", "that", or "the above" to refer to something from a previous section. Repeat the noun. LLMs process chunks independently and may not have the referent in context.

Define Jargon on First Use

If a term is specific to the project or community, define it the first time it appears. Do not assume the reader (human or LLM) knows what "sigma panel" or "duel command" means.

What Not to Do

• Do not use MDX components or imports. These files are compiled with a minimal component set (a and img overrides only). Custom JSX will fail at build time.
• Do not use HTML tags. Stick to markdown. Raw HTML may not be styled correctly by the prose classes.
• Do not duplicate CMS content. Blog posts and guides belong in Payload. The /i/ route is for standalone pages that do not fit into the CMS collections.
• Do not add front-end navigation links to these pages. They are intentionally standalone. The index at /i/ is noindexed and exists only for internal reference.
• Do not use the test article as a template. Use this article instead. The test article exists only to verify the route works.

Checklist Before Publishing

1. Frontmatter has title, description, and publishedAt
2. Description is under 160 characters
3. Filename is lowercase kebab-case
4. Content starts with an h2, not an h1
5. No skipped heading levels
6. All links work (internal paths exist, external URLs resolve)
7. All images have alt text
8. Code blocks specify a language
9. Each section covers one idea with a descriptive heading
10. Key information is in the first sentence of each section
11. No ambiguous references across sections
12. Build passes locally (pnpm build)