انتقل إلى المحتوى الرئيسي
الوصفة رقم 48

دليل الوصفات · الفصل 6 · الإطارات والملاحظات

قوائم الشيفرة ومفاتيح لوحة المفاتيح

دليل لسطر الأوامر تُنضَّد فيه كتل الشيفرة قوائمَ في إطارات داكنة ملوّنة حسب الرموز، وتُنضَّد المفاتيح شاراتٍ على هيئة أزرار.

في هذه الصفحة
المُخرَج
Canvas
المستوى
متوسط
Postext
اختُبرت مع Postext 1.65.0
تتطلب ≥ 1.25.0
الترخيص
حُدّثت في 10 أكتوبر 2026
الشيفرة MIT · النص CC BY 4.0

ص 50–51 · 2–3 من 3

  • نموذج باللغة الإنجليزية: لا توجد طبعة عربية بعد
  • مقاس القص 178 × 229 مم
  • عمود ونصف, فاصل 6 مم بين الأعمدة
  • Charis SIL 10/14.5
  • JetBrains Mono
  • Sora
  • 3 صفحات
  • المستوى
  • Postext 1.57.1
  • أُخرجت في 89 ms
  • أسطر الشيفرة: 147

باختصار

ثلاث صفحات من دليل للمبتدئين في سطر أوامر الحاسوب. تبيّن كيف تُنضَّد أمثلة الشيفرة في إطارات داكنة ملوّنة، وكيف تُرسم مفاتيح مثل Ctrl أزرارًا صغيرة داخل النص.

ما الذي ستنضده

ثلاث صفحات من الفصل 4 من The Shell, Gently، وهو دليل جيب متخيَّل لسطر الأوامر، على صفحة مقاسها 178 × 229 mm. النص مضبوط بخط Charis SIL في عمود عرضه 100 mm، وفي الجهة الخارجية عمود هامشي للملاحظات. كل قائمة شيفرة إطار شبه أسود بخط JetBrains Mono يمتد إلى ذلك العمود، تحت لسان عليه اسم الملف أو الجلسة. الكلمات المحجوزة والأوامر المكتوبة تُطبع بالكهرماني، والسلاسل النصية بالأخضر، والتعليقات بالرمادي. المفاتيح مثل Ctrl وTab أزرار صغيرة محددة الإطار داخل الأسطر المضبوطة، وورقة مرجعية من عمودين لاختصارات Ctrl تملأ أسفل الصفحة 50. يحتفظ ملف Markdown بكتل الشيفرة العادية، وينضّدها المحرّك كما هي.

تجيب هذه الوصفة عن

  • كيف أعرض قوائم الشيفرة؟
  • كيف أصنع شارات مضمّنة: مفاتيح لوحة المفاتيح، ووسوم، وبنوك كلمات للتمارين؟
  • كيف أكتب شرطات الحوار، والسنوات في بداية الفقرة، والأسعار، والرموز الحرفية من دون أن يسيء Markdown قراءتها؟

الجواب المختصر

script.js · الأسطر 26–41في الشيفرة الكاملة
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
  fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
  background: col('night'), span: 'page', // across the text and the margin
  padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
  marginTop: mm(6), marginBottom: mm(2.5),
  label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
    background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
    position: 'top-left' },
  tokens: tokens(), // the colours, below
  inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};

المكونات

تستخدم أيضًا
الرياضيات
الخطوط
Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
الأصول
لا شيء: كل صورة مرسومة بالشيفرة

طريقة التحضير

#1 · أعطِ الأسوار صندوقًا

شيفرة هذه الخطوة في الجواب المختصر أعلاه. كل سطر فتح ``` في ملف Markdown يبدأ كتلة شيفرة: ينضّد Postext أسطرها كما كُتبت، كل سطر من الشيفرة في سطر من الطباعة، ويحفظ الإزاحات والأسطر الفارغة في السكربت ومخرجات du ذات العمودين. ويصمّم codeStyle كل القوائم دفعة واحدة (قوائم الشيفرة): الخط وتباعد أسطره، والتعبئة شبه السوداء، والحشوة، والمسافة فوق الإطار وتحته. وما يلي اسم اللغة في سطر الفتح (Terminal، backup.sh) هو عنوان القائمة، ولأن codeStyle.label مضبوط يُطبع العنوان على لسان التسمية في الحافة العليا للإطار بدلًا من صف للعنوان. ويضبط codeStyle.inline الشيفرة داخل السطر في النص الجاري، مثل ls أو grep -c، بالخط نفسه وبحجم 0.88 em (الشيفرة داخل السطر). والفقرة التي تلي القائمة توضع في :::paragraphs{style="resume"}، فتبدأ بلا إزاحة كما تبدأ بعد عنوان.

#2 · أبقِ النص ضيقًا ودع الشيفرة تعبر الهامش

script.js · الأسطر 124–127في الشيفرة الكاملة
  page: { sizePreset: 'custom', width: mm(178), height: mm(229), margins: {
    top: mm(22), bottom: mm(21), left: mm(20), right: mm(OUTER), mirror: true } },
  layout: { layoutType: 'oneAndHalf', sideColumnPercent: 26, gutterWidth: mm(6),
    sideColumnRole: 'floats', sideColumnSide: 'outer' },

بحجم 10 pt ينضّد Charis SIL نحو 62 حرفًا في العمود ذي 100 mm. العمود الجانبي في هذا الإخراج بعمود ونصف لا يأخذ إلا العناصر العائمة والملاحظات، فلا يجري النص فيه أبدًا. والخاصية span: 'page' في codeStyle تمدّ كل قائمة على العمودين، 143 mm. داخل حشوته يتسع الإطار لـ73 حرفًا من JetBrains Mono بحجم 8.6 pt، وأطول سطر في هذه الصفحات، وهو التعليق الذي يفتتح backup.sh، فيه 71.

#3 · لوّن الشيفرة حسب الرموز

script.js · الأسطر 45–54في الشيفرة الكاملة
function tokens() {
  const plain = { color: col('code') }; // every other kind in the listing's own colour
  return {
    keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },
    string: { color: col('phosphor'), italic: true },
    comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
    prompt: { color: col('amber'), bold: true }, output: plain, // what you type, the answer
    number: plain, type: plain, variable: plain, meta: plain, operator: plain, punctuation: plain,
  };
}

اللغة المذكورة في سطر الفتح (console، bash) تختار المُقطِّع المدمج، ويحدّد codeStyle.tokens لكل نوع من الرموز لونه ووزنه وميله (تلوين الصياغة). في backup.sh تُطبع الكلمات المحجوزة مثل for وdone والأوامر المدمجة مثل set وecho بالكهرماني العريض، والسلاسل النصية بالأخضر المائل، والتعليقات بالرمادي؛ أما برامج مثل mkdir وrsync فتبقى عادية. النمط الافتراضي يجعل التعليقات مائلة، فتُبقيها italic: false قائمة. وفي كتلة console يكون السطر الذي يبدأ بمحثّ رمزًا من نوع prompt، وكل سطر آخر من نوع output، فتُطبع الأوامر التي تكتبها بالكهرماني العريض ويبقى جواب الصدفة بالرمادي الفاتح الذي تُطبع به القائمة. والأنواع التي لا تريد الوصفة تلوينها، ومنها الأرقام والمتغيرات والخيارات، تأخذ ذلك الرمادي أيضًا.

#4 · نضّد المفاتيح شاراتٍ

script.js · الأسطر 58–65في الشيفرة الكاملة
// Chips never break or stretch, so a line with keys puts all its slack in its word spaces;
// the breaker tries other breaks before a space passes 140 % (default 200 %).
const spacing = { maxWordSpacing: 1.4 }; // spread into bodyText
const chipStyles = [
  { id: 'key', fontFamily: MONO, fontSize: pt(7.8), bold: true, color: col('ink'),
    background: col('code'), borderColor: col('slate'), borderWidth: pt(0.6),
    borderRadius: pt(1.6), paddingX: em(0.45), paddingY: em(0.14), gap: em(0.3) },
];

المفاتيح شارات key بتعبئة فاتحة وحدّ بسماكة 0.6 pt. حجمها محدد بالنقاط، فيقيس المفتاح 7.8 pt في النص ذي 10 pt، وفي ملاحظة الهامش ذات 8.6 pt، وفي الورقة المرجعية ذات 8.4 pt؛ أما em(0.78) فتصغّر مفاتيح الورقة المرجعية إلى 6.6 pt. الشارة لا تنكسر بين سطرين ولا تتمدد أبدًا (الشارات داخل السطر)، فالسطر الذي فيه مفاتيح يضع كل فائضه في المسافات بين الكلمات. ويجعل spacing خوارزميةَ تقسيم الأسطر تجرّب مواضع كسر أخرى قبل أن تتجاوز أي مسافة 140 % من عرضها العادي. مع القيمة الافتراضية، 200 %، تتمدد ستة أسطر في هذه الصفحات أبعد من ذلك؛ ومع هذا الإعداد لا يتجاوز أوسعها 132 %.

#5 · رقّم الخطوات على الشبكة

script.js · الأسطر 91–94في الشيفرة الكاملة
const orderedLists = { fontFamily: DISPLAY, fontWeight: 800, color: col('ember'),
  gap: em(0.7), separator: '›', separatorGap: em(0.25), separatorFontFamily: MONO,
  separatorFontWeight: 700, separatorColor: col('muted'),
  marginTop: ZERO, marginBottom: ZERO }; // the default 1.5 em opens 5.3 mm above and below

الأرقام بخط Sora 800 بلون التمييز، والفاصل › أحادي المسافة بالرمادي. للفاصل خطه ولونه الخاصان، لذلك يُرسم مقطعًا منفصلًا (القوائم المرقّمة). هوامش القائمة صفر، فتستمر الخطوات على شبكة النص المحيط بها، 14.5 pt. القيمة الافتراضية 1.5 em تفتح 5.3 mm فوق الخطوات وتدفع الورقة المرجعية إلى الصفحة 51.

#6 · عوّم الورقة المرجعية إلى أسفل الصفحة

script.js · الأسطر 69–76في الشيفرة الكاملة
const sheet = { id: 'sheet', background: col('night'), span: 'page', placement: 'bottom',
  marginTop: mm(6), marginBottom: mm(2.5),
  columnGap: mm(8), padding: { top: mm(5), right: mm(6), bottom: mm(5.5), left: mm(6) },
  titleStyle: { fontFamily: MONO, fontSize: pt(7.5), fontWeight: 700, gap: mm(3.5),
    color: col('phosphor'), textTransform: 'uppercase', letterSpacing: pt(1.5) },
  body: { fontFamily: DISPLAY, fontSize: pt(8.4), lineHeight: pt(13), textAlign: 'left',
    color: col('code'), boldColor: col('amber'), italicColor: col('phosphor'),
    paragraphSpacing: false, firstLineIndent: ZERO } };

الورقة المرجعية نمط إطار بتعبئة القوائم نفسها وبخط Sora للأفعال، ومعه placement: 'bottom' الذي يجعلها تطفو إلى أسفل الصفحة 50 (الصناديق العائمة). لو بقي في التدفق إطارٌ ممتد على عرض الصفحة لاحتاج إلى مكان له ولسطرين من النص تحته. وهنا كان الإطار سينتقل إلى الصفحة 51، تاركًا 58 mm فارغة تحت الخطوات، وكان الفصل سيمتد إلى أربع صفحات. في ملف Markdown يفتح :::columns{count=2 breaks="8"} العمود الأيمن عند الكتلة الثامنة، وهي عنوانه. الموازنة وحدها تقسم حسب الارتفاع، وحين يمتد أحد الأفعال إلى سطر ثانٍ تترك Commands and history في أسفل العمود الأيسر. كل مدخل يبدأ بالشارتين نفسيهما، Ctrl وحرف، وكلتاهما بالخط الأحادي المسافة، فيبدأ كل فعل على المسافة نفسها من الحافة اليسرى لعموده.

الوصفة كاملة

Sandbox
// ═══ Postext Cookbook · Nº 048 · Code listings and keycaps ═══
// https://postext.dev/en/cookbook/code-listings-and-keycaps
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocument, prepareFonts, withLoadedFonts, renderPageToCanvas,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'code-listings-and-keycaps';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1b1f24', muted: '#5c636b', ember: '#9a5410', // text, heads, accent
  night: '#0e1116', code: '#d3d9df', amber: '#f2b134', phosphor: '#3ddc84', // the listings
  slate: '#8a939d' }; // comments in a listing, the outline of a key (code is its face)
// Every colour is linked to its palette entry by id.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.ember })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Charis SIL', 'Sora', 'JetBrains Mono'];
const LEAD = 14.5; // pt: the body leading, the page's baseline grid
const ZERO = pt(0);

// #region answer: a fence is a code listing; codeStyle gives it a dark box
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
  fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
  background: col('night'), span: 'page', // across the text and the margin
  padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
  marginTop: mm(6), marginBottom: mm(2.5),
  label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
    background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
    position: 'top-left' },
  tokens: tokens(), // the colours, below
  inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};
// #endregion

// #region paint: keywords amber, strings green, comments slate; a session's typed lines amber
function tokens() {
  const plain = { color: col('code') }; // every other kind in the listing's own colour
  return {
    keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },

يعمل ملف script.js المجمّع كما هو: الصقه في سكربت الوحدة (module) لأي صفحة، أو افتح الوصفة على CodePen. مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)

تنويعات

#علّق اللسان على اليمين

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

-    position: 'top-left' },
+    position: 'top-right' },

#رقّم الأسطر

تأخذ كل قائمة أرقام أسطر بالرمادي في هامش داخل إطارها. يشغل هذا الهامش نحو أربعة أحرف من الأحرف الثلاثة والسبعين، فلا يعود التعليق الذي يفتتح backup.sh يتسع: ينكسر بعد backup، وتنزل disk. إلى السطر التالي خلف ». ويُصدر فحص كتاب الوصفات التحذير codeOverflow؛ اختصر التعليق ليبقى السكربت في أسطره الثلاثة عشر. ولترقيم قائمة واحدة اكتب {lineNumbers} في سطر فتحها.

+  lineNumbers: true, lineNumberColor: col('slate'),
   tokens: tokens(), // the colours, below

#أعطِ التعليقات لون السلاسل النصية

تأخذ التعليقات أخضر السلاسل النصية، بالمائل.

-    comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+    comment: { color: col('phosphor'), italic: true }, // the strings' green italic

أخطاء شائعة

خطأ شائع

يبدأ الإطار الجانبي بمحاذاة الكتلة التي تلي سياجه

في postext 1.4.1 يقف الإطار span: 'side' في العمود الجانبي على الارتفاع الذي بلغه النص عند سياجه، على سطر الشبكة التالي، وتحت أي إطار موجود هناك. ضع سياج الحاشية الجانبية قبل الفقرة التي تشرحها مباشرةً: إذا وضعته بعدها، بدأت الحاشية بجانب الفقرة التالية. والإطار الذي يتجاوز أسفل العمود ينزلق صعودًا حتى يستقر أسفله على أسفل العمود، بقدر ما يسمح الإطار الذي فوقه؛ وما لا يتسع بعد ذلك ينتظر العمود الجانبي في الصفحة التالية. ملاحظات الهامش →

  • أبقِ كل سطر شيفرة في حدود 73 حرفًا. السطر الأطول ينكسر عند آخر مسافة أو علامة ترقيم تتسع، ويستمر في السطر التالي خلف »، ويُطلق المحرّك تحذير codeOverflow؛ أما overflow: 'shrink' فينضّد القائمة كلها بحجم أصغر بدلًا من ذلك، و'clip' يقطع السطر عند حافة الإطار.
  • الجدولة في القائمة تتقدّم إلى المضاعف التالي لأربعة أعمدة (codeStyle.tabSize). السكربت المزاح بجدولات يعرضها محرّرك بعرض ثمانية أعمدة يخرج هنا أضيق.
  • مع ضبط codeStyle.inline لا تنكسر الشيفرة داخل السطر بين سطرين أبدًا، كما الشارة. المسار الطويل في النص الجاري، مثل ~/Pictures/2025/IMG_0977.MOV، ينتقل كاملًا إلى السطر التالي وقد يترك خلفه سطرًا متباعد الكلمات.

الحقوق

الوصفة
Ignacio Ferro
النص
نص أصلي, CC BY 4.0
الخطوط
Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (SIL OFL 1.1)
الشيفرة
MIT، مثل Postext
Sandbox