Parsoid
要約
Parsoidは、MediaWikiのウィキテキストとHTML/XML DOMを双方向で変換するランタイムパーサーです。RDFaをサポートし、ウィキテキストの構文解析とHTMLへの変換、およびその逆の処理を行います。VisualEditorやコンテンツ翻訳などの機能で利用されており、情報損失を防ぎ、編集の精度を高めることを目的としています。現在はPHPで開発されており、MediaWiki 1.35以降にバンドルされています。
全文翻訳
Parsoid
言語:
- アフリカーンス語
- インドネシア語
- ミンナン語 (タイロー)
- カタルーニャ語
- セブアノ語
- チェコ語
- ドイツ語
- 英語
- スペイン語
- バスク語
- フランス語
- イド語
- インターリングア
- イタリア語
- ロンバルド語
- ハンガリー語
- オランダ語
- ポーランド語
- ポルトガル語
- ブラジルポルトガル語
- ルーマニア語
- ベトナム語
- トルコ語
- バシキール語
- ロシア語
- ヘブライ語
- アラビア語
- ペルシャ語
- クルド語
- ベンガル語
- グジャラート語
- タイ語
- 韓国語
- 中国語
- 日本語
- ミンナン語 / Bân-lâm-gí
Parsoid
双方向のランタイムウィキテキストパーサー。ウィキテキストとHTML/XML DOMをRDFa付きで相互に変換します。
| グループ: | コンテンツ変換チーム |
| 開始: | 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/リリース |
| 進捗状況: | Parsoid/デプロイメント |
[画像: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
使用方法
- Parsoid/リリース – Parsoidのリリース一覧
- Parsoid/API – Web API用
- MediaWiki DOM仕様 – APIから取得するHTMLを理解するためのもので、将来の保存フォーマットとして役立つように設計されています
- Parsoid/LanguageConverter – LanguageConverterのParsoid実装に関する注記
- 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の内部構造に関するドキュメント。
- PHP移植ノートとヘルプ募集タスク
- WikimediaクラスターでのParsoidデプロイメントアジェンダ(コードは通常、太平洋標準時午後1時〜1時30分の間に毎週月曜日と水曜日にデプロイされます)
- Parsoid/ラウンドトリップテスト – 実際のWikipediaコンテンツでウィキテキスト→HTML DOM→ウィキテキストのラウンドトリップをテストするために使用しているセットアップ。
- Parsoid/ビジュアル差分テスト – ParsoidのHTMLレンダリングとPHPパーサーのHTMLレンダリングを比較するためのビジュアル差分テストに関する情報。および、大量のビジュアル差分テストを実行するためのtestreduceセットアップ。
- Parsoid/制限事項 – Parsoidの制限事項。主に実際には問題にならない、人工的なテンプレートの(乱)用。プリプロセッサアップグレードノートと同様に拡張される可能性があります(更新が必要な場合があります)。
- Parsoid/参考文献 – 関連文献の参考文献
Parsoid開発者向けリンク
- デバッグのヒントについては、Parsoid/デバッグを参照してください。
- パッケージのアップグレードまたは追加をParsoidに
- これらの手順を参照して、Parsoidのパーサーテストコピーをコアと同期/非同期してください。
- Parsoidは、プログラムで呼び出すための限定的なライブラリインターフェースを持っています。
- Parsoidで拡張機能を動作させるための技術トーク
- 拡張機能をParsoidで動作させたい場合
- Parsoid HTML仕様のバージョン管理
- Parsoidの出力を変更したい場合
Parsoidデプロイ担当者向けリンク(Wikimediaクラスターへ)
- Parsoid/デプロイメント
- RTテストコミット(リグレッションと修正の確認に便利です)
- Parsoidのデプロイメント手順
- Kibanaダッシュボード
- wt2htmlメトリクスのGrafanaダッシュボード
- html2wtメトリクスのGrafanaダッシュボード
- eqiadのParsoidクラスターのPrometheus内訳
- codfwのParsoidクラスターのPrometheus内訳
- Jenkins Job Builderドキュメント(Jenkinsジョブの更新用)
歴史
元のアプリケーションは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でレンダリングするように設定するにはどうすればよいですか?
- Extension:ParserMigrationをインストールします。
- URLに
?useparsoid=1を追加します。
- ウィキ全体をParsoidでレンダリングするように設定するにはどうすればよいですか?
- Extension:ParserMigrationをインストールします。
$wgParserMigrationEnableParsoidArticlePages = true;を設定します。$wgParserMigrationEnableParsoidDiscussionTools = true;を設定します。
- どのWikimediaウィキがParsoidでレンダリングされていますか?
- リストはparsoidrendered.dblistにあります。2025年10月現在、約1000ウィキのうち650ウィキが該当します。ロールアウトは、すべてのウィキがParsoidを使用するまで継続されます。
関連項目
- API
- RESTBase – Parsoidによって翻訳されたページのHTMLのキャッシュ/保存APIプロキシ
- Parser 2011/Parser plan – 2011年の初期(現在は比較的古い)設計アイデアと問題点
- Special:PrefixIndex/Parsoid/ – このウィキのParsoid関連ページ
- Extension:ParsoidBatchAPI (アーカイブ済み)
- parsoid-jsapi – mwparserfromhell APIに似た、ウィキテキストの抽出と変換のための高レベルインターフェース。
- 代替パーサー
- Parsoid/パーサー統合
外部リンク
- ソースコード(GitHubミラー)
- JSドキュメント(Parsoidの旧バージョン)
- PHPドキュメント
- Wikimedia CommonsのParsoid
ヘルプが必要な場合、または質問/フィードバックがある場合は、#mediawiki-parsoidで接続するか、wikitext-lメーリングリストで連絡できます。それでも解決しない場合は、content-transform-team at the wikimedia.org ドメインにメールで連絡することもできます。