انتقل إلى المحتوى الرئيسي

الفصل 5 · الجزء II · الحرفة

صيغة المستند

الجزء من Markdown الذي يقرؤه Postext: البيانات التمهيدية في أول الملف، والعناوين، والقوائم، وكتل الشيفرة؛ وما يتجاهله؛ وقواعد كتابة المستندات المصدرية

آخر تحديث 2026-10-1915 دقيقةenescadefritptzhjaar

باختصار

تشرح هذه الصفحة كيف تكتب نصًا يستطيع Postext أن يُخرجه في صفحات. تكتب بلغة Markdown، وهي طريقة بسيطة في الكتابة تدلّ فيها رموز قليلة على العناوين والقوائم والكلمات العريضة والروابط. وتتناول هذه الصفحة الأسطر التي في أعلى الملف، والعناوين، والقوائم، والشيفرة، والعلامات التي يتجاهلها Postext. وتتناول أربع صفحات أخرى الكتل مثل الإطارات والأعمدة، والعلامات داخل السطر، والحواشي والإحالات، والصور والجداول. وتنتهي الصفحة بنصائح لكتابة نص سهل القراءة.

يقرأ Postext لهجة Markdown صغيرة عن قصد.

المحلّل مُقطِّع (tokenizer) مكتوب يدويًا، لا تطبيق كامل لمواصفة CommonMark، ولذلك فصيغة المصدر ضيقة ويمكن توقّع سلوكها. والغاية من ذلك أمران: أن يبقى المحرّك صغيرًا وسريعًا، وأن تنتقل المستندات بلا عناء بين Postext وأي قارئ آخر لـCommonMark (Obsidian وPandoc وVS Code…). وكل ما لا تذكره هذه الصفحة إما يُعامَل نصًا عاديًا وإما يُحذف من النص داخل السطر.

إذا كنت تبني مستندًا برمجيًا، فالدالة parseMarkdown (انظر الإعدادات › التحليل) تعطيك بنية الكتل نفسها التي يستهلكها محرّك الإخراج.

#البيانات التمهيدية (frontmatter)

يجوز أن يبدأ المستند بكتلة بيانات تمهيدية اختيارية بصيغة YAML محاطة بعلامتَي ---:

---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---
 
# Chapter One
 
The story begins here…

استدعِ extractFrontmatter(source) لفصل البيانات التمهيدية عن المتن. يُعاد كائن البيانات الوصفية المحلَّل مع ما بقي من Markdown ومع موضع الحرف الذي يبدأ عنده المتن، وهذا مفيد إذا احتجت إلى ردّ الأخطاء أو مواضع المؤشر إلى المصدر الأصلي.

تُحلَّل البيانات التمهيدية بمكتبة gray-matter، فتُقبل أي بنية YAML. لا ينظر Postext نفسه إلا إلى title وsubtitle وauthor وpublishDate؛ أما المفاتيح الأخرى فتُحفظ في PostextContent.metadata وتستخدمها كما تشاء.

الكتلة التي ليست YAML صالحة — علامة اقتباس لم تُغلق، أو نص بعد قيمة بين علامتي اقتباس — لا توقف الإخراج: لا تُرجع extractFrontmatter أي بيانات وصفية، وتُرجع النص الذي يلي سطر --- الختامي بوصفه المتن، وتضع في error السبب الذي ذكره المحلّل. ويُنضَّد المستند دون بياناته الوصفية، ويضيف البناء المدخل invalidFrontmatter إلى contentWarnings (ويعرضه Sandbox باسم بيانات تمهيدية غير صالحة).

تعطي YAML قيمها أنواعًا: 1984 عدد، و2026-04-15 تاريخ، و[Ana Gil, Luis Paz] قائمة. يطبع Postext كل حقل من هذه الحقول الأربعة نصًا أيًّا كان نوعه:

  • العدد بصيغته العشرية البسيطة، والقيمة المنطقية true أو false (title: 1984 يطبع 1984). تقرأ YAML العدد بوصفه قيمة، لا سلسلة من الأرقام: 1.50 يطبع 1.5، و017 (ثماني) يطبع 15، و1:30 (بالأساس 60) يطبع 90؛
  • التاريخ بيومه في التقويم، مكتوبًا بلغة المستند، أي الإعداد locale، وإلا فلغة تقسيم الكلمات: publishDate: 2026-04-15 يطبع April 15, 2026 بالإنجليزية، و15 de abril de 2026 بالإسبانية، و15. April 2026 بالألمانية. وتستخدم التواريخ العربية التقويم الميلادي ما لم يحدّد الوسم تقويمًا آخر (ar-u-ca-islamic يطبع التاريخ الهجري)، بالأرقام التي يقتضيها الوسم (ar-EG: ١٥ أبريل ٢٠٢٦؛ ar-u-nu-latn: 15 أبريل 2026). وإذا تضمّن التاريخ ساعةً من اليوم، طُبع اليوم الموافق لتلك الساعة بتوقيت UTC وأُسقطت الساعة: 2026-09-24T23:30:00-05:00 هو الساعة 04:30 بتوقيت UTC من يوم 25، فيطبع September 25, 2026؛
  • القائمة بعناصرها مفصولة بفواصل (author: [Ana Gil, Luis Paz] يطبع Ana Gil, Luis Paz).

ضع القيمة بين علامتَي تنصيص لتُطبع كما كُتبت تمامًا، كعدد يجب أن يحتفظ بأرقامه أو تاريخ يجب أن يحتفظ بيومه: publishDate: "15/04/2026"، title: "1984". يصل النص إلى doc.metadata وإلى العناصر النائبة ({title}، {publishDate}…) وإلى عنوان ملف PDF ومؤلفه. وأي حقل من الحقول الأربعة لا صيغة نصية له، كخريطة متداخلة أو title: فارغ، يُترك خارج doc.metadata. وتظل extractFrontmatter تعيد القيم بالأنواع التي أعطتها إياها YAML؛ أما metadataText(value, locale) فتعطي النص الذي يطبعه Postext لإحداها.

#البنى الكتلية

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

أنواع كتل النص في لمحةأنواع كتل النص السبعة التي يتعرّف عليها Postext: العنوان والفقرة والاقتباس الكتلي والقائمة غير المرقّمة والقائمة المرقّمة وقائمة المهام والصيغة المعروضة، ولكل منها صياغته في Markdown. أما التوجيهات وتضمين الموارد فلها شرح مستقل.عنوان# Titleفقرةأسطر نص عادياقتباس كتلي> quoted textقائمة غير مرقّمة- itemقائمة مرقّمة1. item1.2.3.قائمة مهام- [x] doneصيغة معروضة$$ \int f(x) $$∫ f(x) dx(1)
كل نوع من كتل النص وصياغته في Markdown.
البنيةالصياغةملاحظات
عنوان# Title … ###### H6من علامة # واحدة إلى ست علامات، تليها مسافة ثم نص العنوان. تقابل المستويات 1–6 مباشرة الإعداد headings.levels.
فقرةنص عادي على سطر واحد أو أكثرالأسطر المتتالية غير الفارغة، التي لا تبدأ ببنية خاصة، تُضمّ بمسافة واحدة وتصير فقرة واحدة. وبين حرفين صينيين أو يابانيين (الحروف الإيديوغرافية والكانا وعلامات الترقيم كاملة العرض، وعلامات التنصيص المنحنية والشرطات وعلامة الحذف المجاورة لها) تُحذف نهاية السطر بدلًا من ذلك، كما تفعل CSS، فيجوز أن تقسم الفقرة الصينية على أسطر المصدر في أي موضع. وبين علامتين من هذا النوع (“你好”⏎“再见”، 他说……⏎“好”) يُحتكم إلى الحرفين الواقعين خارجهما: تُحذف نهاية السطر إذا كان أحدهما صينيًا أو يابانيًا، أما “hello”⏎“bye” فتحتفظ بمسافتها. وتحتفظ الكورية بمسافتها. ولا يُحفظ فاصل السطر المكتوب في المصدر، إلا إذا انتهى السطر بشرطة مائلة عكسية (كسر سطر إجباري، انظر فواصل الأسطر)؛ والسطر الفارغ يبدأ فقرة جديدة. ومحرف الجدولة المكتوب في النص مسافة بين كلمتين كذلك، ما لم يحدّد نمط الفقرة مواضع جدولة؛ أما :tab فجدولة دائمًا (انظر الجدولة ومواضع الجدولة). والقصيدة التي يجب أن تبقى أسطرها كما كُتبت توضع في كتلة :::verse.
اقتباس كتلي> quoted textيجب أن يبدأ كل سطر من الاقتباس بالعلامة > (تليها مسافة اختيارية واحدة). تندمج أسطر الاقتباس المتتالية في كتلة اقتباس واحدة، وتُضمّ كما تُضمّ أسطر الفقرة. ويُنضَّد كما يحدّده bodyText.blockquote: بحروف مائلة رمادية مع إزاحة السطر الأول في المتن ما لم تغيّرها (انظر الإعدادات › الاقتباسات الكتلية).
قائمة غير مرقّمة- item، * item، + itemتُقبل أي علامة من علامات التنقيط الثلاث. يتداخل البند تحت البند الذي فوقه إذا أُزيحت علامته عمودين على الأقل بعد علامة ذلك البند: مسافتان تحت -، ومسافتان أو ثلاث تحت 1. (عمود نصه، كما في CommonMark)، حتى عمق أقصى قدره 5.
قائمة مرقّمة1. item، 2) itemأرقام تليها . أو ): أرقام أوروبية، أو الأرقام الهندية العربية (١.) والفارسية (۱.) التي تكتبها لوحة المفاتيح العربية أو الفارسية. يُحفظ رقم البداية (فيمكن أن تبدأ القائمة من 5 أو من 0). أما الفاصل الذي يظهر في المخرجات فيأتي من orderedLists.separator لا من المصدر.
قائمة مهام (GFM)- [ ] todo، - [x] doneعنصر غير مرقّم بمربع اختيار بين قوسين معقوفين. يقبل x الصغيرة أو X الكبيرة. يرسم المحرّك مربعه، وفيه علامة صح إذا أُنجزت المهمة؛ وإذا حُدّد محرف في taskCheckboxChar / taskCheckedChar نُضِّد نصًّا مكان المربع.
صيغة معروضة$$ … $$صيغة LaTeX تُنضَّد كتلةً قائمة بذاتها. تُرسم في وسط العمود، وتُلحَق بشبكة خطوط الأساس كما يُلحَق العنوان، وتبقى متجهية في مخرجات PDF. والصيغتان، صيغة السطر الواحد وصيغة الكتلة متعددة الأسطر، مشروحتان في الصيغ الرياضية.
كتلة شيفرةjs</code> … <code>، ~~~ … ~~~قائمة شيفرة تُحفظ كما كُتبت: كل مسافة وجدولة وفاصل سطر، ولا يُقرأ شيء منها بوصفه Markdown. تُنضَّد سطرًا سطرًا بخط الشيفرة داخل إطار. انظر كتل الشيفرة.

يُسمح بسطر فارغ واحد بين عنصرين من القائمة، فتبقى القائمة متصلة. أما سطران فارغان أو أكثر فينهيان القائمة.

تُقبل القوائم المختلطة الأنواع في العمق نفسه (يمكنك التحول من غير المرقّمة إلى المرقّمة في منتصف السلسلة)، لكن المحرّك يعامل كل سلسلة على حدة في الترقيم. وعمليًا، احتفظ بنوع واحد لكل عمق ما لم يكن لديك سبب للخلط.

عمق تداخل القوائميتداخل البند تحت البند الذي فوقه إذا أُزيح بعد علامته: مسافتان تحت علامة التنقيط، حتى عمق أقصى قدره خمسة. يزيد كل مستوى الإزاحة ويجوز أن يستخدم نمط تنقيط مختلفًا.024681-المستوى 12-المستوى 2، بإزاحة مسافتين3-المستوى 3، بإزاحة أربع مسافات4-···5-···مسافتان تحت علامة التنقيط، وثلاث تحت 1. العمق الأقصى: 5.
مسافتان لكل مستوى تحت علامة التنقيط. العمق الأقصى: خمسة.

#سمات العناوين

يجوز أن ينتهي سطر العنوان بكتلة سمات بين قوسين معقوصين، بصياغة key="value" نفسها التي تستخدمها التوجيهات:

# The Long Road {author="I. Zango Martín" year=1998}

تُحذف الأقواس ومحتواها من نص العنوان (فالعنوان أعلاه يظهر The Long Road) وتُخزَّن في العنوان ضمن attrs. وتُتاح لخانات التصميم عناصرَ نائبة بصيغة {attr.<key>}: في خانة التصميم المتقدم الخاصة بالعنوان نفسه، وفي ترويسات الصفحات وتذييلاتها، وفيها تُستمد قيمها من عنوان H1 للفصل الحالي. ولا يُتعرَّف إلا على كتلة متوازنة خالية من الأقواس في آخر السطر تمامًا، بعد مسافة، أو مباشرة بعد حرف صيني أو ياباني لأن العناوين الصينية تُكتب بلا مسافة (# 回目{style="x"}). ولا تُعدّ الكتلة كتلة سمات إلا إذا أمكن قراءتها كلها بصياغة السمات المشروحة أدناه: فـ{x, y} و{紅樓|hóng lóu} و{} المنفردة تبقى في العنوان، وكذلك الرايات المنفردة الملتصقة بالعنوان (# 第一回{draft}). تُفصل السمات بمسافات، فالكتلة التي فيها فواصل ({a="1", b="2"}) وصيغة Pandoc {.class} تبقيان في العنوان أيضًا. أما معرّف Pandoc {#id} فيُقرأ: وهو مثل id="…"، يمنح العنوان اسمًا تستعمله الإحالات. والمفتاح المكتوب بنظام كتابة آخر يُقرأ ثم يُسقط مع تحذير (انظر أدناه)، فتُقرأ style في # 回目{style="x" 作者=曹雪芹} مع ذلك. انظر الإعدادات › الترويسات والتذييلات.

يجوز أن تمتد القيمة التي يطبعها نص في التصميم على عدة أسطر: الحرفان \n يبدآن سطرًا جديدًا في موضعهما، أيًّا كانت قيمة overflow للعنصر (to="Firma X\nStrasse 1\n10115 Berlin" يطبع عنوانًا بريديًا من ثلاثة أسطر). ومع inlineMarks على العنصر تُطبَّق العلامات داخل السطر في القيمة أيضًا: authors="Ana Ruiz^1^, Luis Gil^2^" ينضّد أرقام الانتساب حروفًا علوية. وهذا الترميز الهارب (escape) خاص بقيم السمات (وبقوالب التصميم نفسها): الحرفان \n في نص العنوان، داخل مقطع شيفرة مثلًا، يُطبعان كما كُتبا.

لسمتين معنى خاص بهما. style="<id>" تطبّق على العنوان نمط عنوان مسمّى: مقدمة أو قائمة مؤلفين لها تصميم افتتاح خاص وترويسات وهندسة صفحة وطباعة متن خاصة بها، وبلا رقم فصل إذا ضُبط في النمط numbered: false. وtoc="false" (أو "true") تحدّد هل يُذكر العنوان في جدول المحتويات الذي يُنشئه :::toc:

# Preface {style="front-matter"}
 
# Contents {style="front-matter" toc="false"}

وسمتان أخريان تغيّران ما يطبعه العنوان وكيف يُعدّ. hidden="true" (أو "false") تتجاوز قيمة hidden لمستوى العنوان أو نمطه: العنوان المخفي لا يطبع شيئًا ولا يشغل مكانًا، في التدفق وداخل إطار :::callout على السواء، لكنه يظل يفتح صفحته ويُعدّ ويُذكر في المحتويات وفي ترويسات {chapterTitle} وفي العلامات المرجعية لملف PDF. وjidori=N توزّع العنوان ذا السطر الواحد بالتساوي على عرض N من محارفه هو (字取り: # 序章 {jidori=3} يطبع 序 章)، وjidori=0 تلغي التوزيع المتساوي الذي يضبطه مستواه أو نمطه (انظر الإعدادات › تجاوزات كل مستوى). وindent=N تُزيح عنوانًا واحدًا عن بداية السطر بمقدار N من محارف المتن (字下げ: ## 一 {indent=5})، متجاوزةً indent مستواه أو نمطه؛ والعدد المجرد يُعدّ بوحدات em من المتن، و0 تعيد العنوان إلى بداية السطر، وتعمل على النحو نفسه في النص العمودي والأفقي. وfirstLineIndent=N تُزيح السطر الأول وحده من عنوان واحد، متجاوزةً firstLineIndent مستواه أو نمطه، وتبدأ بقية أسطره حيث تضعها indent (عناوين GB/T 9704: ## 关于加强管理的通知 {firstLineIndent=2})؛ وتقرأ الأطوال كما تقرؤها indent، و0 تلغي إزاحة المستوى. وstartAt=N، وهو عدد صحيح موجب، يضبط عدّاد مستوى العنوان على N بدلًا من زيادته؛ وتواصل العناوين التالية العدّ من هناك، في الفصول اللاحقة أيضًا، وتبدأ المستويات الأدنى من جديد تحته كالمعتاد. ومع نمط عنوان يرقّم الملاحق بالحروف (numberingTemplate: 'Appendix {1:A}')، يعيد الملحق الأول بدء العدّ ليُقرأ Appendix A بدلًا من متابعة العدّ من الفصول:

# To my mother {hidden="true" toc="false"}
 
# Survey instrument {style="appendix" startAt=1}
 
# Raw data {style="appendix"}

#الحروف الاستهلالية

تُفتتح الفقرة بحرف استهلالي حين يضبطه مستوى عنوانها أو نمطه، أو نمط الفقرة الخاص بمجموعة :::paragraphs التي هي فيها (انظر الإعدادات › الحروف الاستهلالية): يُنضَّد الحرف الأول كبيرًا بجوار الأسطر الأولى، وتقصر هذه الأسطر حوله. ولا ترميز في الفقرة نفسها؛ فالنص يُكتب كالمعتاد، ويبقى الحرف جزءًا من كلمته في النسخ والبحث وخريطة المصدر. والسمة dropcap تُشغّله أو تُطفئه لفصل واحد أو لمجموعة واحدة:

# Lost {dropcap=false}
 
# The mines {dropcap=2}
 
:::paragraphs{style="entry" dropcap}
The lamp of the first entry opens with an initial.
:::

في سطر العنوان، تترك dropcap=false الفقرة التي تلي ذلك العنوان بلا الحرف الاستهلالي الذي يضبطه مستواه أو نمطه، وتضبطه dropcap=N على N أسطر، وتعطي dropcap المجرّدة تلك الفقرة حرفًا استهلاليًا (بثلاثة أسطر وبخط الفقرة) حيث لا يضبط المستوى شيئًا. وفي سطر الفتح :::paragraphs تفعل السمة الشيء نفسه للفقرة الأولى من المجموعة، أو لكل فقرة فيها حين يضبط النمط each: true. ويُبحث عن الفقرة التي تلي العنوان بتخطّي أسطر فتح الحاويات وإغلاقها، والتوجيهات، والإطارات التي خرجت من التدفق، والأشكال العائمة؛ أما الفقرة الواقعة داخل إطار أو عنصر قائمة أو اقتباس أو قصيدة فلا تأخذ حرفًا استهلاليًا أبدًا. منذ postext 1.23.

في الصفحة المركّبة تكون الإطارات نصًّا جاريًا: تفتح :::paragraphs{style="opening" dropcap} في إطارٍ أولَ فقرة فيه بالحرف الاستهلالي. أما داخل إطار :::callout فلا تأخذ الفقرات حرفًا استهلاليًا، وطلبه هناك يُصدر التحذير dropCap.

#كتل الشيفرة

توضع قائمة الشيفرة بين سطر فتح وسطر إغلاق، يتكوّن كلٌّ منهما من ثلاث علامات اقتباس مائلة (backticks) أو أكثر (أو ثلاث علامات ~ أو أكثر)، ولا يُزاح بأكثر من ثلاث مسافات. وكل ما بينهما يُحفظ كما كُتب: المسافات البادئة وسلاسل المسافات، والجدولات، والأسطر الفارغة، والأسطر التي تبدأ بـ# أو - أو 1. أو > أو $ أو :::. ولا يُقرأ شيء في داخلها Markdown: لا توكيد ولا :ref ولا صيغ رياضية ولا شارات ولا توجيهات ولا عناوين. ويُكتب سطر الإغلاق بمحرف سطر الفتح نفسه، ولا يقصر عنه طولًا؛ فإذا أردت أن تعرض في القائمة سطرًا من هذا النوع، فضعها بين سطرين أطول أو بين سطرين من علامات ~:

```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copy the photos to the backup disk
rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/
echo "done: $(date)"
```

تحدّد سلسلةُ المعلومات (info string) التي تلي سطر الفتح لغةَ الشيفرة (كلمتها الأولى: js أو ts أو python أو bash أو console أو json…)، ويُقرأ ما بعدها سماتٍ بـصياغة السمات، بين قوسين معقوصين أو بدونهما (title="app.js" lineNumbers). وأي شيء آخر بعد اللغة هو العنوان: ```console Terminal و```python normalize.py تطبعان Terminal وnormalize.py فوق القائمة.

السمةالأثر
title="…"عنوان فوق القائمة، في صف للعنوان (أو في لسان على حافة الإطار حين يُضبط codeStyle.label).
label="…"نص لسان الإطار، كما في :::callout (مع codeStyle.label).
lineNumbers، lineNumbers=falseترقّم أسطر هذه القائمة (أو لا ترقّمها)، أيًّا كان ما يقوله codeStyle.lineNumbers. تقف الأرقام في هامش قبل الشيفرة ولا تُنسخ معها.
start=Nرقم السطر الأول (ويرقّم القائمة إن لم يرقّمها شيء آخر).
highlight="3,5-7"تلوّن خلفية الأسطر المذكورة (تُعدّ من السطر الأول للقائمة، بدءًا من 1): أسطر مفردة ونطاقات، مفصولة بفواصل.
span=pageفي صفحة من عدة أعمدة، تمتد القائمة عليها كلها.
placement=top, placement=bottomتطفو القائمة إلى أول شريط فارغ في رأس عمود أو أسفله، كما يطفو :::callout.

ينهي سطرُ الفتح الفقرةَ التي فوقه، بسطر فارغ أو بدونه، ويبدأ النص الذي يلي سطر الإغلاق فقرة جديدة. وإذا لم يُكتب سطر الإغلاق امتدت القائمة حتى نهاية النص، وأصدر Postext التحذير unclosedCodeBlock. وكتلة الشيفرة داخل :::callout إطار متداخل فيه؛ وداخل :::paragraphs تحتفظ القائمة بنمط الشيفرة لا بنمط الفقرة. ولا يعرف Postext مواصلة عنصر القائمة في كتلة تابعة له، فكتلة الشيفرة التي تلي عنصر قائمة تُنهي القائمة. وعلامات الفهرس والمراسي المكتوبة داخل قائمة الشيفرة تبقى كما كُتبت.

لا تُقرأ الشيفرة المزاحة (بأربع مسافات أو بجدولة، بعد سطر فارغ) قائمةَ شيفرة إلا إذا شُغّل codeStyle.indentedCode: فكثيرًا ما تُزاح نصوص Postext بالمسافات، والمسافات البادئة هي ما يجعل عناصر القوائم متداخلة.

يضبط codeStyle مظهر القائمة (خطها وإطارها وعرض الجدولة وما يحدث للسطر الأعرض من الإطار وأرقام الأسطر وألوان رموزها)؛ انظر الإعدادات › قوائم الشيفرة. وتبقى الشيفرة داخل السطر (`x`) بخط النص ما لم يحدّد لها codeStyle.inline خطًا. والكتاب المحفوظ قبل postext 1.23 وفي نصه كتل شيفرة يقرؤها Postext كما كان يقرؤها حينها، أي بوصفها Markdown (codeStyle.blocks: false). منذ postext 1.23.

#ما لا يدعمه Postext

لا يتعرّف Postext على ميزات CommonMark التالية. فهي إما تُعامل نصًا عاديًا (فتظهر حرفيًا في المخرجات) وإما تُحذف بصمت:

  • العناوين بنمط Setext، أي صيغة التسطير === / ---. استعمل عناوين ATX (#).
  • تمرير HTML، فوسوم <tags> الخام لا تُفسَّر. ولا تُدعم الوسوم بأسلوب MDX أيضًا؛ فمصدر Postext هو Markdown خالص.
  • الخطوط الأفقية، أي --- و*** و___.
  • الجداول، فجداول الخطوط العمودية لا تُحلَّل. تُنمذج الجداول موارد مهيكلة في PostextContent.resources.
  • الروابط بأسلوب المراجع، أي [text][id] مع كتلة تعريف.
  • الروابط التلقائية، أي <https://example.com>.
  • فواصل الأسطر بمسافتين في آخر السطر، فالمسافتان تُحذفان. اختم السطر بشرطة مائلة عكسية بدلًا من ذلك (انظر فواصل الأسطر).
  • الحواشي الجانبية، فهي غير منفّذة، وPostextContent.notes، الذي تقبله الأنواع، يتجاهله المحرّك. أما الحواشي السفلية والحواشي الختامية في آخر الفصل فتُكتب بـ[^id] (انظر الحواشي السفلية)؛ وحتى postext 1.5 كان لا بد من تنضيدها نصًا.

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

وبعيدًا عن الصياغة، تُنضَّد العربية وسائر الكتابات التي تُكتب من اليمين إلى اليسار من اليمين إلى اليسار، بخوارزمية النص ثنائي الاتجاه والتجليد من اليمين (انظر الإخراج العربي). وتُنضَّد الصينية أفقيًا عبر الصفحة وعموديًا نزولًا فيها، مع قواعد كسر الأسطر وعروض علامات الترقيم وضبط الأسطر بين المحارف والعلامات والروبي (ruby) والواريتشو (warichu) التي تقتضيها منطقتها (انظر الإخراج الصيني). وتُنضَّد اليابانية بقواعدها الخاصة: الكينسوكو، وبياض الياكومونو، والفوريغانا، وعلامات التوكيد، وعلامات الكانبون، والحواشي (انظر الإخراج الياباني)؛ وتمر الكورية عبر المُنضِّد نفسه بقواعد الصين القارية. ويأتي Postext بأنماط تقسيم الكلمات بالواصلة لثماني لغات، وبتسميات مدمجة لهذه اللغات الثماني وللصينية واليابانية والعربية. انظر اللغات وأنظمة الكتابة.

#أعراف التأليف

بضعة أعراف تصنع الفرق بين مستند يُحلَّل بسلاسة ومستند يفاجئك:

  • اترك سطرًا فارغًا بين الكتل. فقرتان يفصلهما سطر فارغ فقرتان. وفقرتان في سطرين متتاليين تصيران فقرة واحدة، إذ يندمج كل سطر في الفقرة السابقة.
  • الأسطر الفارغة الزائدة لا تضيف مسافة. ثلاثة أسطر فارغة تفصل بين كتلتين تمامًا كسطر واحد. وحين تريد مسافة أكبر بينهما، اكتب سطر :::space.
  • أزِح البند المتداخل حتى نص البند الذي فوقه. مسافتان تحت علامة التنقيط (- )، وثلاث تحت 1. ، وأربع تحت 10. ، كما تتداخل القوائم في CommonMark؛ والمسافتان تحت 1. تُحدثان التداخل أيضًا. يتداخل البند تحت أقرب بند مفتوح تقع علامته قبله بعمودين على الأقل، فالمسافة الواحدة لا تُحدث تداخلًا، ولا يُتخطّى أي مستوى مهما كان مقدار الإزاحة (حتى postext 1.15 كان العمق floor(المسافات / 2) + 1، فكان 1. تحت 1. يقع في المستوى 4). وتنقل علامة الجدولة (tab) إلى المضاعف التالي للعدد أربعة من الأعمدة. والعمق الأقصى 5.
  • لا تُزِح بند القائمة الأول. تبدأ بنود المستوى 1 عند العمود 0. والبند الأول في القائمة يفتح المستوى 1 مهما أُزيح (حتى postext 1.15 كانت المسافات البادئة ترفع عمقه)، فالتداخل يحتاج إلى بند فوقه يتداخل تحته.
  • يجب أن تكون علامات المهام بين قوسين مربعين مع مسافة واحدة. [ ]، [x]، [X]، دون أي تنويع. [*] أو [-] ليستا علامتي مهام، وتظهران نصًا حرفيًا.
  • الاقتباسات الكتلية داخل القوائم غير مدعومة. ابدأ الاقتباس الكتلي عند العمود 0، خارج القائمة.
  • الصور والجداول مكانها resources. تُزال الصيغة داخل السطر ![alt](src) تحديدًا لأن الصور داخل السطر تُفسد توزيع العناصر على الأعمدة. عرّف كل صورة موردًا وأحِل إليها بمعرّفها، فيقرر المحرّك عندئذ هل تطفو، أم تقطع العمود، أم تنتقل إلى أعلى الصفحة التالية.
  • هرّب علامات الدولار بـ\$ حين لا تقصد صيغة رياضية. يفسّر Postext الصيغة $…$ بوصفها LaTeX داخل السطر، فعلامة $ الخام في النص تبدأ صيغة رياضية. الأسعار ومحثّات الصدفة (shell prompts) وكل ما فيه علامة دولار مجردة ينبغي أن يُكتب \$.
  • اكتب الترميز بمحارف ASCII، في النص الصيني والياباني أيضًا. تُعطي طريقة الإدخال الصينية أو اليابانية الصيغ كاملة العرض: ::: لسطر الحاوية، و# للعنوان، و[^1] لعلامة الحاشية، و{…} للسمات، و** للعريض. فتُطبع هذه الصيغ نصًا، ويُصدر البناء عن ذلك السطر التحذير fullwidthMarkup ويذكر فيه صيغة ASCII التي ينبغي كتابتها. ويمكن أن تكون قيم السمات بأي نظام كتابة وأن تُحاط بـ“…” أو 「…」؛ أما أسماء السمات فتبقى بمحارف ASCII.

#مثال تطبيقي

مستند قصير يستعمل كل بنية مدعومة:

---
title: The Typesetter's Craft
author: Anon
---
 
# Opening
 
A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.
 
## What makes text readable
 
Three properties matter most:
 
1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
   1. Tighter at short measures.
   2. Looser at long measures.
3. Contrast between body and headings.
 
Common failure modes include:
 
- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.
 
> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst
 
### Review checklist
 
- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread
 
### A note on formulas
 
Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:
 
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$

ويُنتج المستند نفسه، حين يمر عبر محرّك الإخراج، كائن VDTDocument مهيكلًا تتضمّن صفحاته كل كتلة من هذه الكتل مدخلًا محدّد النوع؛ انظر صفحة البنية لمعرفة كيف تتحول الكتل إلى أشكال هندسية على الصفحة.

#أمثلة في دليل الوصفات

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