markdown-it-Erweiterung als Discourse-Plugin neu paketieren

markdown.it, die von Discourse verwendete CommonMark-Engine, verfügt über eine breite Palette an Plugins

Header-Anker, Definitionslisten, intelligente Pfeile – die Liste ist endlos.

Zunächst eine Warnung

:warning: CommonMark soll … Common (gemeinsam/standardisiert) sein. Je weiter du dich von der Spezifikation entfernst, desto weniger „Common“ wird dein Markdown. Das kann die Portierung auf andere Lösungen erschweren und, wenn man nicht vorsichtig ist, zu internen Inkonsistenzen beim Parsen führen. Bevor du irgendetwas neu verpackst (repackage), stelle sicher, dass du dir die Frage beantwortest: „Will ich das wirklich neu verpacken?“

Ich habe gerade das Neuverpacken von Discourse Footnote abgeschlossen und möchte einige Lektionen teilen, wie man das richtig macht.

Schritte für Faulenzer

Wenn du faul bist und einfach nur loslegen möchtest, ist der einfachste Weg, footnotes zu forken und Dateien sowie Variablen-Namen auszutauschen. Ich habe sehr sorgfältig darauf geachtet, dass Best Practices eingehalten werden, damit du ein solides Beispiel hast.

Erste Schritte, ein minimales Repackaging

Soweit ich das beurteilen kann, werden die meisten markdown.it-Plugins als reine JavaScript-Dateien ausgeliefert. In vielen Fällen werden Plugins einfach als einzelne js-Datei bereitgestellt, wie z. B. hier: markdown-it-mark.js.

Idealerweise möchtest du das Original unversehrt lassen; das bedeutet, dass du einfach eine aktualisierte Version der Datei in dein Plugin kopieren kannst, ohne dich mit dem bestehenden Plugin herumschlagen zu müssen.

Das erste Problem, auf das du stoßen wirst, ist, dass du deinem Plugin beibringen musst, dieses JavaScript auf dem Server zu laden, da die Markdown-Engine auch auf dem Server läuft. Dazu kannst du die Datei einfach unverändert in assets/javascripts/vendor/original-plugin.js kopieren. Dann fügst du in deiner plugin.rb-Datei Folgendes hinzu:

# dies bringt unserer Markdown-Engine bei, deine reine js-Datei zu laden
register_asset "javascripts/vendor/original-plugin.js", :vendored_pretty_text

Sobald der eigentliche Kern des Plugins enthalten ist, musst du unserer Pipeline beibringen, es zu laden und zu initialisieren:

Erstelle eine Datei namens assets/javascripts/lib/discourse-markdown/your-extension.js

Diese Datei wird automatisch geladen, da sie mit .js endet UND sich im Verzeichnis discourse-markdown befindet.

Ein einfaches Beispiel könnte so aussehen:

export function setup(helper) {
  // dies ermöglicht es, deine Extension nur zu laden, wenn eine Site-Einstellung aktiviert ist
  helper.registerOptions((opts, siteSettings) => {
    opts.features["your-extension"] = !!siteSettings.enable_my_plugin;
  });

  // erlaube alle Attribute, die du unterstützen musst,
  // andernfalls entfernt sie unser Sanitizer
  helper.allowList(["div.amazingness"]);

  // du kannst auch ausgefallene Dinge wie diese machen
  helper.allowList({
    custom(tag, name, value) {
      if ((tag === "a" || tag === "li") && name === "id") {
        return !!value.match(/^fn(ref)?\d+$/);
      }
    },
  });

  // schließlich ist dies die Magie, die du verwenden würdest, um die Extension
  // in unserer Pipeline zu registrieren. whateverGlobal ist der Name der globalen Variable,
  // die das Plugin exponiert. Sie akzeptiert eine einzelne (md)-Variable, die dann verwendet wird,
  // um die Pipeline zu erweitern
  helper.registerPlugin(window.whateverGlobal);
}

Immer Tests durchführen

Discourses bin/rake autospec ist plugin-fähig :innocent:

Das bedeutet, dass jedes Mal, wenn du die Datei spec/pretty_text_spec.rb speicherst, die Plugin-Testdatei ausgeführt wird.

Ich nutze dies intensiv, da es die Arbeit so viel schneller macht.

Angenommen, du hast ein Plugin hinzugefügt, das jede Zahl in einem Beitrag in einen „8-Kreis“ ändert; du könntest es discourse-magic-8-ball nennen.

So würde ich die Tests strukturieren:

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

Du musst möglicherweise „Posts dekorieren“

In einigen Fällen funktionieren Plugins am besten, wenn sie deinen Posts zusätzliche „dynamische“ Funktionen hinzufügen. Beispiele dafür sind das poll-Plugin oder das footnotes-Plugin, das ein „…“ hinzufügt, das dynamisch einen Tooltip anzeigt.

Wenn du Posts „dekorieren“ musst, füge assets/javascripts/api-initializers/your-initializer.js hinzu.

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) => {
    // dein großartiger Zauber passiert hier
  });
});

Du musst möglicherweise Posts „nachverarbeiten“

In einigen Fällen musst du Posts möglicherweise „nachverarbeiten“. Die Markdown-Rendering-Engine ist per Design nicht über bestimmte Informationen wie z. B. post_id informiert. In manchen Fällen benötigst du serverseitigen Zugriff auf den Beitrag und den „cooked“ HTML-Code; dies kann dir Dinge ermöglichen, wie das Auslösen von Hintergrund-Jobs, synchronisierten benutzerdefinierten Feldern oder das „Korrigieren“ automatisch generierten HTML-Codes.

Für Fußnoten benötigte ich eine eindeutige id für jede Fußnote, was bedeutete, dass ich Zugriff auf die post_id brauchte. Daher war ich gezwungen, Änderungen am HTML-Code im Post-Processor (der in Sidekiq läuft) vorzunehmen.

Um sich dort einzuhängen, fügst du Folgendes in deine plugin.rb-Datei ein:

DiscourseEvent.on(:before_post_process_cooked) do |doc, post|
  doc.css("a.always-bing").each do |a|
    # dies sollte immer zu bing führen
    a["href"] = "https://bing.com"
  end
end

Du benötigst möglicherweise etwas benutzerdefiniertes CSS

Wenn du benutzerdefiniertes CSS ausliefern möchtest, stelle sicher, dass du die Datei in plugin.rb registrierst.

Füge dein CSS in assets/stylesheets/magic.scss hinzu und führe dann aus:

register_asset "stylesheets/magic.scss"

Denke daran, dass wir Änderungen „automatisch neu laden“, sodass du dein Plugin-CSS ändern und die Änderungen in der Entwicklung sofort sehen kannst.

Viel Erfolg bei deinen Repackaging-Abenteuern :four_leaf_clover:


Dieses Dokument wird versionskontrolliert verwaltet – schlage Änderungen auf Github vor.

29 „Gefällt mir“

Ein Beitrag wurde in ein neues Thema verschoben: Kann Markdown durch Quarkdown ersetzt werden