[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75505":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":15,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":27,"discoverSource":28},75505,"mdxg","vercel-labs\u002Fmdxg","vercel-labs","Spec for markdown presentation and interaction","https:\u002F\u002Fmdxg.org",null,"TypeScript",351,19,52,2,0,300,3.9,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:03:34","# Markdown Experience Guidelines (MDXG)\n\n**A specification for how interfaces should present and interact with markdown documents.**\n\nMarkdown is the most widely supported document format in software. Every AI model speaks it. Every developer reads it. Every platform renders it. But the experience of *using* markdown has barely changed in twenty years.\n\nA 50-line README and a 3,000-line technical spec get the same treatment: a flat scroll of rendered text. No navigation. No structure. No sense of where you are.\n\nMDXG fixes this.\n\n![MDXG Preview](assets\u002Fscreenshot.png)\n\n*The \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fmdxg\u002Ftree\u002Fmain\u002Fpackages\u002Fvscode\" target=\"_blank\">MDXG VS Code extension\u003C\u002Fa>, one implementation of the spec, turning a single markdown file into a navigable, multi-page experience.*\n\n**[Read the spec live at mdxg.org →](https:\u002F\u002Fmdxg.org)**\n\n## What MDXG Is\n\nMDXG is a specification for how interfaces should **present and interact with** markdown documents. It is not a syntax. It does not compete with CommonMark, GFM, or MDX. It sits one layer above, defining the experience, not the format.\n\n| Layer | |\n|-------|---|\n| **MDXG** | presentation + interaction spec |\n| **GFM \u002F MDX** | syntax extensions |\n| **CommonMark** | base syntax spec |\n\nMDXG works on any existing `.md` file with zero modifications. The spec operates at the presentation layer. Your files don't change, the way they are rendered does.\n\nAny interface that displays markdown (editors, documentation platforms, note-taking apps, AI interfaces, CMS systems) can implement MDXG.\n\n### How MDXG is different\n\n**From doc site generators** (VitePress, MkDocs, Docusaurus): MDXG is purely about the reading experience. It works on any `.md` file regardless of how your content is organized.\n\n**From markdown viewer tools** (VS Code extensions, desktop apps): many already provide great features, but each defines its own conventions. MDXG standardizes those conventions so implementations are consistent across platforms.\n\n## The Capabilities\n\nThe full specification is in [SPEC.md](SPEC.md). Here's the summary:\n\n**Virtual pages.** H1 and H2 headings split a document into navigable pages. A single markdown file becomes a multi-page experience. No file splitting, no config, no build step.\n\n**Page navigation.** The user can see all pages, jump to any page, and tell which page they're on. How this is surfaced (sidebar, dropdown, command palette, gesture) is up to the implementation.\n\n**Theme adaptation.** No custom colors. The interface inherits from its host: light, dark, or anything in between.\n\n**Code block rendering.** Fenced code blocks with a language tag get syntax highlighting. Every code block gets a copy button.\n\n**Task lists.** `- [ ]` and `- [x]` render as checkboxes.\n\n**Page outline.** H3–H6 headings within the current page are navigable, with the current heading indicated. Could be a sidebar, a floating panel, a dropdown, or anything else.\n\n**Sequential navigation.** Previous\u002Fnext page movement with visible page titles. Could be footer links, toolbar buttons, keyboard shortcuts, or swipe gestures.\n\n**Search.** Find text across all pages with match highlighting, match count, and next\u002Fprevious navigation.\n\n**Preview and source modes.** Toggle between rendered HTML and editable syntax-highlighted markdown, in place. No new tabs or windows.\n\n**Document links.** Clicking a link to another `.md` file opens it in the same MDXG-conforming viewer.\n\n**Math, diagrams, footnotes.** Encouraged extensions for `$...$` math, ` ```mermaid ` diagrams, and `[^1]` footnotes, with graceful fallbacks when unsupported.\n\n## Why Now\n\nMarkdown is the primary interface between humans and AI agents. When an agent generates documentation, explains code, writes a report, or drafts a proposal, it writes markdown. When a human reads, reviews, or edits that output, they're reading markdown.\n\nMarkdown is already ideal for agents: low token cost, simple to generate, trivial to parse. The missing piece is the human side. Without navigation, structure, and a polished reading experience, people reach for heavier formats. MDXG closes that gap so markdown can serve both audiences with one format.\n\nEvery company building an AI product, a developer tool, a documentation platform, or a knowledge base is rendering markdown somewhere. Most use the default rendering. MDXG defines what a complete markdown experience looks like so every team doesn't have to figure it out independently.\n\n## Reference Implementations\n\n| Package | Description | Status |\n|---------|-------------|--------|\n| [@mdxg\u002Fparser](packages\u002Fparser) | Shared markdown parser | Core library |\n| [@mdxg\u002Fvscode](packages\u002Fvscode) | VS Code extension | Reference implementation |\n| [@mdxg\u002Fweb](apps\u002Fweb) | Documentation site ([mdxg.org](https:\u002F\u002Fmdxg.org)) | Reference implementation |\n\n## For Implementors\n\nMDXG is designed to be implementable in any environment that renders markdown. The spec defines two conformance levels:\n\n**MDXG Viewer**: read-only. Theming, code block rendering, task lists, virtual pages, page navigation, page outline, sequential navigation, and search.\n\n**MDXG Editor**: full. Everything in Viewer, plus mode toggle (preview\u002Fsource\u002Fboth) and document links.\n\nStart with the [spec](SPEC.md). Look at the [VS Code reference implementation](packages\u002Fvscode) for a working example. The shared parser ([`@mdxg\u002Fparser`](packages\u002Fparser)) handles document splitting, heading extraction, and slug generation. It is framework-agnostic and can be used as-is or adapted to any platform.\n\n## Contributing\n\nContributions are welcome: spec feedback, bug reports, new implementations, and code changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\nSee the [GitHub repository](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fmdxg) for issues, discussions, and pull requests.\n","Markdown Experience Guidelines (MDXG) 是一个旨在改善 Markdown 文档展示和交互体验的规范。其核心功能包括将文档通过 H1 和 H2 标题划分为虚拟页面，提供页面导航、代码块语法高亮及复制按钮、任务列表渲染为复选框以及当前页面内的标题导航等。MDXG 不改变现有的 Markdown 文件格式，而是专注于提升呈现层的用户体验，适用于任何显示 Markdown 的界面，如编辑器、文档平台、笔记应用、AI 接口和 CMS 系统。通过标准化这些交互特性，MDXG 使得不同平台上的 Markdown 阅读体验更加一致且高效。","2026-06-11 03:52:58","CREATED_QUERY"]