HN 日本語サマリー

← 一覧へ戻る
オープンソース

Parsoid

Parsoid (mediawiki.org)

19 pointsby debo_1 コメント

要約

Parsoidは、MediaWikiのウィキテキストとHTML/XML DOMを双方向で変換するランタイムパーサーです。RDFaをサポートし、ウィキテキストの構文解析とHTMLへの変換、およびその逆の処理を行います。VisualEditorやコンテンツ翻訳などの機能で利用されており、情報損失を防ぎ、編集の精度を高めることを目的としています。現在はPHPで開発されており、MediaWiki 1.35以降にバンドルされています。

全文翻訳

Parsoid

言語:

Wikimedia Foundationプロジェクト

Parsoid

[画像:Parsoidのワードロゴ]

双方向のランタイムウィキテキストパーサー。ウィキテキストとHTML/XML DOMをRDFa付きで相互に変換します。

[画像:ParsoidのHTML-RDFaコンテンツモデル]

Parsoid HTML5 + RDFa ウィキランタイムの図

2020年までJavaScript (Node.js) で書かれていたParsoidの旧バージョンについては、Parsoid/JSを参照してください。

Parsoidは、ウィキテキストとHTMLの間で相互に変換するために使用されるPHPライブラリです。2012年から開発が進められており、当初はVisualEditorをサポートするためにJavaScriptで書かれていました。MediaWikiバージョン1.35以降バンドルされています。MediaWiki 1.47では、パーサー統合として知られるプロジェクトで、現在のネイティブパーサーを置き換える形で、MediaWikiのデフォルトパーサーになる予定です。

技術詳細

Parsoidは、MediaWikiのウィキテキスト構文と、自動処理およびリッチ編集のための強化されたサポートを備えた同等のHTML/RDFaドキュメントモデルの間で双方向に変換できるアプリケーションです。

2012年からWikimedia Foundationのチームによって開発が進められています。現在、VisualEditor、コンテンツ翻訳、およびその他のアプリケーションで広く利用されています。

Parsoidは、情報損失を回避し、「ダーティ差分」を防ぐために、完璧な双方向変換を提供することを目的としています。

Wikimediaのウィキでは、いくつかのアプリケーションで、Parsoidは現在、Parsoidによって翻訳されたHTMLを保存するRESTBaseの背後でプロキシされています。RESTBaseは最終的に、MediaWikiにより密接に統合されたキャッシュに置き換えられる予定です。

プロジェクト全体については、2013年3月のこのブログ記事を参照してください。使用されているHTMLモデルについては、MediaWiki DOM仕様を参照してください。

Parsoidは当初、Webサービスとして構造化され、Node.jsを使用したJavaScriptで記述されていました。2019年2月の技術トーク(スライド)およびブログ記事では、PHPへの移植のプロセスについて説明しています。Parsoid拡張APIは現在活発に開発されており、2020年8月の技術トークではこの作業について説明しています。

GitHubリポジトリ: https://github.com/wikimedia/parsoid

使用方法

インストール

この拡張機能はMediaWiki 1.35以降に含まれているため、ダウンロードする必要はありません。ただし、残りの設定手順は引き続き実行する必要があります。

Parsoidはバージョン1.35以降MediaWikiに含まれています。有効にするための設定は不要です。

Parsoidは内部REST APIをエクスポートしますが、これは歴史的にRESTBaseによって使用され、WMF内部クラスター外からはアクセスできませんでした。これはVisual Editorやコアの読み取りビューにはもはや必要ではなく、内部APIは非推奨となり、MW 1.43での削除が予定されています。

Parsoidは名目上、mediawikiコアによって使用されるコンポーザーライブラリです。何らかの理由で内部APIが必要な場合は、LocalSettings.phpに以下を追加してParsoidを「拡張機能として」明示的にロードできます。

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

内部Parsoid APIの残りのサードパーティユーザーは、同等の機能を提供するコアREST HTMLページエンドポイントへの移行が強く推奨されます。

開発

開発はParsoid Gitリポジトリで行われます。コードレビューはGerritで行われます。アカウントを設定するには、Gerrit/入門を参照してください。

仮想マシンを使用したMediaWiki-Vagrant開発環境を使用している場合、単にvisualeditorロールを追加するだけで、Extension:VisualEditorと共に動作するParsoidがセットアップされます。

以下の手順はMediaWiki 1.35以降を対象としています。JavaScriptで書かれたParsoidの古いバージョン(MW 1.34以前で使用)を実行している場合は、Parsoid/JSを確認してください。

Parsoidの開発者チェックアウトのリンク

標準的なMediaWikiインストールでは、ParsoidはMediaWikiからコンポーザーライブラリwikimedia/parsoidとして含まれています。

開発目的では、通常、コンポーザーライブラリとしてMediaWikiコアに含まれているバージョンではなく、Parsoidのgitチェックアウトを使用したいでしょう。LocalSettings.phpに以下の行を追加すると、gitチェックアウトのParsoid(オプション)を使用でき、wfLoadExtensionでParsoid REST APIをロードし(VisualEditorにバンドルされているバージョンではなく)、通常VisualEditorによって行われる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 ) {
        // Parsoid名前空間クラスのみをインターセプトします
        if ( preg_match( '/(MW|Wikimedia\\)Parsoid\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // AutoLoader::registerNamespaces は MW 1.39 で追加されました
    AutoLoader::registerNamespaces( [
        // $parsoidInstallDir/composer.json の "autoload" 句と同期させてください
        'Wikimedia\Parsoid\' => "$parsoidInstallDir/src/",
    ] );
}

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

mediawiki-core の単体テストは標準のオートローダー(またはLocalSettings.php)を使用しないため、ローカルのParsoidを認識しません。コア単体テストをローカルのParsoidチェックアウトに対して実行する際にLocalSettings.phpとオートローダーの使用を強制するには、環境変数MEDIAWIKI_HAS_INTEGRATION_TESTS=1を設定してください。

LocalSettings.phpの行は、MediaWikiに含まれるバンドルされたParsoidコードとVisualEditorの自動設定を使用できるVisualEditorのほとんどのユーザーには必要ありませんが、Parsoidを開発しているほとんどの開発者には必要になります。

NginxでMediaWikiを提供している場合、サーバーブロックに以下のようなものを追加する必要があるかもしれません(MediaWikiのセットアップが/w/にファイルを配置していると仮定します)。

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

Dockerを使用してMediaWikiを実行しており、ローカルのParsoidリポジトリをMediaWikiにリンクしている場合、docker-compose.override.ymlファイルにさらにボリュームをマッピングする必要があります。最も簡単な方法は、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
簡単なウィキテキストの変換

bin/ディレクトリのparse.phpスクリプトを使用して、コマンドラインから簡単なウィキテキストスニペットを変換できます:

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

parseスクリプトには多くのオプションがあります。php bin/parse.php --helpで情報が得られます。

Parsoidのデバッグ(開発者向け)

デバッグのヒントについては、Parsoid/デバッグを参照してください。

継続的インテグレーション

ParsoidはMediaWikiコアのコンポーザー依存関係であるため、常にライブラリとして利用可能です。ただし、2つのコンポーネントは有効になっていません:

  • Parsoid ServiceWiring
  • Parsoidの外部REST API

テストランナーQuibbleは、mediawiki/services/parsoid.gitがビルドの一部としてクローンされたことを検出すると、それを有効にします。その場合、それは:

  • Wikimedia Parsoidのオートローダーをクローンされたコードにポイントします(コンポーザーによってインストールされたバージョンを実質的に置き換えます)。
  • 拡張機能wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );をロードします。

ServiceWiringは1.38以降のMediaWikiで有効になる予定です。

REST APIは理論的にはMediaWikiにマージされることはありません:a) 本番環境で公開されたことはなく、廃止されるRESTBaseによって使用される内部APIです。b) セキュリティ監査を受けたことがありません。c) エンタープライズMediaWiki APIと冗長です。解決策は、VisualEditorがVisualEditor Action APIを介して直接Parsoidを呼び出すことになり、REST APIを介した往復が節約されます。

したがって、拡張機能のロードは、変更される可能性のあるインターフェースを使用可能にするハックであり、まだ使用してほしくないものです。

ほとんどの目的では、ParsoidはCI依存関係として追加されるべきではありません。2021年10月現在、唯一の例外はDisambiguator MediaWiki拡張機能です。

拡張機能としてParsoidをロードすると、mediawiki/services/parsoid.git(Quibble、apitestingなど)に対してMediaWiki統合テストジョブを実行でき、ParsoidとMediaWikiが連携して動作することを確認できます。

拡張機能は、リポジトリがクローンされていない場合でも、Parsoidでテストを記述できる可能性があります。MediaWikiコアのコンポーザー依存関係であるため、MediaWiki Parsoid名前空間は利用可能ですが、サービス配線部分は利用できません(Parsoidリポジトリのextension/srcであり、 MWParsoid名前空間として公開されています)。ParsoidTestFileSuite.phpコードは、Parsoidがロードされている場合(MediaWiki 1.38ではデフォルトであるはず)にのみパーサーテストを実行します。

CIでは、ParsoidはMediaWikiの最新版に対してテストされ、一方MediaWikiはComposer依存関係でテストされます。破壊的な変更が発生した場合、Parsoidの変更が最初にマージされ(CIは壊れますがMediaWikiは壊れません)、Parsoidが更新されるとMediaWikiが調整されます。したがって、これは一方通行の変更です。

リリースビルド

MediaWikiリリースビルドでは、VisualEditorが追加設定なしで動作するように(wfLoadExtension( 'VisualEditor' )を除く)、Parsoid ServiceWiringをVisualEditorに統合しています。リリースビルドでは、REST APIも有効になり、Parsoidがすぐに動作するようにすべてがフックアップされます。これは、VisualEditorのマスターブランチにはないParsoidコードの一部をVisualEditorにコピーすることによって行われます。なぜなら、Parsoidが更新されるとすぐに古くなるからです。代わりに、コードは2つの場所に維持されています。

技術文書

Parsoid開発者向けリンク
Parsoidデプロイ担当者向けリンク(Wikimediaクラスターへ)

歴史

元のアプリケーションはJavaScript(Node.jsを使用)で書かれ、2012年12月にWikimediaクラスターで稼働を開始しました。2019年にParsoidはPHPに移植され、2019年12月にPHP版がWikimediaクラスターのJS版に置き換わりました。ParsoidはMediaWikiコアへの統合が進められており、最終的にはMediaWikiの現在のネイティブパーサーを置き換えることを目指しています。2024年初頭、ParsoidはWikimedia Foundationの一部の本番ウィキで、読み取りビューのデフォルトパーサーとして使用され始めました。それらは本番設定リストで見ることができます。

Parsoid(PHP版)は、2020年9月にリリースされたバージョン1.35以降、MediaWikiにネイティブバンドルされています。Wikimedia以外のインストールでは、Parsoid/JSはMediaWiki 1.31 (LTS) のサポート終了(2021年9月)までサポートされていました。

FAQ

  • ページがParsoidでレンダリングされたかどうかを確認するにはどうすればよいですか?
    • フッターに「ページはParsoidでレンダリングされました」と表示されます。
  • ページを一時的にParsoidでレンダリングするように設定するにはどうすればよいですか?
  • ウィキ全体をParsoidでレンダリングするように設定するにはどうすればよいですか?
    • Extension:ParserMigrationをインストールします。
    • $wgParserMigrationEnableParsoidArticlePages = true;を設定します。
    • $wgParserMigrationEnableParsoidDiscussionTools = true;を設定します。
  • どのWikimediaウィキがParsoidでレンダリングされていますか?
    • リストはparsoidrendered.dblistにあります。2025年10月現在、約1000ウィキのうち650ウィキが該当します。ロールアウトは、すべてのウィキがParsoidを使用するまで継続されます。

関連項目

外部リンク

ヘルプが必要な場合、または質問/フィードバックがある場合は、#mediawiki-parsoidで接続するか、wikitext-lメーリングリストで連絡できます。それでも解決しない場合は、content-transform-team at the wikimedia.org ドメインにメールで連絡することもできます。