Jump to content

Parsoid

问题追踪器： #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 95% complete.
Languages:
于Phabricator查看
任务T409283
开放任务；尚未认领
Like all of MediaWiki, Parsoid is not yet compatible with PHP 8.4+. Use PHP 8.3 or avoid upgrading to 1.45 until this problem is fixed.
维基媒体基金会的项目
Parsoid
双向运行时维基文本解析器。 使用RDFa在wikitext和HTML/XML DOM之间相互转换。
群組： Content Transform Team
开始： 2011-10
成员： Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
积压工作： #parsoid
主导： C.Scott Ananian
管理： Sérgio Lopes
更新： Parsoid/Releases
进展： Parsoid/Deployments
对Parsoid HTML5 + RDFa wiki运行时的示意圖

若需了解使用JavaScript（Node.js）编写的Parsoid旧版本，请参阅Parsoid/JS 。

Parsoid 是随 MediaWiki（自 1.35 版本起）一同提供的一个 PHP 库，用于在 wikitext 和 HTML 之间进行相互转换。 该项目自2012年起开始开发，最初使用JavaScript编写，旨在支持VisualEditor 。 其最终目标是使用Parsoid完全取代 MediaWiki当前的原生解析器 。

旧版解析器在MediaWiki 1.43（LTS）版本中仍受支持，但在下一个LTS版本中很可能不再获得支持。

技术细节

Parsoid是一个应用程序，可以在MediaWiki的wiki文本语法和等效的HTML/RDFa文档模型之间来回转换，并增强了对自动处理和丰富编辑的支持。

自2012年以来，它一直由维基媒体基金会的一个团队开发。 它目前被VisualEditor 、内容翻译 和其他应用广泛使用。

Parsoid旨在提供完美的来回转换，即避免信息丢失并防止“脏差异”。

在维基媒体wiki上，对于一些应用程序，Parsoid目前被代理在RESTBase 之后，它存储了由Parsoid翻译的HTML。 预计RESTBase最终将被替换，与MediaWiki的缓存更紧密地集成在一起。

有关整个项目的更多信息，请参阅2013年3月的这篇博文。 要了解正在使用的HTML模型，请参阅MediaWiki DOM 规范。

Parsoid最初是作为Web服务构建的，用JavaScript编写，利用Node.js。 2019年2月的技术讲座（幻灯片）和博客文章描述了将其移植到PHP的过程。 Parsoid扩展API目前正在积极开发中；2020年8月的技术讲座描述了这项工作。

Github仓库： https://github.com/wikimedia/parsoid

用法

安装

此扩展随附于MediaWiki 1.35及更新版本，因此您無需下載它。 但其余的配置的指示仍须依循執行。

Parsoid has been included in MediaWiki since version 1.35. 无需配置即可启用。

Parsoid 提供一个内部 REST API，该 API 过去由 RESTBase 使用，并且在 WMF 内部集群之外无法访问。 可视化编辑器或核心阅读视图已不再需要此 API，该内部 API 正在被弃用，并计划在 MW 1.43 版本中移除。

名义上，Parsoid 是 MediaWiki 核心所使用的一个 Composer 库。 如果您因某种原因仍需使用该内部 API，可以通过将以下内容添加到 LocalSettings.php 的方式，将 Parsoid 明确地加载为“扩展”： 

wfLoadExtension( 'Parsoid', "$IP/vendor/wikimedia/parsoid/extension.json" );

强烈建议仍使用内部Parsoid API接口的第三方用户迁移至核心REST HTML页面端点，该端点可提供同等功能。

开发

开发地址在Parsoid Git repository。 代码审查地址在Gerrit。 请参阅Gerrit/教程为自己创建一个帐户。

如果您使用虚拟机的MediaWiki-Vagrant 开发环境，您只需将角色visualeditor添加到其中，它就会与Extension:VisualEditor 一起设置一个工作的Parsoid。

以下说明适用于 MediaWiki 1.35 及更高版本。 如果您运行的是用JavaScript编写的旧版本的Parsoid，并且用于MW 1.34及更早版本，请查阅Parsoid/JS 。

链接Parsoid的开发人员签出

在标准的MediaWiki安装中，Parsoid作为一个composer库wikimedia/parsoid在MediaWiki中包含。

出于开发目的，您通常希望使用Parsoid的git签出，而不是MediaWiki核心中捆绑的版本作为composer库。 以下添加到LocalSettings.php 的行允许使用Parsoid的git签出（可选），以wfLoadExtension 加载Parsoid REST API（而不是使用可视化编辑器中捆绑的版本），并手动执行通常由可视化编辑器完成的Parsoid配置： 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # 捆绑包副本
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// 写给开发人员：确保Parsoid从$parsoidInstallDir执行，
// （不是默认包含在mediawiki-core中的版本）
// 必须在wfLoadExtension()*之前*执行
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Only intercept Parsoid namespace classes
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // 在MW 1.39中添加了AutoLoader::registerNamespaces
    AutoLoader::registerNamespaces( [
        // 与下文的“autoload”子句保持同步
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

wfLoadExtension( 'Parsoid', "$parsoidInstallDir/extension.json" );

# 手动配置Parsoid
$wgVisualEditorParsoidAutoConfig = false;
$wgParsoidSettings = [
    'useSelser' => true,
    'rtTestMode' => false,
    'linting' => false,
];
$wgVirtualRestConfig['modules']['parsoid'] = [
    // Parsoid实例的URL。
    // 如果Parsoid未在本地运行，则应更改$wgServer以匹配非本地主机 
    // 在macOS中使用Docker时，可能需要将$wgServer替换为http://host.docker.internal:8080
    // 在linux中使用Docker时，可能需要将$wgServer替换为http://172.17.0.1:8080
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // Parsoid“域名”，见下文（可选，很少需要）
    // 'domain' => 'localhost',
];
unset( $parsoidInstallDir );

对于大多数可视化编辑器用户来说，这些行不是必需的，他们可以使用VisualEditor的自动配置功能以及MediaWiki中捆绑的Parsoid代码，但对于大多数开发人员来说，这些行是必需的。

如果您使用Nginx为MediaWiki提供服务，则还需要在服务器块中添加类似这样的东西（假设您的MediaWiki设置的文件位于/w/）： 

location /w/rest.php/ {
    try_files $uri $uri/ /w/rest.php?$query_string;
}

如果你使用 Docker 运行 MediaWiki，并将本地的 Parsoid 仓库链接到 MediaWiki，则需要在 MediaWiki 项目的 docker-compose.override.yml 文件中为 Docker 容器映射额外的卷。 最简单的方法是在 MediaWiki 项目中创建 docker-compose.override.yml 文件，并将以下代码放入其中（请根据实际路径进行修改）。 如果已存在 docker-compose.override.yml 文件，请相应地对其进行修改。 

services:
  mediawiki:
    volumes:
      - ./:/var/www/html/w:cached
      - /my/path/to/git/checkout/of/Parsoid:/my/path/to/git/checkout/of/Parsoid

要测试正确的配置，请访问{$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page，其中$domain是$wgCanonicalServer中的主机名。 （请注意，生产WMF服务器不会向外部网络公开Parsoid REST API。

运行测试

要运行所有解析器测试和mocha测试，请执行以下操作： 

$ composer test

解析器测试现在有很多选项，可以使用php bin/parserTests.php --help命令列出。

如果您的环境变量MW_INSTALL_DIR指向已配置的MediaWiki安装，则可以使用以下命令运行一些额外的测试： 

$ composer phan-integrated

转换简单的wikitext

您可以使用bin/目录中的parse.php脚本从命令行转换简单的wikitext片段： 

$ echo '[[Foo]]' | php bin/parse.php

解析脚本有很多选项。 php bin/parse.php --help命令能为您提供相关信息。

调试Parsoid（对于开发人员）

请参阅Parsoid/Debugging 了解调试提示。

持续集成

截至2021年10月

Parsoid始终可以作为库使用，因为它是MediaWiki核心的composer依赖项。但有两个部分未启用：

  • Parsoid ServiceWiring
  • Parsoid的外部REST api

如果测试运行程序Quibble检测到mediawiki/services/parsoid.git已被克隆为构建的一部分，它将启用它。 在此情况下，它：

  • 为Wikimedia\Parsoid将自动加载器指向克隆的代码（有效地替换了composer安装的版本）
  • 载入扩展 wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

从1.38开始，应在MediaWiki中启用ServiceWiring。

理论上，REST API永远不会被合并到MediaWiki中：a) 它从未在生产环境中公开，只是一个由即将弃用的RESTBase使用的内部API；b) 它从未经过安全审计；c) 它与企业版MediaWiki API功能重复。 解决方案是让VisualEditor通过VisualEditor Action API直接调用Parsoid，从而省去经由REST API的往返环节。

因此，加载该扩展是一种变通手段，它允许使用尚不稳定的接口——这些接口我们目前并不希望用户真正使用。

因此，在大多数情况下，不应将Parsoid作为持续集成的依赖项添加。截至2021年10月，唯一的例外是Disambiguator MediaWiki扩展。

将Parsoid作为扩展加载使我们能够针对mediawiki/services/parsoid.git（如Quibble、apitesting）运行MediaWiki集成测试任务，确保Parsoid与MediaWiki协同工作。

即使未克隆代码库，扩展程序仍可能借助Parsoid编写测试。 由于它是MediaWiki核心的composer依赖项，MediaWiki\Parsoid命名空间可用，但服务连接部分不可用（它在Parsoid代码库中是extension/src，并以\MWParsoid命名空间的形式暴露）。 如果已加载Parsoid（在MediaWiki 1.38中应为默认情况），则ParsoidTestFileSuite.php代码仅会运行解析器测试。

CI环境下，Parsoid针对mediawiki的最新版本进行测试，而mediawiki则通过composer依赖项进行测试。 若出现破坏性变更，Parsoid的改动会先合并（这会破坏其自身CI但不会影响MediaWiki），待Parsoid更新后再调整MediaWiki。 因此这是一个单向的改变。

发布版本

对于MediaWiki的发布版本，我们将Parsoid的ServiceWiring集成到了VisualEditor中，这样VisualEditor无需额外配置（除了wfLoadExtension( 'VisualEditor' )）即可运行。 发布版本还启用了REST API并连接了所有组件，使Parsoid能够开箱即用。 这是通过将一小段Parsoid代码复制到VisualEditor中实现的，该代码并未包含在VisualEditor的主分支里，因为一旦Parsoid更新，这部分代码就会过时。 因此，相关代码实际上是在两个地方分别维护的。

技术文档

Parsoid开发者的相关链接

对于Parsoid部署者的链接（到维基媒体集群）

历史

原始应用程序是用JavaScript编写的（借助Node.js），并自2012年12月起在维基媒体集群上运行。 在2019年，Parsoid移植到PHP，维基媒体集群于2019年12月以PHP版本取代了JS版本。 Parsoid已经集成到MediaWiki核心，其目标是最终取代MediaWiki当前的本地解析器。 In early 2024, Parsoid began to be used on some production wikis of the Wikimedia Foundation as the default parser for read views.

Parsoid (PHP版本) 已经原生捆绑到2020年9月发布的MediaWiki版本1.35或更高版本中。 对于非维基媒体安装，Parsoid/JS在2021年9月MediaWiki 1.31（LTS）生命周期结束之前一直受支持。

FAQ

  • How do I see if a page was rendered with Parsoid?
    • The footer will say "Page was rendered with Parsoid".
  • How do I set a page to temporarily render with Parsoid?
  • How do I get an entire wiki to render with Parsoid?
    • Install Extension:ParserMigration
    • Set $wgParserMigrationEnableParsoidArticlePages = true;
    • Set $wgParserMigrationEnableParsoidDiscussionTools = true;
  • Which Wikimedia wikis render with Parsoid?
    • The list is at parsoidrendered.dblist. As of August 2025, it is approximately 250 of the 1000 wikis. Rollout will continue until all wikis are using Parsoid.

参见

外部链接

联络

如果您需要帮助或有问题/反馈，您可以在#mediawiki-parsoid 在线或wikitext-l邮箱列表与我们联系。 如果所有这些方式都失败了，您也可以通过电子邮件与我们联系，地址为wikimedia.org域名的content-transform-team。

Retrieved from "https://www.mediawiki.org/w/index.php?title=Parsoid/zh&oldid=8142589"