Jump to content

Parsoid

Rastreador de problemas: #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 88% complete.
Languages:
Seguido en Phabricator
Tarea T409283
Resuelto
Al igual que todo MediaWiki, Parsoid aún no es compatible con PHP 8.4 o posterior. Use PHP 8.3 o evite actualizar a la versión 1.45 hasta que se publique un parche.
Proyectos de la Fundación Wikimedia
Parsoid
Un analizador sintáctico de texto wiki en tiempo de ejecución bidireccional. Convierte de ida y vuelta entre código wiki y DOM HTML/XML con RDFa.
Grupo: Content Transform Team
Inicio: 2011-10
Equipo: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
Backlog: #parsoid
Líder: C.Scott Ananian
Gestión: Sérgio Lopes
Actualizaciones: Parsoid/Releases
Progreso: Parsoid/Deployments
Interpretación artística del motor de ejecución para wikis Parsoid compatible con HTML5 y RDFa

Para la versión anterior de Parsoid escrita en JavaScript (Node.js), véase Parsoid/JS .

Parsoid es una biblioteca empaquetada junto con MediaWiki (a partir de la versión 1.35) utilizada para convertir de ida y vuelta entre código wiki y HTML. Ha estado en desarrollo desde 2012, inicialmente escrita en JavaScript y construida para soportar el VisualEditor . El objetivo es, en un futuro, reemplazar completamente el analizador sintáctico nativo de MediaWiki por Parsoid.

El analizador anterior sigue gozando de soporte en MediaWiki 1.43 (LTS), pero probablemente no será así en el próximo LTS.

Detalles técnicos

Parsoid es una aplicación capaz de traducir en ambas direcciones entre la sintaxis código wiki de MediaWiki y un modelo de documentos HTML/RDFa equivalente, compatible con procesamiento automatizado y edición enriquecida mejorada.

Ha estado en desarrollo desde 2012 por un equipo especial de la Fundación Wikimedia. Lo utilizan ampliamente VisualEditor , Traducción de contenido y otras aplicaciones.

Parsoid tiene como objeto brindar una conversión bidireccional impecable, que evite pérdidas de información y «diferencias sucias».

En los wikis de Wikimedia, para varios fines, Parsoid actualmente se ejecuta en un servidor intermediario tras RESTBase , que almacena el HTML que Parsoid procesa. Se espera sustituir con el tiempo RESTBase con una antememoria más estrechamente integrada con MediaWiki.

Para conocer más detalles sobre el proyecto en conjunto, consulte esta entrada de blog de marzo de 2013. Para obtener información sobre el modelo HTML utilizado, vea la especificación del DOM de MediaWiki.

Originalmente, Parsoid se estructuraba como servicio web escrito en JavaScript, haciendo uso de Node.js. Una charla técnica de febrero de 2019 (diapositivas), así como una entrada de blog, describen el proceso de reescritura en PHP. La API de extensiones de Parsoid se está desarrollando activamente en estos momentos; una charla técnica de agosto de 2020 describe esta labor.

Repositorio en GitHub: https://github.com/wikimedia/parsoid

Uso

Instalación

Esta extensión viene con MediaWiki 1.35 y versiones posteriores, así que no necesitas descargarla. Las instrucciones de configuración restantes aún deben seguirse.

Parsoid está incluido en MediaWiki desde la versión 1.35. No hace falta configuración alguna para activarlo.

Parsoid exporta una API REST interna que históricamente era utilizada por RESTBase y no era accesible fuera del clúster interno de la WMF. Esto ya no es necesario para el Editor Visual o las vistas de lectura del núcleo, y la API interna está perdiendo su vigencia, estando prevista su eliminación para MW 1.43.

Parsoid es nominalmente una biblioteca de Composer utilizada por el núcleo de MediaWiki. Si aun así necesitas la API interna por alguna razón, puedes cargar explícitamente Parsoid «como una extensión» añadiendo lo siguiente a LocalSettings.php: 

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

Se recomienda encarecidamente a cualquier usuario externo de la API interna de Parsoid que migre al punto de acceso de la página HTML REST del núcleo que brinda una funcionalidad equivalente.

Desarrollo

El desarrollo se produce en el Parsoid Git repository. La revisión de código tiene lugar en Gerrit. Consulta Gerrit/Primeros pasos para configurar tu propia cuenta.

En caso de utilizar el entorno de desarrollo MediaWiki-Vagrant en una máquina virtual, puedes simplemente añadirle el rol visualeditor y establecerá un Parsoid funcional junto con Extension:VisualEditor .

Las instrucciones a continuación son para MediaWiki 1.35 o posterior. Comprueba Parsoid/JS en caso de ejecutar la versión antigua de Parsoid escrita en JavaScript y utilizada para MW 1.34 y anteriores.

Enlazar a una copia de desarrollador de Parsoid

En una instalación MediaWiki estándar, Parsoid está incluido en MediaWiki como biblioteca de Composer, wikimedia/parsoid.

Para propósitos de desarrollo, generalmente querrás utilizar una copia de Parsoid obtenida de Git, y no la versión empaquetada en el núcleo de MediaWiki como biblioteca de Composer. Las siguientes líneas añadidas a LocalSettings.php permiten utilizar (opcionalmente) una copia de Parsoid proveniente de Git, cargar la API REST de Parsoid con wfLoadExtension (en lugar de utilizar la versión empaquetada en el Editor Visual) y configurar Parsoid a mano, lo que generalmente se hace mediante el Editor Visual: 

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

// Para desarrolladores: asegúrate de que se ejecute Parsoid desde $parsoidInstallDir,
// (no la versión incluida por defecto en mediawiki-core)
// Debe ejecutarse *antes* de 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 );
    // AutoLoader::registerNamespaces fue añadido en MW 1.39
    AutoLoader::registerNamespaces( [
        // Mantener esto sincronizado con la cláusula «autoload» en
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

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

# Configurar Parsoid manualmente
$wgVisualEditorParsoidAutoConfig = false;
$wgParsoidSettings = [
    'useSelser' => true,
    'rtTestMode' => false,
    'linting' => false,
];
$wgVirtualRestConfig['modules']['parsoid'] = [
    // URL de la instancia de Parsoid.
    // Si Parsoid no se ejecuta localmente, cambia $wgServer para que coincida con el anfitrión no local 
    // En caso de ejecutar Docker en macOS, puede que tengas que reemplazar $wgServer por http://host.docker.internal:8080
    // En caso de ejecutar Docker en Linux, puede que tengas que reemplazar $wgServer por http://172.17.0.1:8080
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // «Dominio» de Parsoid; vea más abajo (opcional; rara vez hace falta)
    // 'domain' => 'localhost',
];
unset( $parsoidInstallDir );

Estas líneas no son necesarias para la mayoría de los usuarios del Editor Visual, que pueden utilizar la autoconfiguración del Editor Visual y el código de Parsoid empaquetado en MediaWiki, pero sí serán necesarias para la mayoría de los desarrolladores.

Si estás sirviendo MediaWiki con Nginx, también tendrás que añadir algo parecido a esto en el bloque de tu servidor (asumiendo que tu configuración de MediaWiki tenga sus archivos residiendo en /w/): 

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

If you are running Mediawiki using Docker, and linking your local Parsoid repository to Mediawiki, you need to map additional volume to the docker container in docker-compose.override.yml file in media wiki project. To do so, the simplest way is to create docker-compose.override.yml in mediawiki project and put code bellow inside (with path modification). If you already have docker-compose.override.yml file, modify it accordingly. 

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

Para realizar pruebas de configuración correcta, visita {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page, donde $domain es el nombre del host de tu $wgCanonicalServer. (Ten en cuenta que los servidores de producción de la WMF no exponen la API REST de Parsoid a la red externa.)

Ejecutar las pruebas

Para ejecutar todas las pruebas del analizador y de Mocha: 

$ composer test

Las pruebas del analizador cuentan ahora con una serie de opciones que se pueden enumerar mediante php bin/parserTests.php --help.

Si tu variable de entorno MW_INSTALL_DIR apunta a una instalación de MediaWiki configurada, puedes ejecutar algunas pruebas adicionales con: 

$ composer phan-integrated

Conversión de wikitexto simple

Puedes convertir fragmentos simples de wikitexto desde la línea de comandos utilizando el script parse.php en el directorio bin/: 

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

El script de análisis tiene muchas opciones. php bin/parse.php --help proporciona información al respecto.

Depuración de Parsoid (para desarrolladores)

Véase Parsoid/Debugging para consejos de depuración.

Integración continua

A octubre de 2021

Parsoid siempre está disponible como biblioteca al ser una dependencia de Composer del núcleo de MediaWiki. Pero dos elementos no están activados:

  • el ServiceWiring de Parsoid
  • la API REST externa de Parsoid

El lanzador de pruebas Quibble lo activará si detecta que se ha clonado mediawiki/services/parsoid.git como parte de la versión. En cuyo caso:

  • apuntará el cargador automático de Wikimedia\Parsoid al código clonado (reemplazando efectivamente la versión instalada por Composer)
  • cargará la extensión wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

El ServiceWiring debería estar habilitado en MediaWiki a partir de la versión 1.38.

En teoría, la API REST nunca se fusionará en MediaWiki: a) nunca se ha expuesto al público en producción, es una API interna utilizada por RESTBase que va a desaparecer; b) nunca ha sido sometida a una auditoría de seguridad y c) es redundante con la API empresarial de MediaWiki. La solución será que el Editor Visual invoque directamente Parsoid mediante la API de acciones del Editor Visual, lo que ahorraría tener que pasar por la API REST.

Cargar la extensión es por tanto un apaño que permite utilizar interfaces susceptibles de cambiar y que aún no queremos poner a disposición de los usuarios.

En la mayoría de los casos, por tanto, no se debería añadir Parsoid como dependencia de la integración continua, siendo la única excepción a fecha de octubre de 2021 la extensión Disambiguator de MediaWiki.

Cargar Parsoid como extensión permite ejecutar las tareas de las pruebas de integración de MediaWiki contra mediawiki/services/parsoid.git (como Quibble y apitesting) y garantizar que Parsoid y MediaWiki sean compatibles.

Una extensión puede ser capaz de escribir pruebas con Parsoid aunque no se haya clonado el repositorio. Dado que es una dependencia de Composer del núcleo de MediaWiki, el espacio de nombres MediaWiki\Parsoid está disponible, pero no así la parte del cableado de servicios (es extension/src en el repositorio de Parsoid y está expuesta en tanto que espacio de nombres \MWParsoid). El código de ParsoidTestFileSuite.php solo lanzará las pruebas del analizador si Parsoid está cargado (lo cual debería ser el comportamiento predeterminado con MediaWiki 1.38).

Para la integración continua, Parsoid es sometido a pruebas contra la superficie de MediaWiki, mientras que en el caso de MediaWiki es con la dependencia de Composer. En caso de un cambio disruptivo, el cambio de Parsoid se fusiona en primer lugar (lo que rompe su integración continua, pero no la de MediaWiki), y el de MediaWiki se ajusta cuando se haya actualizado Parsoid. Así pues, se trata de un cambio en un solo sentido.

Versión de lanzamiento

Para las versiones de lanzamiento de MediaWiki, tenemos una integración del ServiceWiring de Parsoid en el Editor Visual para que este último funcione sin una configuración suplementaria (aparte de wfLoadExtension( 'VisualEditor' )). La versión de lanzamiento también permite utilizar la API REST y conecta todo para que Parsoid se pueda ejecutar inmediatamente. Esto se hace copiando un poco de código de Parsoid en el Editor Visual que no está en la rama maestra del Editor Visual, ya que quedaría obsoleto tan pronto como se actualice Parsoid. En lugar de eso, el código está mantenido en dos sitios.

Documentos técnicos

Enlaces para desarrolladores de Parsoid

Enlaces para desplegadores de Parsoid (al clúster de Wikimedia)

Historia

La aplicación original se escribió en JavaScript (utilizando Node.js) y se empezó a ejecutar en los servidores de Wikimedia en diciembre de 2012. En 2019, Parsoid se reescribió en PHP, y esta versión sustituyó a la anterior en JS en los servidores de Wikimedia en diciembre de 2019. Parsoid está en proceso de integración en el núcleo de MediaWiki, con el objetivo de reemplazar a la larga el analizador sintáctico nativo actual de MediaWiki. In early 2024, Parsoid began to be used on some production wikis of the Wikimedia Foundation as the default parser for read views. You can see them in the production config list.

Parsoid (en su versión PHP) se ha incluido nativamente en MediaWiki desde la versión 1.35, publicada en septiembre de 2020. En instalaciones ajenas a Wikimedia, Parsoid/JS gozaba de servicio técnico hasta la finalización del ciclo de vida de MediaWiki 1.31 (LTS), en septiembre de 2021.

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 Extensión: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.

Véase también

Enlaces externos

Contacto

Si necesitas ayuda o tienes preguntas/comentarios, puedes ponerte en contacto con nosotros en #mediawiki-parsoid connect o en la lista de correo wikitext-l. Si todo esto falla, también puedes contactar por nosotros por correo electrónico en content-transform-team en el dominio wikimedia.org.

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