> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 快速开始

本页把一段 wikitext 渲染到页面上。管线、快照与入口的取舍见[工作原理](/zh/guide/concepts.md)。

## 环境要求

- React `>=18.2 <20`（peer dependency）。
- 构建或服务端运行需要 Node `>=18.18`。
- 支持 ESM 与 CJS；Vite 与 webpack 5 的消费者构建已有测试覆盖。
- 运行时不依赖 Wikimedia、字体 CDN 或外部 API。

## 安装

```bash
pnpm add react-wikitext@alpha
```

当前版本通过 alpha dist-tag 分发，安装命令需要显式指定通道；稳定版发布后可以直接使用 `pnpm add react-wikitext`。页面样式单独引入一次：

```ts
import "react-wikitext/styles.css";
```

::::note
npm 包只包含 `dist/`、`NOTICE` 与 `THIRD_PARTY_LICENSES`。从源码构建与本地调试流程见[贡献指南](/zh/project/contributing.md)。
::::

## 最小示例

根入口的 `Wikitext` 组件一次完成解析、准备与渲染。引入一次样式文件即可：

```tsx preview
import { Wikitext } from "react-wikitext";
import "react-wikitext/styles.css";

const source = `== 你好，wikitext ==
这是一段 '''wikitext'''，包含 [[内部链接|链接]] 和 ''斜体''。

* 第一项
* 第二项`;

export default function Article() {
  return <Wikitext source={source} lang="zh-CN" />;
}
```

`Wikitext` 渲染出的根节点是 `div.wtr-view`。`lang` 与 `dir` 会写入容器属性，用于排版与辅助技术。

::::warning
`Wikitext` 与 `WikitextView` 依赖 React Context，只能在客户端组件中运行。根入口与 `/view` 的产物顶部已经带有 `"use client"` 指令，在 Next.js App Router 中直接使用即可；服务端只调用 `/parse`、`/hast` 等无 React 入口，链路见[服务端准备 + 客户端渲染](/zh/guide/server-rendering.md)。
::::

## 你会看到什么

默认管线按下面的规则展示内容：

- 标题、段落、粗体、斜体、列表、定义列表、表格、代码块与参考文献正常渲染。
- 内部链接默认是**无法导航的文本**；需要地址时通过 `resolveLink` 返回。
- 外链使用源码中的安全 URL，并带 `target="_blank"` 与 `rel="nofollow noopener noreferrer"`。
- 模板、解析器函数与文件尚未求值时显示明确的占位，不推断内容。
- 图片默认只显示占位；只有 `resolveImage` 返回并通过校验的地址才会生成 `<img loading="lazy">`。
- 同页标题达到 4 个时自动生成目录；分类汇总到文末底栏。
- 未知结构降级为源码卡片，不会导致整页渲染失败。

逐项状态见[支持矩阵](/zh/guide/syntax-support.md)，细节见[渲染行为](/zh/guide/rendering.md)。

## 下一步

- [工作原理](/zh/guide/concepts.md)：为什么解析与准备要分开，什么时候用 `/view`。
- [基本用法](/zh/guide/usage.md)：显式管线、异步插件与组件覆盖。
- [链接与图片](/zh/guide/links-and-images.md)：接入站内路由与媒体服务。
- [服务端与框架](/zh/guide/server-rendering.md)：服务端准备、序列化与 hydration。
- [故障排查](/zh/guide/troubleshooting.md)：占位、报错与常见配置问题。
- [入口总览](/zh/api/index.md)：每个子路径导出的内容。