Plugins

Cada página se construye con textlane, un pipeline de Markdown y HTML escrito en Rust. La clave plugins de htmlpress.yaml le añade los plugins propios de textlane, en dos puntos:

• md se ejecuta sobre el árbol de una página Markdown (mdast)
• html se ejecuta sobre el árbol de cada página (hast), sea HTML o Markdown

plugins:
  md:
    - name: md.shiftHeading
      options: { shift: 1 }
  html:
    - name: html.externalLinks
      options: { target: _blank }

Qué puede ser un plugin

Cada punto es una lista cuyas entradas toman las mismas formas que el use de textlane:

• Un nombre: uno de los plugins que trae textlane, como html.externalLinks o md.toc, con sus valores por defecto.
• Un nombre con opciones: { name, options }, con las opciones que textlane documenta para ese plugin.

Htmlpress es un único binario, así que un punto solo acepta los plugins que lleva dentro, no plugins de JavaScript como Livemark. Para un marcado propio, añade un componente del proyecto: una directiva :::name o una etiqueta <htmlpress-name> que rellenan tus archivos de components/<name>/.

Dónde se ejecuta cada punto

Página Markdown: parseo → frontmatter, GFM, listas de definición, matemáticas, directivas
  → plugins md → ids de encabezados, componentes → HTML
Cada página:     parseo → emoji, enlaces, matemáticas → KaTeX → plugins html
  → slugs de encabezados → reescritura de rutas → resaltado de sintaxis

• Los plugins md se ejecutan antes de que htmlpress convierta las directivas en componentes, así que ven todas las directivas.
• Los plugins html se ejecutan antes de los slugs de los encabezados, así que un encabezado que añada un plugin recibe un ancla y aparece en el índice «En esta página». Van antes del resaltado de sintaxis, así que los bloques de código conservan su texto plano.

Un plugin que htmlpress ya ejecuta

Nombrar un plugin que ya está en el pipeline, como md.gfm o html.slug, lo reconfigura en lugar de ejecutarlo dos veces: tus opciones se combinan con las de htmlpress, como el use de textlane combina un plugin usado de nuevo. Cuando htmlpress fija la misma opción, gana su valor, porque sus plugins se añaden después de los tuyos.

plugins:
  html:
    - name: html.slug
      options: { prefix: doc- }

Aquí cada id de encabezado generado lleva el prefijo doc-, y cada encabezado sigue recibiendo su id una sola vez.

Errores y recompilaciones

Un nombre desconocido o unas opciones incorrectas hacen fallar la compilación con un error de plugins.md o plugins.html, igual que un plugin cuyo árbol no encaja en su punto, como md.toHtml en html. Editar htmlpress.yaml mientras corre htmlpress start recompila todas las páginas con los nuevos plugins.

Véase también

• Configuración: todas las demás claves.
• textlane: los plugins y sus opciones.