Markdoc vs MDX on this site
How Markdoc-style authoring maps to MDX components used in this portfolio — for authors and AI-assisted editing.
TL;DR
Markdoc (e.g. at Freshworks) uses {% tags %} and a schema for custom nodes. This portfolio’s docs are authored in MDX with React components — same ideas (structured blocks, callouts, grids), different syntax.
Why this page exists
You asked for Markdoc-class documentation patterns. The production systems Thakur shipped used Markdoc heavily; this Next.js site uses MDX (next-mdx-remote + shared React components) because it fits the app router and static export.
Syntax mapping (cheat sheet)
| Markdoc-style pattern | MDX equivalent in this repo |
|---|---|
{% callout %} … {% /callout %} | <Callout type="info">…</Callout> |
{% highlight %} … {% /highlight %} | <Highlight type="tip" title="…">…</Highlight> |
| Custom “feature grid” | <FeatureGrid items={[…]} /> |
| Checklist / tasks | <Checklist items={[{ text: "…" }]} variant="static" /> |
| Code + title | <CodeBlock language="ts" title="…">{snippet}</CodeBlock> |
| Side-by-side compare | <ComparisonTable … /> |
Authoring guidelines (DX)
- Frontmatter — Every doc should set
title,description, andorderfor nav sorting. - Components over raw HTML — Prefer
Callout,Highlight,FeatureGridfor consistent theming and AI-friendly structure (headings + labeled blocks). - Stable headings — Use
##/###so TOCs and search snippets stay predictable. - Cross-links — Use trailing-slash paths (
/docs/skills/) to matchtrailingSlash: true.
AI & search context
- Search (⌘K) attaches result snippets to Ask AI as structured context.
/skills.mdis the portable skills summary for MCP and Cursor-style skills.- For JSON facts, use
/api/llm-context/when your deployment exposes API routes.