Переупаковка расширения markdown-it в плагин Discourse

markdown.it — движок CommonMark, используемый Discourse, поддерживает широкий спектр плагинов.

Якоря заголовков, списки определений, умные стрелки и многое другое.

Предупреждение

:warning: CommonMark задуман как общий стандарт. Чем дальше вы отходите от спецификации, тем менее «общим» становится ваш Markdown. Это может усложнить портирование на другие решения и, если проявить невнимательность, привести к внутренним несоответствиям при парсинге. Прежде чем повторно упаковывать что-либо, убедитесь, что вы действительно хотите это сделать.

Я только что закончил повторную упаковку плагина Discourse Footnote и хотел бы поделиться опытом о том, как это сделать правильно.

Шаги для ленивых

Если вам лень разбираться и вы хотите просто начать, самый простой способ — форкнуть плагин footnotes и поменять файлы и имена переменных. Я постарался убедиться, что он следует лучшим практикам, так что у вас будет хороший пример.

Начальные шаги, минимальная переупаковка

Насколько я могу судить, большинство плагинов для markdown.it поставляются как обычные js-файлы. Часто плагины представляются всего одним js-файлом, например: markdown-it-mark.js.

В идеале следует оставить оригинал нетронутым, то есть вы можете просто скопировать обновленную версию файла в свой плагин, не изменяя существующий код.

Первая проблема, с которой вы столкнетесь, заключается в том, что нужно научить ваш плагин загружать этот JavaScript на сервере, так как движок Markdown работает также на сервере. Для этого просто скопируйте файл как есть в assets/javascripts/vendor/original-plugin.js, а затем в вашем файле plugin.rb добавьте:

# этот код обучает наш движок markdown загружать ваш обычный js-файл
register_asset "javascripts/vendor/original-plugin.js", :vendored_pretty_text

После того как тело плагина включено, вам нужно научить наш конвейер (pipeline) загружать и инициализировать его:

Создайте файл assets/javascripts/lib/discourse-markdown/your-extension.js

Этот файл будет автоматически загружен, потому что он заканчивается на .js И находится в директории discourse-markdown.

Простой пример:

export function setup(helper) {
  // позволяет загружать расширение только если включена настройка сайта
  helper.registerOptions((opts, siteSettings) => {
    opts.features["your-extension"] = !!siteSettings.enable_my_plugin;
  });

  // разрешите любые атрибуты, которые нужно поддерживать,
  // иначе наш санитайзер их удалит
  helper.allowList(["div.amazingness"]);

  // можно также делать сложные вещи, например так
  helper.allowList({
    custom(tag, name, value) {
      if ((tag === "a" || tag === "li") && name === "id") {
        return !!value.match(/^fn(ref)?\d+$/);
      }
    },
  });

  // наконец, это магия, которую вы используете для регистрации расширения в
  // нашем конвейере. whateverGlobal — это имя глобальной переменной, которую предоставляет плагин
  // он принимает одну переменную (md), которая затем используется для изменения конвейера
  helper.registerPlugin(window.whateverGlobal);
}

Всегда пишите тесты

bin/rake autospec в Discourse поддерживает плагины :innocent:

Это означает, что когда вы добавите файл spec/pretty_text_spec.rb, тесты плагина будут запускаться при каждом сохранении.

Я активно это использую, так как это значительно ускоряет работу.

Допустим, вы добавили плагин, который заменяет каждое число в сообщении на 8-шар, назовите его discourse-magic-8-ball.

Вот как я структурировал бы тесты:

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

Возможно, вам придется «декорировать» сообщения

В некоторых случаях плагины лучше всего работают, когда они добавляют дополнительные «динамические» функции к вашим сообщениям. Примерами могут служить плагин poll или плагин footnotes, который добавляет «…» для динамического показа всплывающей подсказки.

Если вам нужно «декорировать» сообщения, добавьте 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) => {
    // ваше удивительное волшебство здесь
  });
});

Возможно, вам потребуется «постобработка» сообщений

В некоторых случаях может потребоваться «постобработка» сообщений. Движок рендеринга Markdown по дизайну не осведомлен о некоторой информации, например, о post_id. В некоторых случаях вам может потребоваться доступ к сообщению и «приготовленному» (cooked) HTML на стороне сервера, что позволит выполнять такие задачи, как запуск фоновых заданий, синхронизация пользовательских полей или «исправление» автоматически генерируемого HTML.

Для сносок мне нужен был уникальный id для каждой сноски, что означало необходимость доступа к post_id, поэтому мне пришлось изменять HTML в постпроцессоре (который выполняется в sidekiq).

Для подключения добавьте следующее в ваш файл plugin.rb:

DiscourseEvent.on(:before_post_process_cooked) do |doc, post|
  doc.css("a.always-bing").each do |a|
    # эта ссылка всегда должна вести на bing
    a["href"] = "https://bing.com"
  end
end

Возможно, вам понадобится пользовательский CSS

Если вы хотите поставлять пользовательский CSS, обязательно зарегистрируйте файл в plugin.rb

Добавьте ваш CSS в assets/stylesheets/magic.scss, а затем выполните

register_asset "stylesheets/magic.scss"

Помните, что мы выполняем «автоперезагрузку» изменений, поэтому вы можете править CSS плагина и видеть изменения на лету в режиме разработки.

Удачи в ваших приключениях с переупаковкой :four_leaf_clover:


Этот документ находится под контролем версий — предлагайте изменения на github.

29 лайков

Пост был разделён на новую тему: Можно ли заменить Markdown на Quarkdown