| KRAMDOWN(1) | General Commands Manual | KRAMDOWN(1) |
نام (NAME)
kramdown - یک مبدل سریع و تمام‌روبی برای ابرمجموعه Markdown
خلاصه دستور (SYNOPSIS)
kramdown [options] [FILE...]
توضیحات (DESCRIPTION)
ابزار kramdown در درجه‌ی اول برای تجزیه (parse) یک ابرمجموعه از Markdown و تبدیل آن به قالب‌های خروجی مختلف استفاده می‌شود. این ابزار از Markdown استاندارد (با برخی اصلاحات جزئی) و افزونه‌های مختلفی مانند جدول‌ها و فهرست‌های تعاریف پشتیبانی می‌کند. به دلیل معماری پیمانه‌ای (ماژولار)، این ابزار قالب‌های ورودی دیگری به‌جز Markdown مانند HTML یا Github Flavored Markdown را نیز می‌پذیرد.
اگر FILE مشخص نشده باشد، kramdown از ورودی استاندارد می‌خواند. نتیجه در خروجی استاندارد نوشته می‌شود.
دو دسته گزینه وجود دارد که kramdown می‌پذیرد: دسته‌ی اول شامل گزینه‌هایی است که مستقیماً توسط باینری kramdown استفاده می‌شوند. دسته‌ی دوم گزینه‌ها نحوه تجزیه و تبدیل ورودی توسط kramdown را کنترل می‌کنند.
مقادیر پیش‌فرض برای این دسته‌ی دوم می‌توانند با استفاده از YAML از طریق فایل پیکربندی kramdownrc تنظیم شوند. توجه داشته باشید که نام گزینه‌های پیکربندی از زیرخط (underscore) استفاده می‌کنند، نه خط تیره (خط تیره‌ها فقط در نام گزینه‌های CLI استفاده می‌شوند)، و گزینه‌های بولی فاقد حالت no هستند و به جای آن مقدار true یا false می‌گیرند. این فایل در لینوکس/یونیکس باید در XDG_CONFIG_HOME، در macOS در ~/Library/Preferences و در ویندوز در ~/AppData/Local قرار داشته باشد.
گزینه‌های ویژه خط فرمان (CLI-ONLY OPTIONS)
- -i FORMAT, --input FORMAT
- قالب ورودی را مشخص می‌کند. قالب‌های ورودی موجود: kramdown (پیش‌فرض است)، markdown، یا html. قالب ورودی GFM از طریق جم kramdown-parser-gfm در دسترس است.
- -o FORMAT, --output FORMAT
- یک یا چند قالب خروجی جداشده با ویرگول را مشخص می‌کند: html (پیش‌فرض)، kramdown، latex، man یا remove_html_tags. مبدل pdf از طریق جم kramdown-converter-pdf در دسترس است.
- -x EXT, --extension EXT
- یک یا چند افزونه را بارگذاری می‌کند. نام افزونه نباید شامل پیشوند kramdown- باشد، برای مثال فقط parser-gfm. می‌توان چندین افزونه را با جدا کردن آن‌ها با ویرگول بارگذاری کرد.
نکته: این گزینه باید قبل از هر گزینه دیگری که متکی به بارگذاری قبلی افزونه است، استفاده شود.
- --no-config-file
- هیچ فایل پیکربندی‌ای را نمی‌خواند. رفتار پیش‌فرض این است که وجود فایل پیکربندی را بررسی کرده و در صورت وجود، آن را می‌خواند.
- --config-file FILE
- مسیر و نام پیش‌فرض فایل پیکربندی را دگرگون می‌کند.
- -v, --version
- نسخه‌ی kramdown را نمایش می‌دهد.
- -h, --help
- راهنما را نمایش می‌دهد.
گزینه‌های KRAMDOWN (KRAMDOWN OPTIONS)
- --auto-id-prefix ARG
- پیشوند مورد استفاده برای شناسه‌های (ID) سرآیند که به‌طور خودکار تولید می‌شوند
این گزینه می‌تواند برای تنظیم یک پیشوند برای شناسه‌های سرآیند تولیدشده به‌طور خودکار استفاده شود تا هنگام تبدیل جداگانه‌ی چندین سند kramdown درون یک فایل خروجی، تداخلی رخ ندهد. این پیشوند فقط باید شامل نویسه‌هایی باشد که در یک ID معتبر هستند!
پیش‌فرض: ‘’ استفاده‌شده توسط: مبدل HTML/Latex
- --[no-]auto-id-stripping
- حذف تمام قالب‌بندی‌ها از متن سرآیند برای تولید خودکار شناسه
اگر این گزینه true باشد، فقط عناصر متنی یک سرآیند برای تولید شناسه در ادامه استفاده می‌شوند (برخلاف استفاده از خط متنی خام سرآیند).
این گزینه در نسخه 2.0 حذف خواهد شد زیرا پس از آن به حالت پیش‌فرض تبدیل می‌شود.
پیش‌فرض: false استفاده‌شده توسط: تجزیه‌گر kramdown
- --[no-]auto-ids
- استفاده از تولید خودکار شناسه‌ی سرآیند
اگر این گزینه true باشد، در صورتی که شناسه‌ای به‌طور صریح مشخص نشده باشد، مقادیر شناسه برای تمام سرآیندها به‌طور خودکار تولید می‌شوند.
پیش‌فرض: true استفاده‌شده توسط: مبدل HTML/Latex
- --entity-output ARG
- نحوه درج نهادها (entities) در خروجی را تعیین می‌کند
مقادیر ممکن عبارتند از: :as_input (نهادها به همان شکلی که در ورودی یافت می‌شوند در خروجی درج می‌شوند)، :numeric (نهادها به شکل عددی در خروجی درج می‌شوند)، :symbolic (در صورت امکان نهادها به شکل نمادین در خروجی درج می‌شوند) یا :as_char (در صورت امکان نهادها به‌صورت نویسه در خروجی درج می‌شوند، تنها در Ruby 1.9 در دسترس است).
پیش‌فرض: :as_char استفاده‌شده توسط: مبدل HTML، مبدل kramdown
- --footnote-backlink ARG
- متنی را که باید برای پیوندهای بازگشتی پاورقی استفاده شود تعیین می‌کند
پیوند بازگشتی پاورقی صرفاً یک متن است، بنابراین هر نویسه‌ی خاص HTML گریز داده می‌شود (escaped).
اگر متن پیوند بازگشتی پاورقی یک رشته‌ی خالی باشد، هیچ پیوند بازگشتی برای پاورقی‌ها تولید نخواهد شد.
پیش‌فرض: ‘&8617;’ استفاده‌شده توسط: مبدل HTML
- --[no-]footnote-backlink-inline
- مشخص می‌کند که آیا پیوند بازگشتی پاورقی همیشه باید درون‌خطی (inline) باشد یا خیر
در حالت پیش‌فرض false، پیوند بازگشتی پاورقی در انتهای آخرین بند (در صورت وجود) قرار می‌گیرد، یا یک بند اضافی که تنها شامل پیوند بازگشتی پاورقی است ایجاد می‌شود.
تنظیم این گزینه روی true تلاش می‌کند پیوند بازگشتی پاورقی را در آخرین بند یا سرآیند (که احتمالاً تو در تو است) قرار دهد. در صورت عدم موفقیت (برای مثال در مورد یک جدول)، یک بند اضافی فقط حاوی پیوند بازگشتی پاورقی ایجاد می‌شود.
پیش‌فرض: false استفاده‌شده توسط: مبدل HTML
- --footnote-link-text ARG
- متن استفاده‌شده برای شماره‌ی پاورقی در پیوند پاورقی
این گزینه می‌تواند برای افزودن متن بیشتر به پیوند پاورقی استفاده شود. این مقدار باید یک رشته قالب‌بندی (format string) باشد و شماره‌ی پاورقی به‌عنوان تنها آرگومان به آن ارسال می‌شود؛ برای مثال “[footnote %s]” به‌صورت “[footnote 1]” نمایش داده خواهد شد.
پیش‌فرض: ‘%s’ استفاده‌شده توسط: HTML
- --footnote-nr ARG
- شماره‌ی اولین پاورقی
این گزینه می‌تواند برای مشخص کردن شماره‌ای که برای اولین پاورقی استفاده می‌شود به کار رود.
پیش‌فرض: 1 استفاده‌شده توسط: مبدل HTML
- --footnote-prefix ARG
- پیشوند مورد استفاده برای شناسه‌های پاورقی
این گزینه می‌تواند برای تنظیم یک پیشوند برای شناسه‌های پاورقی استفاده شود. این قابلیت هنگام تبدیل چندین سند درون یک فایل خروجی مشترک برای جلوگیری از شناسه‌های تکراری مفید است. این پیشوند فقط باید شامل نویسه‌هایی باشد که در یک ID معتبر هستند!
پیش‌فرض: ‘’ استفاده‌شده توسط: HTML
- --forbidden-inline-options ARG
- گزینه‌هایی را مشخص می‌کند که مجاز نیستند با افزونه {::options} تنظیم شوند
مقدار باید آرایه‌ای از نام گزینه‌ها باشد.
پیش‌فرض: [template] استفاده‌شده توسط: مبدل HTML
- --[no-]header-links
- تگ‌های لنگر (anchor tags) را درون سرآیندها اضافه می‌کند که می‌توانند هنگام عدم استفاده از فهرست مطالب برای تولید پیوندهای یکتا (permalinks) استفاده شوند.
تگ‌های لنگر خالی هستند، اما می‌توان بر اساس سلیقه آن‌ها را استایل‌دهی کرد.
پیش‌فرض: false
- --header-offset ARG
- میزان جابه‌جایی (offset) خروجی را برای سرآیندها تنظیم می‌کند
اگر این گزینه c باشد (ممکن است منفی نیز باشد)، آنگاه یک سرآیند با سطح n به‌صورت سرآیندی با سطح c+n در خروجی درج می‌شود. اگر c+n کمتر از 1 باشد، از سطح 1 استفاده خواهد شد. اگر c+n بزرگتر از 6 باشد، از سطح 6 استفاده خواهد شد.
پیش‌فرض: 0 استفاده‌شده توسط: مبدل HTML، مبدل Kramdown، مبدل Latex
- --[no-]html-to-native
- تبدیل عناصر HTML به عناصر بومی (native)
اگر این گزینه true باشد، تجزیه‌گر عناصر HTML را به عناصر محلی تبدیل می‌کند. برای مثال، هنگام تجزیه‌ی <em>hallo</em> تگ تأکید به‌طور معمول به یک عنصر :html با نوع تگ :em تبدیل می‌شود. اگر html_to_native برابر true باشد، آنگاه تأکید به یک عنصر بومی :em تبدیل خواهد شد.
این قابلیت برای مبدل‌هایی که نمی‌توانند با عناصر HTML کار کنند مفید است.
پیش‌فرض: false استفاده‌شده توسط: تجزیه‌گر kramdown
- --latex-headers ARG
- دستورات LaTeX را برای سطوح مختلف سرآیند تعیین می‌کند
دستورات مربوط به سطوح سرآیند یک تا شش را می‌توان با جدا کردن آن‌ها با ویرگول مشخص کرد.
پیش‌فرض: section,subsection,subsubsection,paragraph,subparagraph,subparagraph استفاده‌شده توسط: مبدل Latex
- --line-width ARG
- عرض خط مورد استفاده را هنگام نوشتن سند در خروجی مشخص می‌کند
پیش‌فرض: 72 استفاده‌شده توسط: مبدل kramdown --link-defs ARG تعریف از پیشِ تعاریف پیوند
این گزینه می‌تواند برای تعریف از پیشِ تعاریف پیوند (link definitions) استفاده شود. مقدار باید یک Hash باشد که در آن کلیدها، شناسه‌های پیوند و مقادیر، آرایه‌های دو عضوی (Array) شامل URL پیوند و عنوان پیوند هستند.
اگر مقدار یک String باشد، باید شامل یک هش معتبر YAML بوده و ساختار هش از رهنمودهای بالا پیروی کند.
پیش‌فرض: {} مورداستفاده در: تجزیه‌گر kramdown
- --list-indent ARG
- تنظیم تعداد فاصله‌ها برای تورفتگی فهرست
پیش‌فرض: 2 مورداستفاده در: تبدیل‌کنندهٔ Kramdown
- --math-engine ARG
- تنظیم موتور ریاضی
موتور ریاضی مورد استفاده برای تبدیل بلوک‌ها/محدوده‌های ریاضی (math blocks/spans) را مشخص می‌کند. اگر این گزینه روی +nil+ تنظیم شود، از هیچ موتور ریاضی‌ای استفاده نمی‌شود و بلوک‌ها/محدوده‌های ریاضی بدون تغییر در خروجی قرار می‌گیرند.
گزینه‌های مربوط به موتور ریاضیِ انتخاب‌شده را می‌توان با گزینهٔ پیکربندی math_engine_opts تنظیم کرد.
پیش‌فرض: mathjax مورداستفاده در: تبدیل‌کنندهٔ HTML
- --math-engine-opts ARG
- تنظیم گزینه‌های موتور ریاضی
گزینه‌های مربوط به موتور ریاضیِ تعیین‌شده از طریق گزینهٔ پیکربندی math_engine را مشخص می‌کند.
مقدار باید یک هش از جفت‌های کلید-مقدار باشد که برای موتور ریاضی مورد استفاده قابل فهم باشد.
پیش‌فرض: {} مورداستفاده در: تبدیل‌کنندهٔ HTML
- --[no-]parse-block-html
- پردازش نحو kramdown در تگ‌های بلوکی HTML
اگر این گزینه true باشد، تجزیه‌گر kramdown محتوای تگ‌های بلوکی HTML را به عنوان متنِ حاوی عناصر سطح-بلوک پردازش می‌کند. از آنجا که این رفتار معمولاً مطلوب نیست، مقدار پیش‌فرض false است. معمولاً بهتر است پردازش kramdown را به‌صورت گزینشی و از طریق صفت markdown فعال کنید.
پیش‌فرض: false مورداستفاده در: تجزیه‌گر kramdown
- --[no-]parse-span-html
- پردازش نحو kramdown در تگ‌های درون‌خطی (span) HTML
اگر این گزینه true باشد، تجزیه‌گر kramdown محتوای تگ‌های درون‌خطی HTML را به عنوان متنِ حاوی عناصر سطح-درون‌خطی (span-level) پردازش می‌کند.
پیش‌فرض: true مورداستفاده در: تجزیه‌گر kramdown
- --[no-]remove-block-html-tags
- حذف تگ‌های بلوکی HTML
اگر این گزینه true باشد، تبدیل‌کنندهٔ RemoveHtmlTags تگ‌های بلوکی HTML را حذف می‌کند.
پیش‌فرض: true مورداستفاده در: تبدیل‌کنندهٔ RemoveHtmlTags
- --[no-]remove-line-breaks-for-cjk
- مشخص می‌کند که آیا شکست‌های خط بین نویسه‌های CJK باید حذف شوند یا خیر
پیش‌فرض: false مورداستفاده در: تبدیل‌کنندهٔ HTML
- --[no-]remove-span-html-tags
- حذف تگ‌های درون‌خطی (span) HTML
اگر این گزینه true باشد، تبدیل‌کنندهٔ RemoveHtmlTags تگ‌های درون‌خطی HTML را حذف می‌کند.
پیش‌فرض: false مورداستفاده در: تبدیل‌کنندهٔ RemoveHtmlTags
- --smart-quotes ARG
- تعریف نام‌های موجودیت HTML یا نقاط کد برای خروجی علامت‌های نقل‌قول هوشمند
موجودیت‌هایی که با نام موجودیت (entity name) یا نقطه کد (code point) مشخص شده‌اند و باید به ترتیب برای نقل‌قول تکی چپ، نقل‌قول تکی راست، نقل‌قول دوتایی چپ و نقل‌قول دوتایی راست استفاده شوند، با کاما از یکدیگر جدا می‌شوند.
پیش‌فرض: lsquo,rsquo,ldquo,rdquo مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex
- --syntax-highlighter ARG
- تنظیم برجسته‌ساز نحو (syntax highlighter)
برجسته‌ساز نحو مورد استفاده برای برجسته‌سازی بلوک‌ها و محدوده‌های درون‌خطی کد را مشخص می‌کند. اگر این گزینه روی +nil+ تنظیم شود، هیچ برجسته‌سازی نحوی انجام نمی‌شود.
گزینه‌های مربوط به برجسته‌ساز نحو را می‌توان با گزینهٔ پیکربندی syntax_highlighter_opts تنظیم کرد.
پیش‌فرض: rouge مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex
- --syntax-highlighter-opts ARG
- تنظیم گزینه‌های برجسته‌ساز نحو
گزینه‌های مربوط به برجسته‌ساز نحوِ تعیین‌شده از طریق گزینهٔ پیکربندی syntax_highlighter را مشخص می‌کند.
مقدار باید یک هش از جفت‌های کلید-مقدار باشد که برای برجسته‌ساز نحوِ مورد استفاده قابل فهم باشد.
پیش‌فرض: {} مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex
- --template ARG
- نام فایل الگوی ERB که باید برای قالب‌بندی خروجی استفاده شود، یا خود الگوی ERB.
از این گزینه برای قرار دادن خروجی درون یک قالب استفاده می‌شود تا خروجی بتواند به عنوان یک سند مستقل عمل کند. به عنوان مثال، یک الگوی HTML تگ‌های هدر و بدنهٔ لازم را فراهم می‌کند تا کل خروجی یک فایل معتبر HTML باشد. اگر هیچ الگویی مشخص نشود، خروجی تنها متن تبدیل‌شده خواهد بود.
هنگام واکشی فایل الگو، ابتدا نام الگوی داده‌شده بررسی می‌شود. اگر چنین فایلی پیدا نشود، پسوند تبدیل‌کننده (همان نام تبدیل‌کننده) به انتهای آن افزوده می‌شود. اگر فایل باز هم پیدا نشود، نام الگو به عنوان نام الگویی که توسط kramdown ارائه شده تفسیر می‌شود (بدون پسوند تبدیل‌کننده). اگر فایل همچنان یافت نشود، بررسی می‌شود که آیا نام الگو با ‘string://’ آغاز می‌شود یا خیر؛ در این صورت، این پیشوند حذف شده و باقی‌مانده به عنوان محتوای الگو استفاده می‌شود.
ابزار kramdown برای هر تبدیل‌کننده یک الگوی پیش‌فرض به نام ‘document’ ارائه می‌دهد.
پیش‌فرض: ‘’ مورداستفاده در: تمام تبدیل‌کننده‌ها
- --toc-levels ARG
- سطوحی را که برای فهرست مطالب (TOC) استفاده می‌شوند تعریف می‌کند
سطوح مجزا را می‌توان با جدا کردن توسط کاما (مانند 1,2,3) یا با استفاده از نحو بازه (مانند 1..3) مشخص کرد. تنها سطوح تعیین‌شده برای فهرست مطالب استفاده می‌شوند.
پیش‌فرض: 1..6 مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex
- --[no-]transliterated-header-ids
- نویسه‌گردانی متن سربرگ پیش از تولید شناسه (ID)
در شناسه‌های سربرگ‌ها تنها از نویسه‌های ASCII استفاده می‌شود. این موضوع برای زبان‌هایی با تعداد زیادی نویسهٔ غیر ASCII مناسب نیست. با فعال کردن این گزینه، متن سربرگ تا حد امکان به ASCII نویسه‌گردانی می‌شود تا شناسهٔ سربرگ حاصل کاربردی‌تر باشد.
برای کارکرد این قابلیت باید کتابخانهٔ stringex نصب شده باشد!
پیش‌فرض: false مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex
- --typographic-symbols ARG
- نگاشتی از نماد تایپوگرافی به نویسه‌های خروجی را تعریف می‌کند
نمادهای تایپوگرافی معمولاً با استفاده از نقطه کد یونیکد معادل خود در خروجی قرار می‌گیرند. با این حال، گاهی ممکن است نیاز به تغییر خروجی باشد؛ به‌ویژه برای جایگزینی با دنباله‌ای از نویسه‌های ASCII.
این گزینه چنین امکانی را از طریق تعیین یک نگاشت از نماد تایپوگرافی به رشتهٔ خروجی آن فراهم می‌کند. برای نمونه، نگاشت {hellip: ...} بازنمایی استاندارد ASCII یک سه‌نقطه (ellipsis) را در خروجی تولید می‌کند.
نام‌های نمادهای تایپوگرافی موجود عبارتند از:
- hellip: سه‌نقطه (ellipsis)
- mdash: خط تیرهٔ بلند (em-dash)
- ndash: خط تیرهٔ کوتاه (en-dash)
- laquo: گیومه چپ (left guillemet)
- raquo: گیومه راست (right guillemet)
- laquo_space: گیومه چپ همراه با یک فاصله پس از آن
- raquo_space: گیومه راست همراه با یک فاصله پیش از آن
پیش‌فرض: {} مورداستفاده در: تبدیل‌کنندهٔ HTML/Latex اگر هیچ خطایی رخ ندهد، وضعیت خروج 0 است. در غیر این صورت 1 خواهد بود.
همچنین ببینید (SEE ALSO)
وب‌سایت kramdown http://kramdown.gettalong.org برای اطلاعات بیشتر، به‌ویژه درباره نحو ورودی پشتیبانی‌شده.
نویسندگان (AUTHORS)
kramdown توسط Thomas Leitner نوشته شده است.
این صفحه راهنما توسط Thomas Leitner نوشته شده است.
| January 2019 |