Reempaquetar una extensión de markdown-it como plugin de Discourse

markdown.it, el motor CommonMark utilizado por Discourse, tiene una amplia variedad de complementos

Anclas de encabezados, listas de definición, flechas inteligentes y la lista continúa sin fin.

Primero, una advertencia

:warning: Se supone que CommonMark es… común. Cuanto más te alejes de la especificación, menos común será tu Markdown. Esto puede dificultar la portabilidad a otras soluciones y, si no se tiene cuidado, puede causar inconsistencias internas en el análisis. Antes de reempaquetar cualquier cosa, asegúrate de responder a la pregunta «¿realmente quiero reempaquetar esto?».

Acabo de terminar de reempaquetar Discourse Footnote y tengo algunas lecciones para compartir sobre cómo hacerlo correctamente.

Pasos para los perezosos

Si eres perezoso y solo quieres empezar, la forma más fácil es simplemente bifurcar (fork) footnotes e intercambiar archivos y nombres de variables. Fui bastante cuidadoso al asegurarme de que siguiera las mejores prácticas, por lo que deberías tener un ejemplo sólido.

Movimientos iniciales, un reempaquetado mínimo

Por lo que puedo ver, la mayoría de los complementos de markdown.it se distribuyen como archivos js vanilla. En muchos casos, los complementos se distribuyen simplemente como un único archivo js, como este: markdown-it-mark.js.

Idealmente, querrás dejar el archivo original intacto, lo que significa que simplemente puedes copiar una versión actualizada del archivo en tu complemento sin necesidad de modificar el complemento existente.

El primer problema con el que te encontrarás es que tienes que enseñar a tu complemento a cargar este JavaScript en el servidor, porque el motor de Markdown también se ejecuta en el servidor. Para hacerlo, simplemente puedes copiar el archivo tal cual a assets/javascripts/vendor/original-plugin.js y luego en tu archivo plugin.rb añadirías:

# esto enseña a nuestro motor de markdown a cargar tu archivo js vanilla
register_asset "javascripts/vendor/original-plugin.js", :vendored_pretty_text

Una vez que tengas incluido el cuerpo real del complemento, necesitas enseñar a nuestro pipeline cómo cargarlo e inicializarlo:

Crea un archivo llamado assets/javascripts/lib/discourse-markdown/your-extension.js

Este archivo se cargará automáticamente porque termina con .js Y está en el directorio discourse-markdown.

Un ejemplo simple puede ser:

export function setup(helper) {
  // esto te permite cargar tu extensión solo si una configuración del sitio está habilitada
  helper.registerOptions((opts, siteSettings) => {
    opts.features["your-extension"] = !!siteSettings.enable_my_plugin;
  });

  // permite cualquier atributo que necesites soportar,
  // de lo contrario nuestro sanitizador los eliminará
  helper.allowList(["div.amazingness"]);

  // también puedes hacer cosas avanzadas como esta
  helper.allowList({
    custom(tag, name, value) {
      if ((tag === "a" || tag === "li") && name === "id") {
        return !!value.match(/^fn(ref)?\d+$/);
      }
    },
  });

  // finalmente, esto es la magia que usarías para registrar la extensión en
  // nuestro pipeline. whateverGlobal es el nombre del global que expone el complemento
  // recibe una única variable (md) que luego se usa para modificar el pipeline
  helper.registerPlugin(window.whateverGlobal);
}

Siempre haz pruebas

El comando bin/rake autospec de Discourse es consciente de los complementos :innocent:

Esto significa que cuando añades el archivo spec/pretty_text_spec.rb, cada vez que lo guardes se ejecutará el archivo de pruebas del complemento.

Yo uso esto extensamente porque hace el trabajo mucho más rápido.

Digamos que añadiste un complemento que cambia cada número en una publicación por un círculo 8, puedes llamarlo discourse-magic-8-ball.

Así es como yo estructuraría las pruebas:

require "rails_helper"

describe PrettyText do
  it "puede ser deshabilitado" do
    SiteSetting.enable_magic_8_ball = false

    markdown = <<~MD
      1 cosa
    MD

    html = <<~HTML
      <p>1 cosa</p>
    HTML

    cooked = PrettyText.cook markdown.strip
    expect(cooked).to eq(html.strip)
  end

  it "soporta magic 8 ball" do
    markdown = <<~MD
      1 cosa
    MD

    html = <<~HTML
      <p>8 círculo cosa</p>
    HTML

    cooked = PrettyText.cook markdown.strip
    expect(cooked).to eq(html.strip)
  end
end

Es posible que necesites «decorar publicaciones»

En algunos casos, los complementos funcionan mejor cuando añaden funciones «dinámicas» extra a tus publicaciones. Ejemplos de esto son el complemento poll o el complemento footnotes, que añade un «…» que muestra dinámicamente una descripción emergente (tooltip).

Si necesitas «decorar» publicaciones, añade assets/javascripts/api-initializers/your-initializer.js

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  const siteSettings = api.container.lookup("service:site-settings");
  if (!siteSettings.enable_magic_8_ball) {
    return;
  }

  api.decorateCookedElement((elem) => {
    // tu increíble magia va aquí
  });
});

Es posible que necesites «posprocesar» las publicaciones

En algunos casos, es posible que necesites «posprocesar» las publicaciones; el motor de renderizado de markdown, por diseño, no es consciente de cierta información, como, por ejemplo, post_id. En algunos casos, es posible que desees acceso en el lado del servidor a la publicación y al HTML «cocido»; esto te permite hacer cosas como activar trabajos en segundo plano, campos personalizados sincronizados o «corregir» HTML generado automáticamente.

Para las notas al pie, necesitaba un id distinto para cada nota al pie, lo que significaba que necesitaba acceso a post_id, por lo que me vi obligado a realizar cambios en el HTML en el posprocesador (que se ejecuta en sidekiq).

Para conectar esto, añadirías lo siguiente a tu archivo plugin.rb:

DiscourseEvent.on(:before_post_process_cooked) do |doc, post|
  doc.css("a.always-bing").each do |a|
    # esto debería apuntar siempre a bing
    a["href"] = "https://bing.com"
  end
end

Es posible que necesites CSS personalizado

Si quieres distribuir CSS personalizado, asegúrate de registrar el archivo en plugin.rb.

Añade tu CSS a assets/stylesheets/magic.scss y luego ejecuta

register_asset "stylesheets/magic.scss"

Recuerda que «recargamos automáticamente» los cambios, por lo que puedes modificar el CSS de tu complemento y ver los cambios sobre la marcha durante el desarrollo.

Buena suerte con tus aventuras de reempaquetado :four_leaf_clover:


Este documento está bajo control de versiones: sugiere cambios en github.

29 Me gusta

Una publicación fue dividida en un nuevo tema: ¿Se puede reemplazar Markdown con Quarkdown