AI AI Tools Guidebook
Indie Dev & Website Building

AI-Assisted MDX Template Design: 10 Layout Patterns

Use Claude or Codex to design MDX article templates that actually fit your content — 10 reusable layout patterns, when to use each, and the prompt structure that produces clean components instead of styled soup.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Most AI-generated MDX templates start beautiful and become unreadable by article number 30 — too many one-off components, inconsistent spacing, layouts that fight your content. This article gives 10 layout patterns that hold up at 1000+ articles and the prompt structure to get them out of an LLM cleanly.

Background

MDX is Markdown plus components, so an article template is really two decisions: which Markdown elements to style globally, and which dedicated components to expose. AI is great at producing both, but only if you constrain it. Ask for “a beautiful article template” and you get gradient backgrounds and Tailwind soup. Give it a fixed list of components and a content sample, and it produces something you can actually maintain. The 10 patterns below are the ones we use across a 1200-article bilingual site.

The cost of template drift is non-linear. At 50 articles, inconsistency feels like minor polish work. At 500 articles, every drift becomes a refactor that has to touch hundreds of files. At 1000+ articles, you stop refactoring and start working around the drift in style overrides — which is the worst of both worlds. Define the vocabulary early.

How to tell

  • You are scaffolding a new content site or refreshing the layout of an existing one.
  • Your current template has 6+ ad-hoc styled divs per article and you keep tweaking them.
  • New writers (or AI) keep inventing new heading structures because the template does not have a clear vocabulary.
  • You want the same template to work for tutorials, troubleshooting, listicles, and reviews.

Quick verdict

Pick 5-7 core patterns from the list below. Define each as a single component (or a CSS class on a standard HTML element). Forbid all other ad-hoc styled blocks. Let AI generate articles within this fixed vocabulary, not invent new shapes per article.

The 10 patterns

  1. Step list: numbered steps with a bold lead phrase. Use ordered lists with a <strong> first sentence. No dedicated component needed.
  2. Compare table: 3-column max (option, when to use, when to skip). Render as standard Markdown table; style globally for striping and small caps headers.
  3. Decision tree: bullet list with conditional indentation. Cap nesting at 2 levels. Anything deeper is a separate section.
  4. Verdict box: single-paragraph <aside> styled with a left border. One per article, near the top.
  5. Code-with-caption: code block immediately followed by a one-line italic description. No special component; rely on CSS sibling selector.
  6. Diagnostic table: symptom-cause-fix. Three columns, rendered as Markdown table. Used in every troubleshooting article.
  7. Inline checklist: task list with - [ ] syntax. Useful for “before you start” sections.
  8. Quote block: for real screenshots of platform messages or rejection reasons. Style as a callout, not a generic blockquote.
  9. Comparison example: Bad/Good code or text pair. Render with a text code block and Bad: / Good: prefixes. Keep dead simple.
  10. Related links cluster: bullet list of 3-6 links under ## Related, always at the end. Same shape every article.

Prompt structure that produces clean output

Send the LLM three things: the fixed pattern list, a single real article in MDX as a sample, and the new article topic. Anchor the prompt with these constraints:

- Use only the 10 patterns listed. Do not invent components or styled divs.
- Headings: ## level only, no ### unless content has 4+ subsections.
- No emoji, no exclamation marks, no marketing voice.
- First paragraph: 2-3 sentences, no heading.
- Last section is always "## Related" with 3-6 links.
- Tone matches the sample article.

Without the sample article as anchor, the model averages over its training data and you get generic SaaS-blog voice. With the sample, it copies your house style — usually well enough that a 10-minute edit is all you need per article.

How to enforce the vocabulary

  • Write a lint script that scans every MDX file: counts ## headings, checks the final section is ## Related, flags components outside the allowlist, flags raw <div> tags in prose.
  • Run the lint as a prebuild step. If a file fails, the build fails. This is the cheapest way to keep 1000 articles in line.
  • For new article PRs, include a small checklist: which of the 10 patterns are used, which are not, why.
  • Keep an examples/ folder with one MDX per pattern as living documentation. AI can read these when generating new content.

Migrating a legacy template

  • Inventory every existing component used across articles. Most legacy templates have 30+ components, half of which appear once.
  • Map each existing component to one of the 10 patterns, or mark it for deletion. Aim for a 5:1 reduction.
  • Run a codemod pass that replaces deprecated components with their standard equivalents. AI is good at writing the codemod once you give it 3-5 before/after examples.
  • Migrate in batches of 50-100 articles. Build after each batch; an unexpected break in one article usually means the codemod missed an edge case.

Common mistakes

  • Letting the model invent new components for “visual variety”. Variety kills consistency. The pattern list is the variety.
  • Asking for “a beautiful template” with no constraints. You get gradients, animations, and three font families.
  • Generating components without checking they work in MDX. Some libraries break MDX braces — test with one article first.
  • Skipping the sample article. The model defaults to whatever blog template was popular in its training set, not your style.
  • Adding decorative dividers (---) between every section. MDX renders them as <hr>; they add visual noise without information.

FAQ

  • Should I let the model design the components directly?: For the first pass, yes. For the final styling, do it yourself or have a designer pair with the model. AI is good at proposing shapes, less good at picking spacing and color systems.
  • How do I prevent template drift across 1000 articles?: Lint every MDX file: check that headings are at the right level, that the closing section is ## Related, that no article uses components outside the allowlist. A 30-line script catches 90% of drift.
  • Can I use the same template for English and Chinese?: Yes. Define spacing, font stack, and line height once. The Chinese version usually needs tighter line height and a different font fallback; everything else stays identical.
  • What about dark mode?: Define semantic tokens (background, foreground, muted, accent) and let the components use them. Do not hardcode colors in any component, ever.
  • Should I use shadcn or build raw?: For an article-heavy content site, build raw. shadcn is great for app UI but adds weight you do not need for prose. 200 lines of CSS and 5 components beats a component library here.
  • What about syntax highlighting?: Use Shiki at build time, not Prism in the browser. Shiki ships zero JS to the client and renders identically. Configure two themes (light, dark) and switch via CSS variables.
  • Do I need an MDX provider for global components?: Only if you actually use shared components like Aside or Callout across many files. For a 5-component vocabulary, importing each component per file is fine and keeps the build simpler.
  • How do I handle responsive design in MDX?: All responsive logic lives in the layout, not in MDX. The article body should be plain Markdown with components. The container layout decides breakpoints, fluid type, and spacing.
  • Should I version the template?: Yes, informally. Tag major template changes in a CHANGELOG.md so you know which articles were authored under v1 vs v2. Helps when debugging style anomalies on older articles.

Tags: #Indie dev #ai-assisted #building #MDX

Related Articles