ساختار دورتر از قرارداد سفر میکند
## Installation در همهٔ رندرکنندههای CommonMark به عنوان یک عنوان ATX سطح دو شناخته میشود. Installation و پس از آن خطی از خطتیرهها، یک عنوان Setext سطح دو است. این توافق دربارهٔ ساختار سند است.
قطعهٔ پس از # در یک URL به ناوبری HTML تعلق دارد. یک رندرکننده ممکن است عنوان را به حروف کوچک تبدیل کند، علائم نگارشی را حذف کند و فاصلهها را با خطتیره جایگزین کند، اما مشخصات هستهٔ Markdown آن الگوریتم را الزامی نمیکند. موردهای دشوار این شکاف را آشکار میکنند:
| عنوانهای قابل مشاهده | پرسشهایی که میزبان باید پاسخ دهد |
|---|---|
Café & crème | یونیکد حفظ شود، علائم دیاکریتیک تجزیه شوند، یا اصلِ متن کدگذاری شود؟ |
Install! و Install | آیا تفاوتهای علائم نگارشی از اسلاگسازی جان سالم به در میبرند؟ |
سه نسخه از Usage | پسوند -1 است، -2، _2، یا چیز دیگری؟ |
دو ابزار Markdown منطبق با استاندارد میتوانند پاسخهای متفاوتی بدهند، چون تجزیهٔ عنوان و تولید شناسهٔ خودکار دو کار جداگانهاند.
بلوکها را پیش از اسکن کردن علامتهای # تجزیه کنید
خطی که با ## شروع میشود لزوماً عنوان سند نیست. درون یک بلوک کد حصاردار، محتوای نمونهٔ تحتاللفظی است. متنی که با چهار فاصله تورفته باشد هم کد است. مرحلهٔ بلوکِ CommonMark به همین دلیل مقدم است: ابتدا تعیین کنید کد و بلوکهای دیگر کجا هستند، سپس نحو عنوان را در ساختار باقیمانده تفسیر کنید.
پیش از ادامهٔ مطلب
یک README درون یک نمونهٔ shell در بلوک کد حصاردار، `## Delete everything` دارد. آیا اسکنر فهرست مطالب باید به آن پیوند بدهد؟
نه. اسکنر باید پیش از تفسیر نشانگرهای عنوان، کد حصاردار و کد تورفته را دنبال کند. در غیر این صورت نمونههای مستندات به مدخلهای ناوبری نادرست تبدیل میشوند.
سازندهٔ فهرست مطالب Markdown همین ترتیب را رعایت میکند و زیرمجموعهٔ پشتیبانیشدهاش را منتشر میکند. خود را رندرکنندهای جهانی برای هر افزونه نمینامد.
هر دو سر پیوند را صریح کنید
یک <a id="install"></a> که نویسنده نوشته، مقصد را خودش تأمین میکند به جای آنکه از میزبان بخواهد یکی بسازد. فهرست تولیدشده میتواند دقیقاً به #install پیوند بدهد، و شناسههای تکراری را میتوان پیش از آنکه سند از ابزار خارج شود حل کرد.
این قابلیت حمل را بهتر میکند، اما جادو نیست. HTML خام در CommonMark مجاز است و همچنان میتواند توسط پاکساز یک سایت حذف شود. گردش کار صادقانه این است که سیاست مقصد را بدانید، هر جا که اجازه میدهد شناسههای صریح تولید کنید، و پیش از اعمال این قرارداد در همهجا، یک سند منتشرشده را پیشنمایش کنید.
متن تولیدشده باید قابل بازرسی و قابل جایگزینی باشد
تولیدکننده به مرزهای مالکیت نیاز دارد. کامنتهای آغاز و پایان، جدولی را مشخص میکنند که بعداً میتواند جایگزینش کند؛ خطهای لنگرِ نشانهگذاریشده، مقصدهایی را مشخص میکنند که مالک آنهاست. HTML بدون نشانه از آنِ نویسنده میماند. این کار بازتولید را ایدمپوتنت (تکرارپذیر بدون اثر جانبی) میکند، بیآنکه «جدول قدیمی را حذف کن» به یک قاعدهٔ اکتشافیِ حذفِ گسترده تبدیل شود.
سازندهٔ دیف متن نیمهٔ دوم آن انضباط را فراهم میکند. منبع و خروجی را با سه خط زمینه مقایسه کنید تا جدول و لنگرها را در جای خود ببینید، یا با زمینهٔ صفر تا فقط خطهای درجشده جدا شوند. یک ابزار سادهٔ خط برای مرتبسازی محتوا مفید است، اما سلسلهمراتب عنوانهای سند را حفظ نمیکند و نباید به عنوان تجزیهکنندهٔ Markdown به کار رود.
پرسشهای رایج
آیا CommonMark لنگرهای عنوان به سبک GitHub را تعریف میکند؟
نه. CommonMark عنوانها و پیوندها را تعریف میکند، در حالی که شناسههای خودکار به سبک GitHub قراردادِ رندرکنندهاند. میزبان دیگری میتواند از همان عنوانِ قابل مشاهده قطعهٔ متفاوتی تولید کند.
آیا لنگرهای صریح HTML در Markdown معتبرند؟
CommonMark بلوکهای HTML خام و HTML درونخطی را مجاز میداند، و یک `id` در HTML میتواند مقصد قطعه باشد. یک سرویس انتشار همچنان میتواند آن HTML را به عنوان سیاست محصول یا امنیت پاکسازی کند.
چگونه بازبینی کنم که یک تولیدکننده چه چیزی را تغییر داده است؟
Markdown اصلی و تولیدشده را خط به خط مقایسه کنید. یک دیف یکپارچه (unified diff) هر خط جدول، نشانگر و لنگر درجشده را نمایان میکند بیآنکه از شما بخواهد نثر تغییرنکرده را دوباره بخوانید.