markdown.it هو محرك CommonMark المستخدم في Discourse ويتوفر له مجموعة واسعة من الإضافات
روابط رؤوس الفصول، قوائم التعريفات، الأسهم الذكية، والقائمة مستمرة على هذا المنوال.
تحذير أولاً
الغرض من CommonMark أن يكون مشتركاً وعاماً. كلما ابتعدت أكثر عن المواصفات، أصبح Markdown الخاص بك أقل “عالمية”. قد يجمل هذا الأمر صعوبة أكبر في نقله إلى حلول أخرى، وإذا لم تكن حذراً، فقد يسبب عدم اتساق داخلي عند التحليل. قبل أن تعيد تعبئة أي شيء، تأكد من الإجابة على السؤال: “هل أرغب حقاً في إعادة تعبئة هذا؟”
لقد انتهيت للتو من إعادة تعبئة Discourse Footnote، ولدي بعض الدروس لأشاركها حول كيفية فعل ذلك بشكل صحيح.
خطوات للمتكاسلين
إذا كنت تكاسل وتريد فقط البدء بأسهل طريقة، فإنها تتمثل في عمل نسخة (fork) من الإضافة footnotes وتبديل الملفات وأسماء المتغيرات. لقد كنت دقيقاً جداً لضمان اتباع أفضل الممارسات، لذا يجب أن تحصل على مثال متين.
الحركات الافتتاحية، إعادة تعبئة أساسية
من ما أستطيع أن أخمنه، فإن معظم إضافات markdown.it تُوزع كملفات js عادية (vanilla). في كثير من الحالات، تُوزع الإضافات ببساطة كملف js واحد، مثل هذا: markdown-it-mark.js.
من المثالي أن تترك الملف الأصلي سليماً، وهذا يعني أنه يمكنك ببساطة نسخ نسخة محدثة من الملف إلى الإضافة الخاصة بك دون الحاجة إلى العبث بالإضافة الموجودة.
المشكلة الأولى التي ستواجهها هي أنك يجب أن تعلم الإضافة الخاصة بك كيفية تحميل هذا الـ JavaScript على الخادم، لأن محرك Markdown يعمل أيضاً على الخادم. للقيام بذلك، يمكنك ببساطة نسخ الملف كما هو إلى assets/javascripts/vendor/original-plugin.js، ثم في ملف plugin.rb الخاص بك، تضيف:
# هذا يعلم محرك الـ markdown الخاص بنا تحميل ملف الـ vanilla 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;
});
// اسمح بأي سمات (attributes) تحتاج إلى دعمها،
// وإلا فسيقوم مُعقّمنا (sanitizer) بإزالتها
helper.allowList(["div.amazingness"]);
// يمكنك أيضاً فعل أشياء متقدمة مثل هذا
helper.allowList({
custom(tag, name, value) {
if ((tag === "a" || tag === "li") && name === "id") {
return !!value.match(/^fn(ref)?\d+$/);
}
},
});
// أخيراً، هذا هو السحر الذي تستخدمه لتسجيل الإضافة في
// مسار المعالجة لدينا. whateverGlobal هو اسم المتغير العام (global) الذي تكشفه الإضافة
// ويأخذ متغيراً واحداً (md) يُستخدم بعد ذلك لتعديل مسار المعالجة
helper.registerPlugin(window.whateverGlobal);
}
اختبر دائماً
أداة bin/rake autospec في Discourse مدركة للإضافات ![]()
هذا يعني أنه عندما تضيف الملف spec/pretty_text_spec.rb، فستتم تشغيل ملف اختبار الإضافة في كل مرة تحفظ فيها الملف.
أستخدم هذا كثيراً لأنه يجعل العمل أسرع بكثير.
لنفترض أنك أضفت إضافة تغير كل رقم في المنشور إلى “كرة الرقم 8” (8-circle)، يمكنك تسميتها 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 التي تضيف “…” تعرض تلميحاً أداة (tooltip) ديناميكياً.
إذا احتجت إلى “تزيين” المنشورات، أضف 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 على سبيل المثال. في بعض الحالات، قد ترغب في وصول الخادم إلى المنشور و HTML “المُطبوخ” (cooked)، مما يسمح لك بفعل أشياء مثل تشغيل مهام في الخلفية، حقول مخصصة متزامنة أو “تصحيح” HTML المُولد تلقائياً.
بالنسبة للحواشي السفلية، احتجت إلى id مميز لكل حاشية سفلية، مما يعني أنني احتجت وصولاً إلى post_id، لذا اضطررت إلى إجراء تغييرات على HTML في المعالج اللاحق (post processor) (الذي يعمل في 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 للإضافة الخاصة بك ورؤية التغييرات على الفور أثناء التطوير.
حظاً موفقاً في مغامرات إعادة التعبئة الخاصة بك ![]()
هذا المستند مُدار بالإصدارات - اقترح التغييرات على github.