WikiParser-Node

Other Languages

• English

简介

WikiParser-Node 是一款由 Bhsd 开发的基于 Node.js 环境的离线维基文本语法解析器，可以解析几乎全部的维基语法并生成语法树（在线解析），还可以很方便地对语法树进行查询和修改，最后返回修改后的维基文本。

尽管 WikiParser-Node 并非以将维基文本完整转换为 HTML 为主要目标，但它在很多场合中能提供实用的 HTML 渲染能力。这里是一个使用这个库渲染的 HTML 示例页面列表，来源于 MediaWiki.org。

WikiParser-Node 已使用包含约 3,000 个测试用例的官方 MediaWiki PHP 解析器测试集进行了广泛的测试，这些测试用例涵盖了维基文本的各种边缘情况和特殊情况。测试结果可在这里查看。

为什么选择 WikiParser-Node

• 维基文本与语法树的双向转换：将维基文本解析为语法树，查询并修改节点后可以安全地写回有效的维基文本，适用于需要程序化编辑的机器人和自动化脚本。
• 面向 Node.js 的语言服务器协议（LSP）与校验能力：为 WikiLint 和 Wikitext LSP 等工具提供解析与诊断能力，便于集成到编辑器和 CI 流程中。
• 浏览器与编辑器集成：可与 CodeMirror、Monaco 等编辑器配合使用，并已集成到 MediaWiki 官方的 CodeMirror 扩展中。
• 大规模适用性：在消费级硬件上对英文维基百科数据库转储文件进行解析与校验的实际案例表明，处理百万级规模工作负载是可行的。
• 透明的质量信号：本仓库包含持续集成与 CodeQL 检查、公开的解析器测试报告以及覆盖率报告。

使用者

其他版本

WikiLint

提供了 CLI，但仅保留了解析和语法错误分析功能。虽然牺牲了语法树的修改能力，但换来了 2.4 倍的执行速度提升。这个版本为 Wikitext 语言服务器协议提供支持，可为 VS Code、Sublime Text 和 Helix 等编辑器提供多种语言服务。

可用的语法检查规则列表请见这里。

Browser-compatible

兼容浏览器的版本，可用于代码高亮或是搭配 CodeMirror 和 Monaco 等编辑器作为语言服务器协议（LSP）插件（使用实例展示）。自 1.45 版本起已集成到 MediaWiki 官方 CodeMirror 扩展中。

WikiParser-Template

一个轻量级版本，仅支持模板的解析和操作。这个版本适用于仅需要处理模板的使用场景，例如某些专注于模板操作的的机器人或网络工具（例如 GANReviewTool）。

安装方法

Node.js

请根据需要需要安装对应的版本（WikiParser-Node 或 WikiLint），如：

npm i wikiparser-node

或

npm i wikilint

可选依赖

你可以安装以下任意可选库来启用高级功能：

库	功能
mathoid-texvcjs	诊断和渲染 <math> 和 <chem> 扩展标签
stylelint	诊断 style 属性
vscode-css-languageservice	style 属性的 CSS 语言服务
vscode-html-languageservice	HTML 标签的语言服务
vscode-json-languageservice	<templatedata>、<mapframe> 和 <maplink> 标签的 JSON 语言服务
ajv + ajv-errors	渲染 <templatedata> 扩展标签时的 JSON Schema 验证
katex	渲染 <math> 和 <chem> 扩展标签
prismjs + prism-wiki	渲染 <syntaxhighlight> 扩展标签时的语法高亮

# 完整的语言服务特性（用于 `Parser.createLanguageService()`）
npm i mathoid-texvcjs stylelint vscode-css-languageservice vscode-html-languageservice vscode-json-languageservice

# 完整的 HTML 渲染特性（用于 `Parser.toHtml()`）
npm i ajv ajv-errors katex mathoid-texvcjs prismjs prism-wiki

浏览器

可以通过 CDN 下载代码，如：

<script src="https://github.com/bhsd-harry/wikiparser-node/raw/v1.45.0/cdn.jsdelivr.net/npm/wikiparser-node"></script>

或

<script src="https://github.com/bhsd-harry/wikiparser-node/raw/v1.45.0/unpkg.com/wikiparser-node/bundle/bundle-lsp.min.js"></script>

更多浏览器端可用的插件请查阅对应文档。

使用方法

CLI 使用方法

对于安装了 CodeMirror 扩展的 MediaWiki 站点，如不同语言版本的维基百科和其他由维基媒体基金会托管的站点，可以使用以下命令获取解析器配置：

npx getParserConfig <site> <script path> [user] [force]
# 例如：
npx getParserConfig frwiki https://fr.wikipedia.org/w user@example.net

生成的配置文件将保存在 config 目录下，然后就可以使用站点名称设置 Parser.config。

// 例如：
Parser.config = "frwiki";

API 使用方法

请查阅 Wiki。其中包含一些应用实例展示了如何使用这个库完成各种任务。

快速入门示例（TypeScript）

import Parser from "wikiparser-node";
import type {TranscludeToken} from "wikiparser-node";

Parser.config = "enwiki";
const root = Parser.parse("{{Infobox|name=Old}}\nText"),
    template = root.querySelector<TranscludeToken>("template#Template:Infobox");
template?.setValue("name", "New");
const wikitext = String(root);
assert.strictEqual(wikitext, "{{Infobox|name=New}}\nText");

性能

在一台个人的 MacBook Air 上对英文维基百科约 1900 万篇条目的数据库转储文件（*.xml.bz2）的一次完整扫描（解析和语法错误分析）需要约 5 小时。

WikiParser-Node 与 WikiLint 的性能比较

版本	条目平均用时	条目最大用时
WikiParser-Node	3.6ms	2.8s
WikiLint	1.5ms	0.75s

最佳适用场景

• MediaWiki 机器人工作流，尤其是需要可靠的语法树操作和编辑操作时。
• Node.js 大规模维基文本校验和格式化工作流。
• 基于语言服务器协议（LSP）的语言工具。
• 浏览器端用于全站小工具、用户脚本和编辑器插件中的维基文本解析与编辑辅助功能。

已知问题

请参阅英语版本。