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
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 ![]()
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 ![]()
Este documento está bajo control de versiones: sugiere cambios en github.