【GitHub】Code Hike 深度解析：用 Markdown + React 构建下一代技术内容网站

如果 Markdown 和 React 生了个孩子，那它一定叫 Code Hike。

一、什么是 Code Hike？

Code Hike 是一个开源库，它的核心使命极其清晰：在 Markdown 的写作体验和 React 的表现力之间架一座桥。

当你写技术博客、文档、教程的时候，通常会面临一个两难选择：

• 纯 Markdown：写得爽，但排版受限，代码块千篇一律，交互为零。
• 纯 React：表现力无限，但写内容要写 JSX，内容与样式耦合，维护噩梦。

Code Hike 的思路是——小孩子才做选择，成年人全都要。它通过在 Markdown 中注入轻量级的"装饰语法"，将内容结构化，然后在 React 组件层自由渲染。

npx create-next-app -e https://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 type="warning">
注意：以下内容需要 Node.js 18+
</Callout>

<CodeBlock title="hello.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 后的文字作为 title
• 图片： → 提取 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 自研高亮引擎：Lighter

Code Hike 没有使用 Shiki 或 Prism，而是自己写了一个高亮引擎——lighter。

为什么造轮子？核心原因是 Code Hike 的注解系统需要对 token 级别的精细控制。Shiki 的 transformer 机制操作的是 AST，而 Code Hike 的注解是 React 组件——粒度不同、理念不同。

内置 22 种主题：

dark-plus github-dark github-light dracula monokai nord one-dark-pro solarized-dark solarized-light min-dark min-light material-* 系列等。

还支持 CSS 变量驱动的明暗主题（github-from-css、material-from-css）和自定义主题（可通过 Theme Editor 在线编辑）。

支持 211 种语言：从 Assembly 到 Zig，从 GraphQL 到文言文，覆盖面相当广。

4.2 注解系统（Annotations）：在代码里"画重点"

这是 Code Hike 最具差异化的功能。你可以通过代码注释给代码块添加注解，然后用 React 组件来渲染注解效果。

基本语法：

// !name(起始行:结束行) query参数
// !name[起始列:结束列] query参数

两种注解类型：

4.2.1 示例：高亮标记

// !mark(2:3)
function calculate(input) {
const result = process(input) // ← 这两行被标记
return result * 2 // ←
}

4.2.2 示例：正则匹配

不用手动数行号列号，直接用正则：

// !border[/ipsum/g] orange
const lorem = ipsum == null ? ipsum : 1
dolor = lorem – sit(dolor)

所有匹配 ipsum 的 token 都会被打上橙色边框。

4.2.3 示例：start/end 标记

const lorem = ipsum == null ? 0 : 1
// !highlight(start)
dolor = lorem – sit(dolor)
let amet = lorem ? 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 className="bg-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 可以自定义的渲染层面：

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 的文档提供了大量可直接复用的注解实现：

4.6 代码导入指令

直接从文件导入代码，避免复制粘贴：

```js
!from ./src/hello.js
```

代码块内容会被 ./src/hello.js 的文件内容替换，从此告别"示例代码与源码不同步"的痛点。

五、安装与配置

5.1 快速开始

npx create-next-app -e https://github.com/code-hike/v1-starter

5.2 手动安装

npm install codehike

在 next.config.mjs 中配置 MDX 插件：

import { remarkCodeHike, recmaCodeHike } from "codehike/mdx"

/** @type {import('codehike/mdx').CodeHikeConfig} */
const chConfig = {
components: { code: "Code" },
// 如果不支持 RSC，在此处指定主题：
// syntaxHighlighting: {
// theme: "github-dark",
// },
}

const mdxOptions = {
remarkPlugins: [[remarkCodeHike, chConfig]],
recmaPlugins: [[recmaCodeHike, chConfig]],
jsx: true,
}

5.3 框架兼容性

六、Scrollycoding：杀手级布局

Scrollycoding 是 Code Hike 最具代表性的布局模式——滚动讲解与代码同步，广泛用于技术教程和代码 walkthrough。

基本结构：右侧固定代码块，左侧内容随滚动切换。每滚动到一个 Section，代码高亮/注解也随之切换。

<Scrollycoding>

## !!steps 初始化
项目初始化的第一步…

## !!steps 路由
接下来配置路由…

## !!steps 数据层
然后设置数据获取…

</Scrollycoding>

结合 Block 系统 + 代码注解，Scrollycoding 可以做到：

• 滚动到某一步时，自动高亮对应代码行
• 代码中嵌入 callout 气球注释
• 折叠非相关的代码区域
• 自适应移动端（stack 布局切换）

正是这种交互让 Code Hike 从一众 Markdown 工具中脱颖而出——它不是"更好看的代码块"，而是把文档变成了一个交互式应用。

七、竞品对比

Code Hike 的真正优势不在于"我能做"，而在于"我做得极其顺手"。Shiki 也能做代码注解——但要写大量 transformer 代码；MDX 也能做结构化内容——但要手动组织组件树。Code Hike 把这些模式做了标准化封装，让它们成为一种"理所当然"的使用方式。

八、生态与应用场景

8.1 谁在用 / 适合谁

8.2 成功案例

• Shopify API Reference 克隆版：用 Code Hike 重现了 Shopify 精美的 API 文档 UI
• SwiftUI Tutorials 克隆版：复刻了 Apple 的 SwiftUI 交互式教程体验
• Code Hike 自身文档站：codehike.org 全站用 Code Hike 构建

8.3 赞助商矩阵

Meta（Facebook 开源赞助）、Vercel（部署平台）、Speakeasy（API 工具）、ui.dev（前端培训）——这说明 Code Hike 不仅技术过硬，商业生态也在稳步成型。

九、总结与思考

为什么 Code Hike 值得关注？

踩坑点与局限

• 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/examples
• Remotion 集成：https://codehike.org/blog/remotion
• 高亮引擎：https://github.com/code-hike/lighter