Ricreare un'estensione di markdown-it come plugin per Discourse

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

:warning: 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 :innocent:

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 :four_leaf_clover:


Questo documento è controllato nella versione - suggerisci modifiche su github.

29 Mi Piace

Un post è stato diviso in un nuovo argomento: Can Markdown be replaced with Quarkdown