markdown.it, il motore CommonMark utilizzato da Discourse, dispone di una vasta gamma di plugin
Ancore negli intestazioni, liste di definizioni, frecce intelligenti e la lista continua.
Prima un avvertimento
CommonMark è progettato per essere… comune. Quanto più ti allontani dalla specifica, tanto meno il tuo Markdown diventa “comune”. Può rendere più difficile la portabilità ad altre soluzioni e, se non si fa attenzione, causare incoerenze interne nell’analisi. Prima di reimballare qualsiasi cosa, assicurati di rispondere alla domanda “voglio davvero reimballare questo?”
Ho appena finito di reimballare Discourse Footnote e ho alcune lezioni da condividere su come farlo nel modo giusto.
Passi per i pigri
Se sei pigro e vuoi semplicemente iniziare, il modo più semplice è fare un fork delle note a piè di pagina e sostituire i file e i nomi delle variabili. Sono stato abbastanza attento ad assicurarmi che seguisse le migliori pratiche, quindi dovresti avere un esempio solido.
Mosse di apertura, un reimballaggio minimo
Da quello che posso dire, la maggioranza dei plugin markdown.it viene distribuita come file js vanilla. In molti casi, i plugin sono semplicemente forniti come singolo file js, come questo: markdown-it-mark.js.
Idealmente vuoi lasciare il file originale intatto, il che significa che puoi semplicemente copiare una versione aggiornata del file nel tuo plugin senza dover armeggiare con il plugin esistente.
Il primo problema che incontrerai è che devi insegnare al tuo plugin a caricare questo JavaScript sul server, perché il motore Markdown funziona anche sul server. Per farlo, puoi semplicemente copiare il file così com’è in assets/javascripts/vendor/original-plugin.js, quindi nel tuo file plugin.rb aggiungi:
# this teaches our markdown engine to load your vanilla js file
register_asset "javascripts/vendor/original-plugin.js", :vendored_pretty_text
Una volta che hai il corpo effettivo del plugin incluso, devi insegnare alla nostra pipeline come caricarlo e inizializzarlo:
Crea un file chiamato assets/javascripts/lib/discourse-markdown/your-extension.js
Questo file verrà caricato automaticamente perché termina con .js E si trova nella directory discourse-markdown.
Un esempio semplice può essere:
export function setup(helper) {
// this allows you only to load your extension if a site setting is enabled
helper.registerOptions((opts, siteSettings) => {
opts.features["your-extension"] = !!siteSettings.enable_my_plugin;
});
// allow any attributes that you need to support,
// otherwise our sanitizer will strip them
helper.allowList(["div.amazingness"]);
// you can also do fancy stuff like this
helper.allowList({
custom(tag, name, value) {
if ((tag === "a" || tag === "li") && name === "id") {
return !!value.match(/^fn(ref)?\d+$/);
}
},
});
// finally this is the magic that you would use to register the extension in
// our pipeline. whateverGlobal is the name of global the plugin exposes
// it takes in a single (md) var that is then used to amend the pipeline
helper.registerPlugin(window.whateverGlobal);
}
Testa sempre
bin/rake autospec di Discourse è consapevole dei plugin ![]()
Ciò significa che quando aggiungi il file spec/pretty_text_spec.rb, ogni volta che lo salvi verrà eseguito il file di test del plugin.
Lo utilizzo estesamente perché rende il lavoro molto più veloce.
Diciamo che hai aggiunto un plugin che cambia ogni numero in un post in “palla 8”, puoi chiamarlo discourse-magic-8-ball.
Ecco come strutturerei i test:
require "rails_helper"
describe PrettyText do
it "can be disabled" do
SiteSetting.enable_magic_8_ball = false
markdown = <<~MD
1 thing
MD
html = <<~HTML
<p>1 thing</p>
HTML
cooked = PrettyText.cook markdown.strip
expect(cooked).to eq(html.strip)
end
it "supports magic 8 ball" do
markdown = <<~MD
1 thing
MD
html = <<~HTML
<p>8 circle thing</p>
HTML
cooked = PrettyText.cook markdown.strip
expect(cooked).to eq(html.strip)
end
end
Potresti dover “decorare i post”
In alcuni casi, i plugin funzionano meglio quando aggiungono funzionalità “dinamiche” extra ai tuoi post. Esempi sono il plugin poll o il plugin footnotes che aggiunge un “…” che mostra dinamicamente un tooltip.
Se devi “decorare” i post, aggiungi 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) => {
// your amazing magic goes here
});
});
Potresti dover “post-elaborare” i post
In alcuni casi, potresti dover “post-elaborare” i post; il motore di rendering Markdown, per progettazione, non è consapevole di alcune informazioni come, ad esempio, post_id. In alcuni casi, potresti desiderare l’accesso lato server al post e all’HTML “cotto”; questo può permetterti di fare cose come attivare job in background, sincronizzare campi personalizzati o “correggere” l’HTML generato automaticamente.
Per le note a piè di pagina, avevo bisogno di un id distinto per ogni nota a piè di pagina, il che significava che avevo bisogno di accesso a post_id, quindi sono stato costretto ad apportare modifiche all’HTML nel post processor (che viene eseguito in sidekiq).
Per agganciarti, aggiungi quanto segue al tuo file plugin.rb:
DiscourseEvent.on(:before_post_process_cooked) do |doc, post|
doc.css("a.always-bing").each do |a|
# this should always go to bing
a["href"] = "https://bing.com"
end
end
Potresti aver bisogno di alcuni CSS personalizzati
Se vuoi distribuire CSS personalizzati, assicurati di registrare il file in plugin.rb
Aggiungi il tuo css in assets/stylesheets/magic.scss e poi esegui
register_asset "stylesheets/magic.scss"
Ricorda che “ricarichiamo automaticamente” le modifiche, quindi puoi modificare il CSS del tuo plugin e vedere i cambiamenti al volo nello sviluppo.
Buona fortuna con le tue avventure di reimballaggio ![]()
Questo documento è controllato nella versione - suggerisci modifiche su github.