如果 Markdown 和 React 生了个孩子那它一定叫 Code Hike。一、什么是 Code HikeCode Hike是一个开源库它的核心使命极其清晰在 Markdown 的写作体验和 React 的表现力之间架一座桥。当你写技术博客、文档、教程的时候通常会面临一个两难选择纯 Markdown写得爽但排版受限代码块千篇一律交互为零。纯 React表现力无限但写内容要写 JSX内容与样式耦合维护噩梦。Code Hike 的思路是——小孩子才做选择成年人全都要。它通过在 Markdown 中注入轻量级的装饰语法将内容结构化然后在 React 组件层自由渲染。npx create-next-app-ehttps://github.com/code-hike/v1-starter一句话定位Code Hike MDX 插件 代码高亮引擎 注解系统 布局工具集。项目由 Rodrigo Pombo (pomber) 创建入选了GitHub Accelerator 首批扶持项目并获得Meta、Vercel、Speakeasy等公司赞助目前采用MIT 协议开源。二、核心设计理念内容与呈现彻底分离Code Hike 的设计哲学可以概括为一句话Markdown 负责是什么React 负责怎么呈现。2.1 传统 MDX 的问题传统 MDX 允许你在 Markdown 中嵌入 React 组件这确实增强了表现力但它把内容和呈现混在了一起# 我的博客 Callout typewarning 注意以下内容需要 Node.js 18 /Callout CodeBlock titlehello.js lineNumbers js console.log(hello)这种写法的痛点很明显每次换样式就要改内容文件非技术作者看到 JSX 就头大同一份内容在不同平台博客、文档站、Slide要写不同的组件。2.2 Code Hike 的做法Code Hike 引入了一个关键概念——装饰器Decorators。你在 Markdown 元素前加一个!name标记Code Hike 的 MDX 插件会把这些元素解析成结构化的Block 对象然后作为 props 传给 React 组件。你写在 Markdown 里的## !!steps 初始化项目 首先安装依赖 ## !!steps 配置插件 在 next.config 中添加 Code Hike ## !!steps 开始写作 创建你的第一篇 .mdx 文件Code Hike 帮你转换成的数据结构{steps:[{title:初始化项目,children:p首先安装依赖/p},{title:配置插件,children:p在 next.config 中添加 Code Hike/p},{title:开始写作,children:p创建你的第一篇.mdx 文件/p},]}你的 React 组件可以这样渲染export function Tutorial({ steps }) { return ( div {steps.map((step, i) ( StepCard key{i} number{i 1} title{step.title} {step.children} /StepCard ))} /div ) }内容和呈现完美解耦——同一份 Markdown 可以用完全不同的 React 组件渲染成博客、文档页、Slide、甚至视频脚本。三、Block 系统给 Markdown 加上类型系统Block 是 Code Hike 最核心的抽象它给无结构的 Markdown 注入了结构。3.1 装饰语法一览装饰器用途示例!name标记单个元素## !intro 简介!!name收集为数组## !!steps 第一步不加!普通内容传给children支持的被装饰元素标题##、###等!name后的文字作为title图片![!cover alt](/img.jpg)→ 提取alt、url、title代码块js !code main.js → 提取lang、meta、value段落!author Tolkien→ 段落文本作为值3.2 嵌套 Block利用标题层级天然实现嵌套MyComponent 魔戒的力量 ## !master 至尊魔戒 ### !!rings 精灵 三枚戒指 ### !!rings 矮人 七枚戒指 ### !!rings 人类 九枚戒指 /MyComponent解析结果{master:{title:至尊魔戒,children:p至尊魔戒/p,rings:[{title:精灵,children:p三枚戒指/p},{title:矮人,children:p七枚戒指/p},{title:人类,children:p九枚戒指/p},]}}3.3 类型安全Zod Schema 验证Code Hike 强烈推荐配合 Zod 做 Schema 校验这是它区别于其他 Markdown 方案的一个亮点import { z } from zod import { Block, CodeBlock, ImageBlock, parseProps } from codehike/blocks const Schema Block.extend({ author: z.string(), cover: ImageBlock.optional(), code: CodeBlock, steps: z.array(Block), }) export function MyPage(props: unknown) { const data parseProps(props, Schema) // data 现在有完整的 TypeScript 类型推导 // data.author → string // data.code → { lang, meta, value } // data.steps → { title, children }[] }这意味着你的 Markdown 内容是类型安全的。结构不符合 Schema编译阶段直接报错零运行时意外。3.4 根级 Block如果不想包裹组件可以直接在.md文件中使用装饰器然后用parseRoot解析import { parseRoot } from codehike/blocks import Content from ./content.md const Schema Block.extend({ features: z.array(Block), }) export default function Page() { const data parseRoot(Content, Schema) return FeatureList features{data.features} / }四、代码块系统不止于高亮如果说 Block 系统是 Code Hike 的骨架那代码块系统就是它的灵魂。4.1 自研高亮引擎LighterCode Hike 没有使用 Shiki 或 Prism而是自己写了一个高亮引擎——lighter。为什么造轮子核心原因是 Code Hike 的注解系统需要对 token 级别的精细控制。Shiki 的 transformer 机制操作的是 AST而 Code Hike 的注解是 React 组件——粒度不同、理念不同。内置 22 种主题dark-plusgithub-darkgithub-lightdraculamonokainordone-dark-prosolarized-darksolarized-lightmin-darkmin-lightmaterial-*系列等。还支持CSS 变量驱动的明暗主题github-from-css、material-from-css和自定义主题可通过 Theme Editor 在线编辑。支持 211 种语言从 Assembly 到 Zig从 GraphQL 到文言文覆盖面相当广。4.2 注解系统Annotations在代码里画重点这是 Code Hike 最具差异化的功能。你可以通过代码注释给代码块添加注解然后用 React 组件来渲染注解效果。基本语法// !name(起始行:结束行) query参数// !name[起始列:结束列] query参数两种注解类型类型作用范围语法场景块注解 (Block)多行代码// !highlight(1:3)高亮一个函数行内注解 (Inline)行内 token// !mark[5:9]标记一个变量4.2.1 示例高亮标记// !mark(2:3)functioncalculate(input){constresultprocess(input)// ← 这两行被标记returnresult*2// ←}4.2.2 示例正则匹配不用手动数行号列号直接用正则// !border[/ipsum/g] orangeconstloremipsumnull?ipsum:1dolorlorem-sit(dolor)所有匹配ipsum的 token 都会被打上橙色边框。4.2.3 示例start/end 标记constloremipsumnull?0:1// !highlight(start)dolorlorem-sit(dolor)letametlorem?consectetur(ipsum):3// !highlight(end)不用数行号用标记对来圈定范围。4.3 Handler 机制把注解渲染成任意 UI注解本身只是元数据真正让它们活起来的是AnnotationHandler。import { Pre, RawCode, highlight } from codehike/code import type { AnnotationHandler } from codehike/code const markHandler: AnnotationHandler { name: mark, Inline: ({ annotation, children }) ( span classNamebg-yellow-200 rounded px-0.5{children}/span ), } export async function Code({ codeblock }: { codeblock: RawCode }) { const highlighted await highlight(codeblock, github-dark) return Pre code{highlighted} handlers{[markHandler]} / }Handler 可以自定义的渲染层面组件作用Block渲染被注解包裹的代码块适合折叠、calloutInline渲染被注解标记的 token适合高亮、tooltipLine自定义每一行的渲染适合行号、缩进指示Token自定义每个 token 的渲染AnnotatedLine自定义被注解行的渲染AnnotatedToken自定义被注解 token 的渲染Pre/PreWithRef自定义整个pre元素4.4 注解变换Transform你可以在 handler 中定义transform函数在渲染前修改注解。这非常强大——一个注解可以拆成多个行内注解可以转成块注解const callout: AnnotationHandler { name: callout, transform: (annotation: InlineAnnotation) { // 把行内注解转成块注解 return { ...annotation, fromLineNumber: annotation.lineNumber, toLineNumber: annotation.lineNumber, data: { column: (annotation.fromColumn annotation.toColumn) / 2 }, } }, Block: ({ annotation, children }) ( {children} CalloutBubble column{annotation.data.column} {annotation.query} /CalloutBubble / ), }4.5 内置注解模式Copy-Paste 即用Code Hike 的文档提供了大量可直接复用的注解实现注解效果复杂度mark高亮标记 token⭐border边框框住代码区域⭐collapse折叠/展开代码块⭐⭐callout代码旁的气泡注释⭐⭐⭐tooltip悬浮显示 MDX 内容⭐⭐⭐fold折叠特定匹配内容⭐⭐⭐word-wrap自动换行⭐line-numbers行号显示⭐diffdiff 效果⭐⭐4.6 代码导入指令直接从文件导入代码避免复制粘贴js !from ./src/hello.js 代码块内容会被./src/hello.js的文件内容替换从此告别示例代码与源码不同步的痛点。五、安装与配置5.1 快速开始npx create-next-app-ehttps://github.com/code-hike/v1-starter5.2 手动安装npminstallcodehike在next.config.mjs中配置 MDX 插件import{remarkCodeHike,recmaCodeHike}fromcodehike/mdx/** type {import(codehike/mdx).CodeHikeConfig} */constchConfig{components:{code:Code},// 如果不支持 RSC在此处指定主题// syntaxHighlighting: {// theme: github-dark,// },}constmdxOptions{remarkPlugins:[[remarkCodeHike,chConfig]],recmaPlugins:[[recmaCodeHike,chConfig]],jsx:true,}5.3 框架兼容性框架支持程度备注Next.js Fumadocs✅ 最佳推荐组合完美支持 RSCNext.js (App Router)✅ 完整官方 Starter 使用的方案Nextra 3✅ 可用有官方模板Docusaurus✅ 可用有官方模板Remotion✅ 可用可用 Code Hike 做代码演示视频Astro❌ 不支持六、Scrollycoding杀手级布局Scrollycoding 是 Code Hike 最具代表性的布局模式——滚动讲解与代码同步广泛用于技术教程和代码 walkthrough。基本结构右侧固定代码块左侧内容随滚动切换。每滚动到一个 Section代码高亮/注解也随之切换。Scrollycoding ## !!steps 初始化 项目初始化的第一步... ## !!steps 路由 接下来配置路由... ## !!steps 数据层 然后设置数据获取... /Scrollycoding结合 Block 系统 代码注解Scrollycoding 可以做到滚动到某一步时自动高亮对应代码行代码中嵌入 callout 气球注释折叠非相关的代码区域自适应移动端stack 布局切换正是这种交互让 Code Hike 从一众 Markdown 工具中脱颖而出——它不是更好看的代码块而是把文档变成了一个交互式应用。七、竞品对比特性Code HikeShikiMarkdocMDX代码高亮✅ 自研 Lighter✅ TextMate 引擎需外部集成需外部集成代码注解✅ 一等公民⚠️ Transformer❌❌内容结构化✅ Block 系统❌✅ Tags⚠️ 手动类型安全✅ Zod Schema❌⚠️❌交互式布局✅ Scrollycoding❌❌⚠️ 手动文件导入✅!from❌❌❌框架耦合React 专属无耦合无耦合React 专属Code Hike 的真正优势不在于我能做而在于我做得极其顺手。Shiki 也能做代码注解——但要写大量 transformer 代码MDX 也能做结构化内容——但要手动组织组件树。Code Hike 把这些模式做了标准化封装让它们成为一种理所当然的使用方式。八、生态与应用场景8.1 谁在用 / 适合谁场景为什么适合大型文档站Block 系统让设计师和写作者并行工作内容与 UI 分离技术教程/BlogScrollycoding 代码注解是技术写作的黄金搭档API 参考文档克隆 Shopify API Reference 就是例子视频脚本/课程配合 Remotion 生成代码演示视频Landing Page结构化的内容可以在不同页面用不同组件渲染8.2 成功案例Shopify API Reference 克隆版用 Code Hike 重现了 Shopify 精美的 API 文档 UISwiftUI Tutorials 克隆版复刻了 Apple 的 SwiftUI 交互式教程体验Code Hike 自身文档站codehike.org 全站用 Code Hike 构建8.3 赞助商矩阵MetaFacebook 开源赞助、Vercel部署平台、SpeakeasyAPI 工具、ui.dev前端培训——这说明 Code Hike 不仅技术过硬商业生态也在稳步成型。九、总结与思考为什么 Code Hike 值得关注它解决了一个真实且普遍的痛点技术人员想写出好内容但工具链要么太简陋纯 Markdown要么太繁琐手写 React 组件。Code Hike 找到了那条刚刚好的分界线。注解系统是真正的差异化在代码注释中写!mark然后自动渲染成高亮——这种体验一旦用了就回不去。它把写代码注解变成了写作流程的自然延伸而不是额外的排版工作。类型安全的内容系统Zod Schema 验证让 Markdown 内容有了类型约束。这在多人协作的大型文档项目中意义重大——CI 里就能发现内容结构问题。生态定位精准不做框架Docusaurus/Nextra 已经够好了不做高亮器但自己写了一个来支撑注解只做内容结构化 代码表现力这一层。API 设计克制而优雅。踩坑点与局限React 专属这对 React 生态来说是优势对 Vue/Svelte 用户是硬伤。Astro 不支持Astro 的 MDX 处理方式与 Code Hike 的 remark/recma 插件链不兼容。学习曲线Block 概念 Schema 定义 Handler 编写初学者需要一点上手时间。文档建设中v1.1.0 刚发布2026.03部分功能如 Component Blocks标记为 “Coming soon”。一句话Code Hike 不是另一个 Markdown 渲染器它是Markdown 的类型系统 React 的渲染管线。如果你在做技术内容网站它应该是你工具箱里的首选武器。附录关键链接GitHub 仓库https://github.com/code-hike/codehike官方文档https://codehike.org/docs在线体验StackBlitz Starter主题编辑器https://themes.codehike.org/editor示例仓库https://github.com/code-hike/examplesRemotion 集成https://codehike.org/blog/remotion高亮引擎https://github.com/code-hike/lighter