DiscoTOC - فهرس محتويات تلقائي

[Discourse]

	ملخص	سيسمح لك DiscoTOC بإنشاء فهرس تفاعلي لمحتويات مواضيعك بنقرة واحدة!
	معاينة	معاينة على منشئ سمات Discourse
	رابط المستودع	https://github.com/discourse/DiscoTOC
	جديد في سمات Discourse؟	دليل المبتدئين لاستخدام سمات Discourse

تثبيت مكون السمة هذا

نظرًا لأن هذا مكون سمة #رسمي يتم صيانته بواسطة فريق Discourse، يمكن تقديم طلبات #الدعم، و#المساهمة:أخطاء، و#المساهمة:تجربة_المستخدم، و#المساهمة:ميزات في الفئات المناسبة هنا على Meta، مع وضع علامة مكون السمة المناسب. انقر على رابط أدناه لبدء طلب.

 الدعم  أخطاء  تجربة المستخدم  ميزات

عينات

سطح المكتب

جوال

الميزات

toc = فهرس المحتويات

• يولد الفهرس بالكامل تلقائيًا عبر زر في قائمة إعدادات محرر المنشورات

• سيظهر الفهرس دائمًا على الشاشة - يتحرك مع المحتوى مثل عنصر تقدم الموضوع

• أثناء التمرير عبر الأقسام في الموضوع، سيتم تعيين العنصر النشط في فهرس المحتويات ليكون نشطًا (تمييز أزرق)

• كل إدخال في الفهرس يربط إلى نقطة الارتساء الخاصة بالترويسة، لذا يمكنك أيضًا ربط قسم معين من موضوع آخر أو منشور

• النقر على أي رابط في الفهرس سيوجه المتصفح للتنقل إلى القسم ذي الصلة (تمرير سلس)

• في المواضيع التي تحتوي على ردود، زر المحتويات / الجدول الزمني يسمح للقراء بالتبديل بين الفهرس والجدول الزمني العادي للموضوع. يتم حفظ الاختيار في المتصفح

• يعمل مع إضافة Discourse Docs

• دعم اختياري لفهارس المحتويات في الردود، وليس فقط في المنشور الأول

• دعم اللغات من اليمين إلى اليسار (RTL)

كيف يعمل؟

باختصار، يبحث عن الترويسات في المواضيع التي تم وضع علامة عليها لإنشاء فهرس (عبر زر المحرر) وإذا اتضح أن الموضوع الحالي معتمد، فإنه يأخذ جميع الترويسات ويضعها في الفهرس (متداخلة حسب مستويات الترويسات) - هذا يعني أن تنسيق Markdown الخاص بك يجب أن يكون صحيحًا نحويًا.

# الترويسة 1
## الترويسة 2
### الترويسة 3
#### الترويسة 4
##### الترويسة 5

أنت حر في العودة والتقدم في مستويات الترويسات، ولكن يجب أن يكون الترتيب صحيحًا

# الترويسة 2
## الترويسة 3
## الترويسة 3
### الترويسة 4
## الترويسة 3
# الترويسة 2

إلخ...

بعض الأشياء التي يجب معرفتها حول الترويسات المتوافقة

• يتم تضمين h1 إلى h5. h6 غير مدرج
• يتم تجاهل الترويسات داخل الاقتباسات، لذا لن تلوث الاقتباسات الفهرس
• يظهر الفهرس فقط إذا كان المنشور يحتوي على عدد من الترويسات يساوي على الأقل إعداد الحد الأدنى لترويسات الفهرس (3 افتراضيًا)

كيف تعمل الروابط في الفهرس؟

تحتوي كل ترويسة في منشور مطبوخ على نقطة ارتساء على شكل p-<معرف المنشور>-<معرّف الترويسة>-<الرقم> — وهي الهدف خلف ترويسة a. يربط DiscoTOC إلى نقاط الارتساء هذه بدلاً من اختراع نقاط خاصة به.

لأن نقاط الارتساء هذه تتضمن موضع الترويسة في المنشور، فإنها تتغير إذا أعدت ترتيب الترويسات أو غيرت عناوينها. إذا كنت تربط إلى أقسام من مكان آخر، يمكنك إضافة نقاط ارتساء مسماة مستقرة فوق الترويسة:

<div><a name="my-section"></a></div>
## قسم الخاص بي

ثم اربط إلى /t/your-topic-slug/1234#my-section. يسمح Discourse بـ <a name="..."> في المنشورات. ستستخدم إدخالات DiscoTOC الخاصة بهما لا تزال نقاط الارتساء الأساسية للترويسات، لكن نقاطك ستستمر في العمل بغض النظر عن التعديلات.

الإعدادات

الاسم	الوصف
الحد الأدنى لمستوى الثقة لإنشاء فهرس	يجب أن يكون لديك لرؤية زر الفهرس في المحرر
نص فهرس المحرر	النص الذي يظهر في المحرر للإشارة إلى أن الموضوع سيحتوي على فهرس محتويات
فئات الفهرس التلقائي	تفعيل الفئات تلقائيًا
علامات الفهرس التلقائي	تفعيل الفهرس تلقائيًا على المواضيع التي تحتوي على هذه العلامات
تمكين الفهرس للردود	يسمح بإنشاء الفهرس للردود. لا تتأثر فهارس الردود بإعدادات علامات الفهرس التلقائي وفئات الفهرس التلقائي ويجب إدراجها يدويًا
الحد الأدنى لترويسات الفهرس	الحد الأدنى لعدد الترويسات في الموضوع ليظهر فهرس المحتويات

نص فهرس المحرر هو ما يظهر في معاينة المحرر للإشارة إلى أن الفهرس سيتم إنشاؤه:

الترجمات

الترجمة	الافتراضي
table_of_contents	فهرس المحتويات
insert_table_of_contents	إدراج فهرس المحتويات
jump_bottom	الانتقال إلى النهاية
toggle_toc.show_timeline	الجدول الزمني
toggle_toc.show_toc	المحتويات

table_of_contents: "فهرس المحتويات"

يُستخدم هذا للزر الذي يفتح الفهرس على الجوال

insert_table_of_contents: "إدراج فهرس المحتويات"

يُستخدم هذا كنص لزر الفهرس في قائمة إعدادات المحرر

toggle_toc.show_toc: "المحتويات"
toggle_toc.show_timeline: "الجدول الزمني"

هذه تسميات الزر الذي يبدل بين فهرس المحتويات والجدول الزمني للموضوع

كيف أنشئ فهرسًا؟

1. اكتب موضوعًا بترويسات صحيحة نحويًا
2. انقر على زر الفهرس في قائمة إعدادات المحرر. بشكل افتراضي يظهر فقط في المنشور الأول للموضوع؛ فعّل إعداد تمكين الفهرس للردود لاستخدامه في الردود أيضًا
3. استمتع بالنتيجة.

ماذا يحدث لعنصر تقدم الموضوع عندما يحتوي الموضوع على فهرس؟

لا يوجد مساحة لإظهار الاثنين في نفس الوقت، لذا في موضوع يحتوي على فهرس، يتم إخفاء عنصر تقدم الموضوع أثناء وجودك في المنشور الأول، وتظهر الفهرس بدلاً منه. بمجرد التمرير عبر المنشور الأول، يتم استبدال الفهرس بعنصر تقدم الموضوع العادي أثناء قراءة الردود. (مع تفعيل تمكين الفهرس للردود، يظهر رد يحتوي على فهرس خاص به بدلاً من ذلك.)

في المواضيع التي تحتوي على أكثر من منشور واحد، زر المحتويات / الجدول الزمني يسمح للقراء بالتبديل بين الاثنين، ويتم حفظ التفضيل في متصفحاتهم.

على الشاشات الضيقة، يفتح الفهرس كتراكب عبر زر في منطقة تقدم الموضوع.

هل هناك أي سلبيات لاستخدام هذا المكون؟

تحدث معظم الأشياء على جانب العميل، لذا يمكنك إزالة المكون في أي وقت وستظهر منشوراتك كما كانت من قبل. الشيء الوحيد الذي يمس محتواك هو زر المحرر: يلف المنشور في علامة <div data-theme-toc="true">، وهو كيف يعرف المكون أن المنشور يجب أن يحتوي على فهرس. إذا قمت بإلغاء تثبيت المكون، تبقى هذه العلامة في المنشور ولكن ليس لها تأثير مرئي.

القيود

لا يتم تضمين ترويسات h6 والترويسات داخل الاقتباسات في الفهرس.

الاعتماد

بدأ هذا كشوكة قوية لمكتبة Greg Franko tocify.js، وتم إعادة كتابته منذ ذلك الحين كمكونات Ember أصلية. لا توجد تبعيات خارجية أو طلبات.

شكر كبير لـ @erlend_sh على الكثير من الملاحظات القيمة ولـ @david لمساعدته في الترجمات.

نستضيف لك؟ مكونات السمات متاحة للاستخدام في خططنا Pro و Business و Enterprise.

[mentalstring (Paulo)]

لا أعرف كيف يتم تنفيذ هذه المكونة ولا الكثير عن هيكل الواجهة الأمامية لـ Discourse، لذا يمكنني فقط تقديم تخمين.

@tobiaseigen

لذا فإن عرض كليهما في نفس الوقت غير عملي بعض الشيء.

ألا يمكن عرض شريط التقدم فقط أ) إذا كان هناك أكثر من مشاركة واحدة في الموضوع و ب) تعديل بدايته لتبدأ من المشاركة الثانية (بدلاً من الثالثة)، ولكن أيضًا ج) إضافة هامش سفلي/علوي مريح لأحد العنصرين للتأكد من أن الآخر يظل بعيدًا بما فيه الكفاية (مثل 1vh) حتى لا يبدو غريبًا؟

بعبارة أخرى، بدلاً من استخدام المشاركة الثانية بأكملها كفجوة، استخدم CSS للسماح ببعض المساحة بينهما (إذا كان هناك أكثر من مشاركة واحدة).

مرة أخرى، قد لا يكون لهذا أي معنى على الإطلاق لأنني لا أعرف الكثير عن الطريقة التي يعمل بها هذا في الوقت الحالي.

[AndyB (Andy Benditt)]

مرحباً! لقد قمنا مؤخراً بتثبيت DiscoTOC لمنتدياتنا وكنا نتساءل عما إذا كان من الممكن جعل المكون يقرأ النص البديل (alt text) في الصور؟ لقد استخدمنا صوراً لبعض رؤوس ملاحظات الإصدار…

على هذا النحو:

وللأسف، لا يبدو أن نظام جدول المحتويات (TOC) قادر على تحليل صورة كرأس، مما يؤدي إلى إنشاء إدخال فارغ في القائمة وإنشاء رابط يأخذك إلى صفحة فارغة. هل هناك أي حل بديل لهذا بخلاف “عدم استخدام الصور”؟ شكراً جزيلاً! نحن نحب النظام بخلاف ذلك.

[simon]

@AndyB

لقد قمنا مؤخرًا بتثبيت DiscoTOC لمنتدياتنا وكنا نتساءل عما إذا كان من الممكن جعل المكون يقرأ النص البديل (alt text) في الصور؟

تخميني هو أن الحل هو عدم استخدام الصور كعناوين، ولكن ربما ستكون هناك طريقة لجعلها تعمل عن طريق إضافة بعض الأكواد إلى موقعك تتصل بكود DiscoTOC. ما إذا كان الأمر يستحق البحث في ذلك سيعتمد على مدى أهمية استخدام الصور في عناوين المشاركة بالنسبة لك.

[AndyB (Andy Benditt)]

لقد كنا نستخدم الصور كعناوين في ملاحظات الإصدار الخاصة بنا باستمرار لفترة طويلة، وهي جزء من علامتنا التجارية وعرضنا التقديمي؛ ليس فقط في المنتديات، ولكن على ستيم وما شابه ذلك أيضًا. نود أن تكون لدينا القدرة على الاستمرار في استخدام الصور كعناوين أثناء استخدام DiscoTOC للحفاظ على الاتساق.

لقد كان DiscoTOC رائعًا لأشياء أخرى مثل ملخص لأسئلة وأجوبة (AMA)، ومنشور شامل حول تطبيقنا المشغل للخوادم المخصصة، وأدلة اللاعبين الجدد، وما إلى ذلك. نحن نحب النظام كثيرًا، ولكننا نرغب في الحصول على وظيفة إضافية بسيطة للطريقة التي نقدم بها ملاحظات الإصدار.

[TheOctopus]

تعمل وظيفة مرساة العنوان (heading anchor) في هذا المكون على التعارض قليلاً مع وظيفة روابط العنوان التلقائية (Automatic header links) المضافة في 2.7.0beta6، حيث تحصل العناوين على أيقونتين عند التمرير فوقها، واحدة من Discourse والأخرى من DiscoTOC. هل هناك طريقة لتجاوز هذا؟

[Don]

مرحباً،

يمكنك إخفاء مرساة Automatic header links باستخدام

.anchor {
  display: none;
}

[neo (R.Zhang)]

مرحباً dodesz،

لقد جعلت عرض المنشور أكبر بكثير من الافتراضي، وبعد تثبيت هذا المكون يبدو شكله خاطئًا، هل يمكنك إخباري بكيفية إصلاح هذه المشكلة؟

شكراً!

[fkohrt]

على منتدى يعمل بإصدار Discourse 2.8.0.beta4 (90232af778)، يؤدي تضمين مكون DiscoTOC إلى ظهور رسالة خطأ:

تم تنشيط المكون سابقًا وأثار مشكلة مع إصدار Discourse المثبت مسبقًا أيضًا، على الرغم من أنني لا أستطيع تحديد الإصدار الذي كان عليه.

[simon]

هل يمكنك العثور على أي رسائل خطأ متعلقة بالمشكلة في سجلات أخطاء موقعك؟

[Falco]

رسالة الخطأ تلك هي خطأ في الواجهة الخلفية (backend)، بينما DiscoTOC هو مكون سمة للواجهة الأمامية (front-end)، لذا من الصعب أن يكونا مرتبطين. هل لديك أي إضافات (plugins) مثبتة؟

[fkohrt]

@simon

هل يمكنك العثور على أي رسائل خطأ متعلقة بالمشكلة في سجلات أخطاء موقعك؟

للأسف، لم أتمكن من العثور على أي شيء مفيد في /logs.

@Falco

هل لديك أي إضافات (plugins) مثبتة؟

لدي، إليك المقتطف ذي الصلة من app.yml:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager.git
          - git clone https://github.com/discourse/discourse-openid-connect.git
          - git clone https://github.com/discourse/discourse-checklist.git
          - git clone https://github.com/discourse/discourse-push-notifications.git
          - git clone https://github.com/discourse/discourse-characters-required.git
          - git clone https://github.com/angusmcleod/discourse-news.git
          - git clone https://github.com/discourse/discourse-data-explorer.git
          - git clone https://github.com/DNOeV/discourse-watch-category.git
          - git clone https://github.com/discourse/discourse-footnote.git
          - git clone https://github.com/discourse/discourse-knowledge-explorer.git

[debryc (Deborah Chang)]

عندما يكون العنوان داخل اقتباس، لا يظهر العنوان في جدول المحتويات. هل يمكن تغيير هذا السلوك؟

هذا العنوان لن يظهر في جدول المحتويات

محتوى مقتبس

هذا العنوان يظهر في جدول المحتويات

محتوى مقتبس

[Jagster (Jakke Flemming)]

لا أعرف كيف من المخطط أن يعمل، ولكن عادةً لا، لأنه جزء من الاقتباس، وليس عنوانًا لذلك النص.

[JammyDodger]

هل يمكنك المحاولة باستخدام وسم HTML <blockquote> بدلاً من ذلك؟ سيسمح ذلك للعنوان # بأن يكون في بداية السطر.

مثال:

<blockquote>

### عنوان المرساة
 
</blockquote>

عنوان المرساة

لم أجربه في جدول المحتويات (TOC)، ولكنه يبدو أنه يعمل مع العناوين ذاتية الربط في منشور عادي.

[tobiaseigen]

لماذا تريد أن تظهر العناوين داخل علامات الاقتباس في جدول المحتويات؟ ما هي حالة الاستخدام الخاصة بك؟

[debryc (Deborah Chang)]

@JammyDodger

هل يمكنك محاولة استخدام وسم HTML <blockquote> بدلاً من ذلك؟ سيسمح ذلك بظهور العنوان # في بداية السطر.

شكرًا لك على الفكرة. لكنها لم تنجح معي.

@tobiaseigen

لماذا تريد أن تظهر العناوين داخل الاقتباسات في جدول المحتويات (TOC)؟ ما هي حالة الاستخدام الخاصة بك؟

إليك مثال على متى أستخدم الاقتباسات لتنظيم المحتوى بصريًا بدءًا من منطقة المشكلة: العمر

A Progressive's Style Guide: Toward Harnessing Language in Support of...

[Jagster (Jakke Flemming)]

لماذا تستخدم الاقتباس بهذه الطريقة؟ إخبار المصدر يكفي. بالإضافة إلى أن هذا خطأ نحويًا، حتى في اللغة الإنجليزية.

[Jagster (Jakke Flemming)]

هل هذه مشكلة (bug) أم مجرد مستخدم آخر، ولكن… كيف يجب أن أغلق جدول المحتويات (TOC)؟ كنت أبحث عن بعض التعليمات الأساسية حول كيفية استخدام الرسائل الخاصة من قبل المستخدم النهائي وبالطبع ذهبت إلى وثيقة المستخدمين الجدد وفتحت جدول المحتويات لمعرفة ما إذا كان هناك أي معلومات.

كنت أستخدم جهاز iPad وDiscourseHub.

لقد حصلت على هذا:

جدول المحتويات جيد تمامًا. لكنه يتداخل مع النص ولم أتمكن من إخفائه مرة أخرى. فما الخطأ الذي ارتكبته بحق الجحيم، أو لم أرتكب أي خطأ على الإطلاق