عنوانهای سند خود را به ناوبری تبدیل کنید
عنوانهای مارکداون را بیرون از بلوکهای کد پیدا کنید، به هر عنوان واردشده یک لنگر صریح و بدون تداخل بدهید و سند کامل را با یک فهرست مطالب تودرتوی قابلجایگزینی دانلود کنید.
مارکداون با فهرست مطالب
سند اصلی با یک بلوک تولیدشدهٔ قابلجایگزینی و لنگرهای صریح HTML پیش از عنوانها.
هر عنوان پیوندشده
| ۵ | ۲ | تجهیزات | تجهیزات |
| ۷ | ۳ | دوربین | دوربین |
| ۹ | ۲ | نتایج | نتایج |
| ۱۱ | ۳ | دوربین | دوربین-2 |
چگونگی کار
چرا لنگرهای صریح مهماند
CommonMark مشخص میکند عنوان ATX یا Setext چیست. مشخص نمیکند که ## Getting started باید به #getting-started تبدیل شود، و نه اینکه عنوان دومی با همان واژهها چگونه پسوند بگیرد. این انتخابها به رندرکنندهها و پلتفرمهای میزبانی تعلق دارند.
بنابراین سند تولیدشده هر دو سوی هر پیوند را در خود دارد:
- [Camera](#camera-2)
<!-- tessalor-toc:anchor --><a id="camera-2"></a>
### Camera
کامنت، لنگری را مشخص میکند که این ابزار ممکن است جایگزینش کند. id مقصد واقعی قطعهٔ HTML است. یک لنگر نامرتبط بدون آن نشانگر، محتوای نویسنده به حساب میآید و دستنخورده میماند.
عنوانها چگونه پیدا میشوند
اسکنر از بالا به پایین کار میکند. حصاری از دستکم سه بکتیک یا مد (~) یک بلوک کد را آغاز میکند؛ فقط حصاری با همان نویسه و دستکم همان طول آن را میبندد. خطوط درون آن هرگز عنوان به حساب نمیآیند. خطوطی با چهار فاصله یا یک تب در ابتدا، به همین دلیل کد تورفته تلقی میشوند.
بیرون از کد، یک تا شش نویسهٔ # در ابتدای خط و پس از آن فضای خالی، یک عنوان ATX میسازد. خط متنیای که پس از آن === یا --- بیاید، عنوان تکخطی Setext سطح ۱ یا سطح ۲ شناخته میشود. # های بستهٔ اختیاری در انتهای عنوانهای ATX از برچسب قابلمشاهده حذف میشوند.
این عمداً محدودتر از وانمود کردن به یک رندرکنندهٔ کامل مارکداون است. افزونههای مخصوص کانتینر و پاراگرافهای چندخطی Setext میتوانند رفتاری وابسته به تجزیهگر داشته باشند؛ این ابزار بیسروصدا وعدهٔ مدل کردن هر میزبانی را نمیدهد.
لنگرها چگونه ساخته میشوند
متن قابلمشاهدهٔ پیوندهای درونخطی و نشانگرهای سادهٔ تأکید به متنشان کاهش مییابند، سپس برچسب نرمالسازی یونیکد و کوچکسازی حروف میشود. نشانههای ترکیبی حذف میشوند، رشتهای از نویسههای غیر از حرف و عدد به یک خط تیره تبدیل میشود و خط تیرههای ابتدا و انتها ناپدید میشوند. عنوانی که فقط از علائم نگارشی ساخته شده به section بازمیگردد.
تشخیص تکراری پس از این نرمالسازی انجام میشود. Café & Crème و Cafe Creme هر دو با cafe-creme آغاز میشوند، بنابراین عنوان بعدی بهجای اینکه هر دو ورودی به بخش اول اشاره کنند، cafe-creme-2 میشود.
سند کارشده
سند پیشفرض یک عنوان اصلی و این عنوانهای واردشده را دارد:
| عنوان منبع | سطح | لنگر درجشده |
|---|---|---|
تجهیزات | ۲ | تجهیزات |
دوربین | ۳ | دوربین |
نتایج | ۲ | نتایج |
دوربین | ۳ | دوربین-2 |
با انتخاب سطحهای ۲ تا ۴، نتیجه ۴ عنوان پیوندشده، ۱ تکراری رفعشده و عمیقترین سطح واردشدهٔ ۳ است. فهرست پس از عنوان آغازین # یادداشت میدانی قرار میگیرد؛ ورودیهای تودرتوی سطح ۳ دو فاصله تورفتگی فهرست میگیرند.
از دیفساز متن برای بازبینی خطوط درجشده در برابر منبع استفاده کنید، یا وقتی پرسش دربارهٔ محتوای سند است — نه ناوبریاش — از شمارندهٔ واژه.
مراحل انجام کار
- پایان خطوط را یکسانسازی کنید و فقط بلوک کامل فهرست مطالب و خطوط لنگری را که پیشتر همین ابزار تولید کرده حذف کنید.
- خطوط را به ترتیب اسکن کنید، حصارهای بکتیک و مد (~) را دنبال کنید و کد تورفته با چهار فاصله یا تب را نادیده بگیرید، سپس عنوانهای ATX و Setext را تشخیص دهید.
- هر عنوان واردشده را به یک اسلاگ یونیکد با حروف کوچک ساده کنید، سپس هرگاه نامهای نرمالشده تداخل کنند پسوند شمارشی بیفزایید، یعنی ۲ برای دومی، ۳ برای سومی و همینطور تا آخر.
- لنگر دقیق HTML را پیش از هر عنوان واردشده درج کنید و یک فهرست تودرتوی نشانهگذاریشده را پس از عنوان آغازین سطح یک یا در ابتدای سند قرار دهید.
فرضها
- کمعمقترین سطح انتخابشده عمیقتر از بیشترین سطح انتخابشده نیست.
- اسکنر عنوانهای معمولی ATX و عنوانهای تکخطی Setext مطابق CommonMark را هدف میگیرد؛ یک رندرکنندهٔ کامل مارکداون با افزونههای خاص نیست.
- رندرکنندهٔ مقصد لنگرهای خام HTML را مجاز میداند. پلتفرمی که HTML نوشتهشده توسط نویسنده را حذف میکند، این مقصدهای صریح را هم حذف خواهد کرد.
- شناسههای HTML موجود بدون نشانگر و یک بلوک نشانگر تولیدشدهٔ ناقص، محتوای نویسنده تلقی میشوند و هرگز حذف نمیشوند.
پرسشهای رایج
آیا مارکداون شناسهٔ خودکار یک عنوان را تعریف میکند؟
خیر. مارکداون اصلی ساختار عنوان را تعریف میکند، اما اسلاگ قطعهٔ (fragment) تولیدشدهٔ میزبان را نه، و قواعد پسوند تکراریها متفاوت است. این ابزار شناسههای صریح مینویسد تا پیوندها و مقصدهایش بخشی از همان سند باشند.
آیا عنوانی که درون یک نمونهکد نشان داده شده وارد فهرست میشود؟
وقتی درون حصار بکتیک یا مد (~) یا یک بلوک کد تورفته باشد، خیر. اسکنر پیش از آزمودن اینکه یک خط نحو عنوان دارد یا نه، آن بلوکها را دنبال میکند.
آیا میتوانم پس از ویرایش عنوانها فهرست را دوباره بسازم؟
بله. فهرست تولیدشده کامنتهای آغاز و پایان دارد و هر لنگر تولیدشده نشانگر خودش را دارد. اجرای بعدی آن بخشهای نشانهگذاریشده را حذف میکند و یک نسخهٔ بهروز میسازد.
چرا ممکن است یک پیوند در یک پلتفرم انتشار کار نکند؟
برخی پلتفرمها HTML خام را پاکسازی میکنند و عناصر لنگر نوشتهشده را حذف میکنند. مارکداون همچنان خوانا میماند، اما مقصدهای صریح به رندرکنندهای نیاز دارند که HTML درونخطی معمولی را مجاز بداند.