Jump to content

Parsoid

Issue tracker: #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 100% complete.
Languages:
Wikimedia Foundation projecten
Parsoid
Een tweerichting runtime parser voor wikitext. Converteert heen en weer tussen wikitext en HTML/XML DOM met RDFa.
Groep: Content Transform Team
Start: 2011-10
Teamleden: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
Backlog: #parsoid
Hoofd: C.Scott Ananian
Management: Sérgio Lopes
Updates: Parsoid/Releases
Voortgang: Parsoid/Deployments
Een diagram van Parsoid HTML5 + RDFa wiki runtime
Voor de oude versie van Parsoid (tot 2020) geschreven in JavaScript (Node.js), zie Parsoid/JS .

Parsoid is een PHP-bibliotheek die wordt gebruikt om heen en weer te converteren tussen wikitext en HTML. Het is sinds 2012 in ontwikkeling, oorspronkelijk geschreven in JavaScript en gebouwd om de VisualEditor te ondersteunen. Het wordt sinds versie 1.35 meegeleverd met MediaWiki. In MediaWiki 1.47 is het de bedoeling dat Parsoid de standaardparser van MediaWiki wordt, ter vervanging van de huidige interne parser , in een project dat bekend staat als parser unification .

Technische details

Parsoid is een applicatie die heen en weer kan vertalen tussen MediaWiki's wikitext-syntaxis en een equivalent HTML/RDFa-documentmodel met verbeterde ondersteuning voor geautomatiseerde verwerking en rijke bewerking.

Het is sinds 2012 in ontwikkeling door een team bij de Wikimedia Foundation. Het wordt nu uitgebreid gebruikt door VisualEditor , Content Translation en andere applicaties.

Parsoid is bedoeld om een foutloze conversie te bieden, d.w.z. om informatieverlies te voorkomen en ook "vuil verschil" te voorkomen.

Op Wikimedia wiki's, voor verschillende toepassingen, zit Parsoid nu op een proxy achter RESTBase , die de HTML opslaat die door Parsoid is vertaald. Er wordt verwacht dat RESTBase uiteindelijk zal worden vervangen door een cache die nauwer geïntegreerd is met MediaWiki.

Voor meer informatie over het algehele project, zie deze blogpost van maart 2013. Om meer te lezen over het gebruikte HTML-model, zie MediaWiki DOM specificatie.

Parsoid is oorspronkelijk gestructureerd als een webservice en geschreven in JavaScript, waarbij Node.js wordt gebruikt. Een tech talk uit februari 2019 (dia's) en blogpost beschrijft het proces van het porteren naar PHP. De Parsoid-extensie-API is nog actief in ontwikkeling; een tech talk uit augustus 2020 beschrijft dit werk.

GitHub Repository: https://github.com/wikimedia/parsoid

Gebruik

Installatie

Deze extensie wordt meegeleverd met MediaWiki 1.35 en nieuwer. De overige configuratie-instructies moeten nog altijd worden gevolgd.

Parsoid is sinds versie 1.35 opgenomen in MediaWiki. Er is geen configuratie nodig om het in te schakelen.

Parsoid exporteert een interne REST-API die historisch door RESTBase werd gebruikt en niet toegankelijk was buiten het interne WMF-cluster. Dit is niet langer nodig voor VisualEditor of kernlees-weergaven, en de interne API wordt ontraden en is gepland voor verwijdering in MediaWiki 1.43.

Parsoid is een composer bibliotheek die wordt gebruikt door de core Mediawiki. Als u om een of andere reden nog steeds de interne API nodig hebt, kunt u Parsoid expliciet "als extensie" laden door het volgende toe te voegen aan LocalSettings.php: 

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

Alle resterende gebruikers van de interne Parsoid API worden sterk aangemoedigd om te migreren naar het kern-REST HTML-page-endpunt dat gelijkwaardige functionaliteit biedt.

Ontwikkeling

De ontwikkeling gebeurt in de Parsoid Git repository. Code beoordeling vindt plaats in Gerrit. Zie deze pagina om een account voor uzelf aan te maken.

Als u de ontwikkelomgeving van MediaWiki-Vagrant/nl met een virtuele machine gebruikt, kunt u er de rol visualeditor aan toevoegen en dan zet hij een werkende Parsoid op samen met Extension:VisualEditor .

De onderstaande instructies zijn voor vanaf MediaWiki 1.35. Controleer Parsoid/JS als u de oude versie van Parsoid gebruikt, deze was in gebruik voor MediaWiki 1.34 en ouder.

Koppelen van een ontwikkelaarscheckout van Parsoid

In een standaard MediaWiki-installatie wordt Parsoid opgenomen in MediaWiki als bibliotheek via composer, wikimedia/parsoid.

Voor ontwikkelingsdoeleinden wilt u meestal een git-checkout van Parsoid gebruiken, en niet de versie die in MediaWiki core wordt gebundeld als een bibliotheek. Het toevoegen van de volgende regels aan LocalSettings.php maken het mogelijk om een git-checkout van Parsoid te gebruiken (optioneel), de Parsoid REST API met wfLoadExtension te laden (in plaats van de in VisualEditor gebundelde versie te gebruiken) en de Parsoide-configuratie handmatig uit te voeren die meestal door VisualEditor wordt uitgevoerd: 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # gebundelde kopie
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// Voor ontwikkelaars: zorg ervoor dat Parsoid vanaf $parsoidInstallDir wordt uitgevoerd.
// (niet de versie die standaard in mediawiki-core zit)
// Moet staan *voor* wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Alleen onderscheppen van 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 );
    // AutoLoader::registerNamespaces is toegevoegd in MediaWiki 1.39
    AutoLoader::registerNamespaces( [
        // Houd dit in synchronisatie met de clausule "autoload" in
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

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

Deze regels zijn niet nodig voor de meeste gebruikers van VisualEditor, die de auto-configuratie van VisualEditor en de gebundelde Parsoid-code in MediaWiki kunnen gebruiken, maar ze zullen voor de meeste ontwikkelaars wel nodig zijn.

Als u MediaWiki gebruikt met Nginx, moet u ook iets als dit toevoegen in uw serverblok (met de aanname dat de bestanden van de MediaWiki-instelling in /w/ staan): 

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

Als u Mediawiki met Docker gebruikt en uw lokale Parsoid-repository koppelt aan Mediawiki, moet u extra volume regelen in het dockercontainer in het bestand docker-compose.override.yml in het MediaWiki project. Om dat te doen, is de eenvoudigste manier om docker-compose.override.yml aan te maken in het project en onderstaande code erin te plaatsen (met wijziging van het pad). Als u al een bestand docker-compose.override.yml heeft, wijzig het dan dienovereenkomstig. 

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

Om de configuratie te testen, ga naar {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page waar $domain de hostnaam in uw $wgCanonicalServer is. (Let op dat productie-WMF-servers de Parsoid REST API niet vrijgeven voor het externe netwerk.)

Testen uitvoeren

Om alle parser- en mocha-testen uit te voeren: 

$ composer test

De parser-testen hebben nu veel opties die kunnen worden getoond met php bin/parserTests.php --help.

Als u de omgevingsvariabele MW_INSTALL_DIR heeft die naar een geconfigureerde MediaWiki-installatie wijst, kunt u een aantal extra tests uitvoeren met: 

$ composer phan-integrated

Eenvoudige wikitext converteren

U kunt eenvoudige stukjes code met wikitext op de commandoregel omzetten met het script parse.php in de map bin/: 

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

Het script heeft veel opties. Informatie over de optiesː php bin/parse.php --help

Parsoid debuggen (voor ontwikkelaars)

Zie Parsoid/Debugging voor tips over debuggen.

Blijvende integratie

Parsoid is altijd beschikbaar als een bibliotheek omdat het een composor afhankelijkheid van de MediaWiki kern is. Maar er zijn twee delen die niet zijn ingeschakeld:

  • Parsoid ServiceWiring
  • Parsoid's externe REST-API

De test-runner Quibble zou het inschakelen als het ontdekt dat er een kloon van mediawiki/services/parsoid.git is gemaakt als deel van de build. In dat geval:

  • verwijst de autoloader voor Wikimedia\Parsoid naar de gekloonde code (het vervangen van de door de composer geïnstalleerde versie)
  • Laad de extensie wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

De ServiceWiring moet vanaf MediaWiki 1.38 geactiveerd zijn.

De REST-API zou theoretisch nooit worden samengevoegd in MediaWiki: a) is het nooit in productie aan het publiek vrijgegeven, het is een interne API die wordt gebruikt door RESTBase die verdwijnt; b) is het nog nooit beveiligd en c) is het overbodig met de Enterprise MediaWiki API. De oplossing voor VisualEditor zal zijn dat het Parsoid direct aanroept via de VisualEditor Action-API, wat een retour via de REST-API opslaat.

Het laden van de extensie is dus een hack die het gebruik van veranderbare interfaces mogelijk maakt en waarvan we niet echt willen dat mensen dat gebruiken.

Voor de meeste doeleinden moet Parsoid dus niet worden toegevoegd als een CI-afhankelijkheid, de enige uitzondering vanaf oktober 2021 is de extensie Disambiguator MediaWiki.

Door Parsoid als een extensie te laden, kunnen we MediaWiki integratie-testen uitvoeren met mediawiki/services/parsoid.git (zoals Quibble, apitesting) en ervoor zorgen dat Parsoid en MediaWiki samenwerken.

Een extensie kan testen met Parsoid schrijven, zelfs wanneer het repository niet is gekloond. Omdat het een composer-afhankelijkheid is van de MediaWiki-kern is de namespace MediaWiki\Parsoid beschikbaar, maar het deel van servicewiring niet (het is extension/src in de Parsoid-repository en wordt beschikbaar gesteld in de namespace \MWParsoid). De code ParsoidTestFileSuite.php zou alleen de parsertesten uitvoeren als Parsoid is geladen (wat de standaard moet zijn bij MediaWiki 1.38).

Voor CI wordt Parsoid getest tegen het puntje van MediaWiki, terwijl MediaWiki wordt getest met de Composer-afhankelijkheid. In geval van een grote wijziging wordt de Parsoid-wijziging eerst samengevoegd (die de CI breekt, maar niet MediaWiki) en MediaWiki wordt aangepast wanneer Parsoid wordt bijgewerkt. Het is dus een verandering op één manier.

Release build

Voor MediaWiki-release builds hebben we een integratie van Parsoid ServiceWiring in VisualEditor zodat VisualEditor werkt zonder verdere configuratie (behalve wfLoadExtension( 'VisualEditor' )). De release build schakelt ook de REST-API in en koppelt alles zodat Parsoid direct werkt. Dit wordt gedaan door een stukje Parsoid-code te kopiëren in VisualEditor, dat niet in de master branch van VisualEditor is, omdat dat het verouderd zou zijn zodra Parsoid wordt bijgewerkt. In plaats daarvan wordt de code op twee plaatsen onderhouden.

Technische documenten

Geschiedenis

De oorspronkelijke applicatie is geschreven in JavaScript (met Node.js) en is in december 2012 op het Wikimedia-cluster in productie genomen. In 2019 werd Parsoid naar PHP geport en de PHP-versie verving in december 2019 de JS-versie op het Wikimedia-cluster. Parsoid wordt geïntegreerd in de kern MediaWiki, met als doel uiteindelijk de huidige interne parser van MediaWiki te vervangen. Begin 2024 werd Parsoid gebruikt op sommige productie-wiki's van de Wikimedia Foundation als standaardparser voor het weergeven bij het lezen. U kunt ze zien in de deze lijst.

Parsoid (de PHP-versie) is sinds versie 1.35, uitgebracht in september 2020, intern gebundeld met MediaWiki. Voor niet-Wikimedia-installaties werd Parsoid/JS ondersteund tot het einde van de levensduur van MediaWiki 1.31 (LTS, september 2021).

Veelgestelde vragen

  • Hoe zie ik of een pagina met Parsoid is opgebouwd?
    • In de voet staat: "Pagina is weergegeven met Parsoid".
  • Hoe stel ik een pagina in voor tijdelijke opbouw met Parsoid?
  • Hoe stel ik de hele wiki in voor opbouw met Parsoid?
    • Installeer Extension:ParserMigration
    • Zet $wgParserMigrationEnableParsoidArticlePages = true;
    • Zet $wgParserMigrationEnableParsoidDiscussionTools = true;
  • Welke wiki's van Wikimedia gebruiken Parsoid voor het opbouwen van pagina's?
    • De lijstː parsoidrendered.dblist. Op augustus 2025 zijn het ongeveer 250 van de 1000 wiki's. De uitrol zal doorgaan tot alle wiki's Parsoid gebruiken.

Zie ook

Contact

Als u hulp nodig heeft of vragen/feedback heeft, kunt u contact met ons opnemen via #mediawiki-parsoid verbinden of de wikitext-l mailinglijst. Als dat allemaal niet lukt, kunt u ons ook e-mailen content-transform-team op het domein wikimedia.org.

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