Markdown Easy
Un filtro de texto Markdown simple para Drupal que convierte la sintaxis Markdown a HTML utilizando la biblioteca league/commonmark.
markdown_easy
Instalar
composer require 'drupal/markdown_easy:^2.0'
Overview
Markdown Easy es un módulo de filtro de texto sencillo para Drupal diseñado para convertir sintaxis Markdown en HTML. Aprovecha la potente biblioteca PHP league/commonmark para el análisis y proporciona una configuración mínima a través de la interfaz de administración de Drupal.
El módulo ofrece tres "sabores" distintos de Markdown para adaptarse a diferentes necesidades: Markdown Estándar (especificación CommonMark), Markdown con estilo GitHub (con tablas, tachado, enlaces automáticos y listas de tareas), y Markdown Smörgåsbord (que añade notas al pie y listas de descripción). La seguridad se prioriza por defecto con la eliminación de entrada HTML y el bloqueo de enlaces inseguros.
Cuando se instala, Markdown Easy crea automáticamente un formato de texto "Markdown" preconfigurado. Por seguridad, exige que el filtro del núcleo de Drupal "Limitar las etiquetas HTML permitidas y corregir HTML defectuoso" se ejecute después del filtro Markdown Easy para prevenir ataques XSS.
Features
- Tres opciones de sabor Markdown: Markdown Estándar (CommonMark), Markdown con estilo GitHub, y Markdown Smörgåsbord con características extendidas
- Creación automática de un formato de texto 'Markdown' preconfigurado tras la instalación del módulo
- Seguridad por defecto: eliminación de entrada HTML y bloqueo de enlaces inseguros habilitados de fábrica
- Validación obligatoria que requiere que el filtro 'Limitar las etiquetas HTML permitidas' se ejecute después de Markdown Easy
- Sistema de advertencias que alerta a los administradores cuando faltan etiquetas HTML requeridas en la lista de etiquetas permitidas
- Soporte de alineación de tablas con inyección automática de clases CSS para columnas alineadas a la izquierda, centro y derecha
- Extensibilidad a través de dos hooks: hook_markdown_easy_config_modify() para configuración y hook_markdown_easy_environment_modify() para añadir extensiones Markdown
- Verificaciones de estado en tiempo de ejecución que informan sobre configuraciones de formato de texto inseguras en la página de Informe de Estado
- Advertencia de compatibilidad cuando el filtro obsoleto 'Convertir saltos de línea en HTML' está habilitado
Use Cases
Sitios de Documentación Técnica
Permite a los editores de contenido escribir documentación técnica usando la familiar sintaxis Markdown. Use Markdown con estilo GitHub para bloques de código con soporte de resaltado de sintaxis, tablas para presentación de datos, y listas de tareas para listas de verificación. El sabor Smörgåsbord añade notas al pie para citas y referencias.
Plataforma de Blog para Desarrolladores
Cree un blog donde los desarrolladores puedan escribir publicaciones en Markdown en lugar de editores WYSIWYG. La sintaxis familiar reduce la fricción para escritores técnicos que regularmente usan Markdown en sus flujos de trabajo (archivos README, issues de GitHub, etc.).
Migración desde Generadores de Sitios Estáticos
Organizaciones que se mudan de Jekyll, Hugo u otros generadores de sitios estáticos basados en Markdown a Drupal pueden preservar su contenido Markdown existente sin conversión. Los editores pueden continuar usando la misma sintaxis con la que están familiarizados.
CMS Headless con Almacenamiento Markdown
Para implementaciones headless de Drupal donde el contenido es consumido por frontends que manejan su propio renderizado Markdown, almacene Markdown sin procesar en campos de texto y use Markdown Easy para la vista previa en el administrador de Drupal.
Añadir Extensiones Markdown Personalizadas
Los desarrolladores pueden extender los sabores integrados implementando hook_markdown_easy_environment_modify() para añadir cualquier extensión CommonMark del ecosistema, como Menciones, Puntuación Inteligente, o extensiones personalizadas.
Tips
- Use el sabor 'Markdown Smörgåsbord' para el conjunto de características más completo incluyendo notas al pie y listas de descripción
- Siempre habilite 'Limitar las etiquetas HTML permitidas' después de Markdown Easy para una seguridad adecuada - esto previene ataques XSS
- Revise la página de Informe de Estado (/admin/reports/status) para advertencias sobre formatos de texto configurados de forma insegura
- Al añadir nuevos elementos HTML, consulte los consejos de filtro mostrados en la página de configuración del formato de texto para las etiquetas y atributos exactos necesarios
- Implemente hook_markdown_easy_config_modify() para personalizar el estilo de las notas al pie o los nombres de clases de alineación de tablas
- Para personalización avanzada, use hook_markdown_easy_environment_modify() para añadir cualquier extensión CommonMark de https://commonmark.thephpleague.com/2.6/extensions/overview/
- La alineación de tablas (izquierda, centro, derecha) aplica automáticamente clases CSS que pueden estilizarse en su tema
Technical Details
Hooks 2
hook_markdown_easy_config_modify
Permite a los módulos modificar la configuración del convertidor Markdown antes del procesamiento. Esto se puede usar para cambiar la configuración de seguridad como html_input y allow_unsafe_links, o para personalizar las opciones de renderizado de notas al pie y tablas.
hook_markdown_easy_environment_modify
Permite a los módulos modificar el entorno Markdown después de cargar las extensiones base. Esto se puede usar para añadir extensiones CommonMark adicionales no incluidas en los sabores integrados.
Troubleshooting 8
Ajuste los pesos de los filtros en la página de configuración del formato de texto. Asegúrese de que Markdown Easy tenga un peso menor (se ejecuta primero) que el filtro 'Limitar las etiquetas HTML permitidas'. El filtro 'Limitar las etiquetas HTML permitidas' debe estar habilitado y configurado para ejecutarse después de Markdown Easy.
Verifique que el filtro Markdown Easy esté habilitado en el formato de texto que se está usando. Compruebe que el formato de texto esté asignado al campo y que los usuarios tengan permiso para usar ese formato de texto.
Asegúrese de haber seleccionado el sabor Markdown apropiado (estilo GitHub para tablas/tachado, Smörgåsbord para notas al pie). También verifique que las etiquetas HTML correspondientes estén incluidas en la lista permitida del filtro 'Limitar las etiquetas HTML permitidas'.
Añada las etiquetas HTML y atributos recomendados al filtro 'Limitar las etiquetas HTML permitidas'. La advertencia lista exactamente qué etiquetas se necesitan para compatibilidad completa con el sabor Markdown seleccionado.
Por defecto, Markdown Easy elimina la entrada HTML por seguridad. Si necesita permitir HTML, establezca skip_html_input_stripping a true en la configuración, o implemente hook_markdown_easy_config_modify() para establecer html_input a 'allow'.
Habilite el filtro 'Limitar las etiquetas HTML permitidas' en el formato de texto afectado y asegúrese de que se ejecute después del filtro Markdown Easy. Este es un requisito de seguridad para prevenir ataques XSS.
La versión 2.x ya no requiere el filtro 'Convertir saltos de línea en HTML'. Desactívelo y añada <p> y <br> a las etiquetas HTML permitidas. Tenga en cuenta que 1.x no seguía la especificación Markdown para saltos de línea, por lo que el contenido existente puede renderizarse de manera diferente.
Si previamente tenía instalado el módulo Markdown con league/commonmark, elimine primero la versión anterior: composer remove league/commonmark, luego instale Markdown Easy. Markdown Easy requiere una versión más nueva de la biblioteca.
Security Notes 6
- Por defecto, Markdown Easy se ejecuta con html_input: strip y allow_unsafe_links: false para máxima seguridad
- El módulo exige que el filtro 'Limitar las etiquetas HTML permitidas' se ejecute después de Markdown Easy para sanear la salida HTML convertida
- Desactivar la aplicación de filtros (skip_filter_enforcement) o la eliminación de HTML (skip_html_input_stripping) puede exponer su sitio a vulnerabilidades XSS
- El módulo muestra advertencias en tiempo de ejecución en la página de Informe de Estado para cualquier formato de texto configurado de forma insegura
- Al usar hooks para modificar la configuración de seguridad, asegúrese de entender las implicaciones para la postura de seguridad de su sitio
- La cobertura de seguridad en drupal.org es 'covered', lo que significa que este módulo es revisado por el Equipo de Seguridad de Drupal