mdeck 3.10.0 → 3.11.0

package/examples/showcase/slides.ar.md

@@ -0,0 +1,567 @@
+---
+theme: neue
+meta:
+  title: "جولة في mdeck"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+  date: "2026-10-06"
+bibliography: refs.bib
+---
+
+---
+:::meta
+layout: title
+image: ./img/mdeck.svg
+fit: contain
+alt: "ملف Markdown يتحوّل إلى مجموعة من الشرائح"
+id: a-talk-in-a-text-file
+time: 1m
+:::
+# محاضرة في ملف نصي.
+## جولة في mdeck: كل شريحة تعرض *ما هو مكتوب* وما يصير إليه.
+
+:::notes
+يعلّمك هذا العرض mdeck بالأمثلة. معظم الشرائح تعرض نص Markdown بجانب ما يصير إليه. افتح `slides.ar.md` إلى جانبه: كل شريحة هنا مكتوبة تمامًا كما تظهر.
+
+تنقّل فيه بمفاتيح الأسهم أو بمفتاح المسافة. هذه الملاحظات لك وحدك؛ افتح عرض المقدِّم من صفحة الإطلاق لتراها بجانب الشريحة.
+
+الجولة متوفرة أيضًا بالإنجليزية (`slides.en.md`) وبالألمانية (`slides.de.md`). شغّلها بالأمر `mdeck run slides.ar.md`، والمفتاح **L** في عرض المقدِّم ينقل كل النوافذ إلى اللغة التالية.
+:::
+
+---
+:::meta
+layout: chapter
+number: 1
+part: الكتابة
+description: Markdown عادي، الصيغة التي يكتبها مساعدو الذكاء الاصطناعي أصلًا. يمكنك قراءة كل كلمة وتغييرها.
+time: 15s
+:::
+# اكتبها.
+
+:::notes
+في الواقع يكتب مساعد ذكاء اصطناعي هذا الملف عادةً من موادك أنت: شرائح قديمة، أو مستند، أو ملاحظاتك. مهارة `write-slides` تعلّمه mdeck. تعرض الشرائح التالية ما يكتبه، لتتمكن من قراءته وتعديله.
+:::
+
+---
+:::meta
+layout: split
+time: 1m
+:::
+# الكلمات تصير شرائح
+:::slot left
+```markdown
+# مغامرتنا القادمة
+
+فقرة من نص عادي.
+
+---
+
+# الفكرة التالية
+```
+:::
+:::slot right
+## مغامرتنا القادمة
+
+فقرة من نص عادي.
+
+ثلاث شرطات في سطر مستقل تبدأ الشريحة التالية.
+:::
+
+:::notes
+`#` هو عنوان الشريحة. السطر الفارغ يفصل بين الفقرات.
+
+جرّب: غيّر عنوانًا في `slides.ar.md` واحفظ الملف. تتحدّث الشريحة وهي مفتوحة.
+:::
+
+---
+:::meta
+layout: split
+time: 45s
+:::
+# القوائم والتوكيد
+:::slot left
+```markdown
+- أحضر دفترًا.
+- اطرح **سؤالًا واحدًا جيدًا**.
+- شارك ما تتعلّمه *أنت*.
+
+1. استمع
+2. لخّص
+```
+:::
+:::slot right
+- أحضر دفترًا.
+- اطرح **سؤالًا واحدًا جيدًا**.
+- شارك ما تتعلّمه *أنت*.
+
+1. استمع
+2. لخّص
+:::
+
+:::notes
+`**bold**` و`*emphasis*`؛ والقالب يحدّد شكل التوكيد. في هذا القالب يأخذ لون التمييز.
+:::
+
+---
+:::meta
+time: 1m
+:::
+# اكشف النقاط واحدة تلو الأخرى
+
+:::columns
+```markdown
+:::steps
+- أولًا، سؤال.
+- ثم، وقفة.
+- ثم، الجواب.
+:::
+```
++++
+:::steps
+- أولًا، سؤال.
+- ثم، وقفة.
+- ثم، الجواب.
+:::
+:::
+
+:::notes
+اضغط مفتاح التقدّم: كل ضغطة تكشف نقطة واحدة، ثم تنتقل إلى الشريحة التالية. الشرائح المطبوعة وملف PDF تعرض كل النقاط.
+
+ليس لهذه الشريحة تخطيط: `:::columns` يضع المصدر والنتيجة جنبًا إلى جنب، و`+++` يبدأ العمود الثاني.
+:::
+
+---
+:::meta
+layout: chapter
+number: 2
+part: التخطيطات والمحتوى
+description: التخطيطات والصور والشيفرة والجداول والتنبيهات. اختر تخطيطًا لكل شريحة، والقالب يتكفّل بالباقي.
+time: 15s
+:::
+# رتّبها.
+
+---
+:::meta
+layout: split
+props:
+  ratio: [3, 2]
+time: 1m
+:::
+# اختر تخطيطًا
+:::slot left
+```markdown
+:::meta
+layout: focus
+attribution: "معلّم"
+:::
+# الأسئلة الجيدة تصنع
+# حوارات أفضل.
+```
+:::
+:::slot right
+كتلة `:::meta` في أعلى الشريحة تحمل إعداداتها.
+
+`layout: focus` يصنع عبارة واحدة كبيرة. الشريحة التالية هي هذه بالضبط.
+:::
+
+:::notes
+من دون تخطيط تكون الشريحة عنوانًا عاديًا مع محتوى. هذه الشريحة `layout: split`، وجانباها مكتوبان كـ`:::slot left` و`:::slot right`؛ و`ratio: [3, 2]` يعطي الشيفرة مساحة أكبر.
+
+التخطيطات المدمجة هي `title` و`chapter` و`focus` و`split` و`image-text` و`full-bleed-image`.
+:::
+
+---
+:::meta
+layout: focus
+attribution: "معلّم"
+time: 30s
+:::
+# الأسئلة الجيدة تصنع حوارات أفضل.
+
+---
+:::meta
+layout: image-text
+image: ./img/image.jpg
+alt: "خطوط كنتورية مثل تلك التي على الخرائط"
+time: 45s
+:::
+# صورة بجانب كلماتك
+
+```markdown
+:::meta
+layout: image-text
+image: ./img/image.jpg
+alt: "خطوط كنتورية"
+:::
+```
+
+`alt` يصف الصورة لمن لا يستطيع رؤيتها.
+
+:::notes
+احفظ الصور في مجلد بجانب الشرائح، وهو هنا `img/`. الشريحة التالية تستخدم الصورة نفسها مع `layout: full-bleed-image`.
+:::
+
+---
+:::meta
+layout: full-bleed-image
+image: ./img/image.jpg
+alt: "خطوط كنتورية مثل تلك التي على الخرائط"
+overlay: true
+time: 30s
+:::
+# أو دع الصورة تملأ الشريحة.
+
+:::notes
+هذه الشريحة مكتوبة هكذا:
+
+```markdown
+:::meta
+layout: full-bleed-image
+image: ./img/image.jpg
+overlay: true
+:::
+# أو دع الصورة تملأ الشريحة.
+```
+
+`overlay: true` يعتّم الصورة كي يبقى العنوان مقروءًا.
+:::
+
+---
+:::meta
+layout: split
+time: 1m30s
+:::
+# شيفرة يمكنك تشغيلها
+:::slot left
+````markdown
+```python live editable
+squares = [x**2 for x in range(1, 6)]
+print(squares)
+```
+````
+:::
+:::slot right
+```python live editable
+squares = [x**2 for x in range(1, 6)]
+print(squares)
+```
+:::
+
+:::notes
+اضغط Run. `live` يضيف الزر، و`editable` يتيح لك تغيير الشيفرة أثناء العرض، و`copy` يضيف زر نسخ. وتعمل JavaScript بالطريقة نفسها.
+
+تنزّل Python الحيّة بيئة تشغيلها في المرة الأولى، لذا تحتاج إلى اتصال بالإنترنت.
+:::
+
+---
+:::meta
+layout: split
+time: 45s
+:::
+# الجداول والمعادلات
+:::slot left
+```markdown
+| الطبقة | من يملكها |
+|---|---|
+| الكلمات | أنت |
+| المظهر | القالب |
+
+$$
+A = \pi r^2
+$$
+```
+:::
+:::slot right
+| الطبقة | من يملكها |
+|---|---|
+| الكلمات | أنت |
+| المظهر | القالب |
+
+$$
+A = \pi r^2
+$$
+:::
+
+:::notes
+تُكتب المعادلات بـLaTeX. علامة دولار واحدة تضع المعادلة داخل الجملة؛ وعلامتا دولار فوقها وتحتها تضعانها في سطر مستقل.
+:::
+
+---
+:::meta
+layout: split
+time: 45s
+:::
+# نصائح وتحذيرات
+:::slot left
+```markdown
+:::tip
+نصيحة واحدة لكل شريحة تكفي.
+:::
+
+:::warning
+افحص جهاز العرض في القاعة.
+:::
+```
+:::
+:::slot right
+:::tip
+نصيحة واحدة لكل شريحة تكفي.
+:::
+
+:::warning
+افحص جهاز العرض في القاعة.
+:::
+:::
+
+:::notes
+التنبيهات الأخرى هي `note` و`important` و`caution`. أضف تسميتك الخاصة بعد النوع، مثلًا `:::tip قبل المحاضرة`.
+:::
+
+---
+:::meta
+layout: split
+time: 1m
+:::
+# اذكر مصادرك
+:::slot left
+```markdown
+---
+bibliography: refs.bib
+---
+
+الاستذكار يتفوّق على إعادة القراءة
+[@roediger2006].
+```
+:::
+:::slot right
+الاستذكار يتفوّق على إعادة القراءة [@roediger2006].
+
+المحاضرات التي تتضمن تعلّمًا نشطًا تخفض معدلات الرسوب بمقدار الثلث [@freeman2014].
+:::
+
+:::notes
+`refs.bib` ملف BibTeX كما يصدّره Zotero؛ وتعمل أيضًا CSL-JSON وHayagriva. تسرد كل شريحة مراجعها فوق التذييل، و`<bibliography />` على شريحة ما يسردها كلها. و`csl: vancouver` يحوّل الإحالات إلى أرقام.
+:::
+
+---
+:::meta
+layout: chapter
+number: 3
+part: التقديم
+description: ملاحظات لك، والرسم على الشرائح، وأسئلة للحضور.
+id: give-the-talk
+time: 15s
+:::
+# ألقِ المحاضرة.
+
+---
+:::meta
+layout: split
+time: 1m
+:::
+# ملاحظات لا يراها سواك
+:::slot left
+```markdown
+:::notes
+توقّف هنا. اسأل من جرّب
+هذا من قبل.
+:::
+```
+:::
+:::slot right
+توضع الملاحظات تحت محتوى الشريحة. تظهر في **عرض المقدِّم**، ولا تظهر أبدًا على جهاز العرض.
+
+افتحه من صفحة الإطلاق، وانقل **نافذة الحضور** إلى جهاز العرض. وتتبع النافذتان إحداهما الأخرى.
+:::
+
+:::notes
+توقّف هنا. اسأل من جرّب هذا من قبل.
+
+هذا ما يعرضه عرض المقدِّم لهذه الشريحة. ويعرض رأسه أيضًا ما هو متصل: عروض مقدِّم أخرى، ونوافذ الحضور، والهواتف.
+:::
+
+---
+:::meta
+id: draw-on-any-slide
+time: 1m
+:::
+# ارسم على أي شريحة
+
+اضغط **D** الآن، أو زر القلم. ارسم بقلم، أو بقلم تظليل، أو بقلم تأشير يتلاشى بعد لحظة. **Escape** يوقف الرسم.
+
+تُحفظ الرسوم في ملف `.drawings.json` بجانب الشرائح، وتظهر في ملف PDF.
+
+:::notes
+الخط تحت النص والدائرة على هذه الشريحة رُسما بالقلم وحُفظا؛ ويظهران في كل العروض وفي ملف PDF.
+
+على جهاز iPad، اقرنه من صفحة الإطلاق: ترسم وتتحكّم من هناك بينما يشغّل الحاسوب المحمول جهاز العرض.
+:::
+
+---
+:::meta
+layout: split
+hotspots: auto
+id: zoom-in-on-a-part
+time: 1m30s
+:::
+# كبّر جزءًا
+:::slot left
+```markdown
+:::meta
+hotspots: auto
+:::
+```
+
+في عرض المقدِّم، اضغط **رقمًا** لتكبير ذلك الجزء. الرقم نفسه، أو **0** أو **Escape** يعيدك.
+:::
+:::slot right
+| الطبقة | من يملكها |
+|---|---|
+| الكلمات | أنت |
+| المظهر | القالب |
+
+$$
+A = \pi r^2
+$$
+:::
+
+:::notes
+تظهر المفاتيح المرقّمة على هذه الشريحة هنا في عرض المقدِّم فقط، ولا تظهر أبدًا على جهاز العرض. اضغط 2 للجدول، و3 للمعادلة؛ ونافذة الحضور تتبعك. ومفاتيح الأسهم تخرج من التكبير وتنتقل إلى ما بعده بضغطة واحدة.
+
+`hotspots: auto` يجد الصور والشيفرة والجداول والمعادلات والتنبيهات. ضعه في إعدادات العرض في الأعلى لتظهر المفاتيح على كل شريحة، أو اكتب `marked` لتُعطى المفاتيح فقط للأجزاء الموسومة بـ`data-hotspot`. والمفتاح H يطفئ المفاتيح ويشغّلها أثناء المحاضرة.
+:::
+
+---
+:::meta
+layout: split
+time: 1m
+:::
+# وقّت محاضرتك
+:::slot left
+```markdown
+:::meta
+time: 1m
+:::
+```
+:::
+:::slot right
+أعطِ كل شريحة **مدة**. يعدّها عرض المقدِّم تنازليًا، ويخبرك إن كنت متقدّمًا أم متأخرًا.
+
+شغّل `mdeck rehearse slides.md` لتوقيت الشرائح أثناء التمرين، ثم احفظ الأوقات في الملف.
+:::
+
+:::notes
+لكل شريحة في هذه الجولة مدة، والمجموع 21 دقيقة. اضغط T في عرض المقدِّم لتشغيل المؤقّت: تحته ترى ما تبقّى من هذه الشريحة وأين وصلت المحاضرة.
+
+التمرين يقيس الأوقات عنك. في النهاية يقترحها مقرّبة إلى 15 ثانية؛ غيّر أيًّا منها قبل الحفظ.
+:::
+
+---
+:::meta
+time: 1m30s
+:::
+# أي جزء ستجرّبه أولًا؟
+
+<poll room="tour" options="الكتابة|التخطيطات|الرسم|الاستطلاعات" />
+
+:::notes
+سطر واحد يصنع استطلاعًا؛ والعنوان هو السؤال:
+
+`<poll room="tour" options="الكتابة|التخطيطات|الرسم|الاستطلاعات" />`
+
+تنضمّ الهواتف عبر رمز QR. ويمكنها الوصول إلى هذا الحاسوب حين تشغّل `mdeck run slides.md --network`.
+:::
+
+---
+:::meta
+layout: split
+time: 1m
+:::
+# كلمة واحدة من كل شخص
+:::slot left
+```markdown
+<wordcloud room="mood"
+  qr="false" />
+
+<scale room="pace" min="1" max="5"
+  low="بطيء جدًا" high="سريع جدًا" />
+
+<question room="ask" />
+```
+:::
+:::slot right
+<wordcloud room="mood" placeholder="كلمة واحدة" qr="false" />
+:::
+
+:::notes
+الهواتف التي انضمّت عبر رمز الاستطلاع تبقى متصلة: `qr="false"` يُخفي الرمز هنا. تظهر الإجابات فور وصولها.
+
+إلى جانب الاستطلاعات وسحب الكلمات هناك التقييمات (`<scale>`)، والأرقام ذات الإجابة الصحيحة (`<numeric>`)، والأسئلة المفتوحة (`<question>`). وإذا كان لديك عدد منها، فإن `<qrcode join />` على شريحة مبكرة يعرض الرمز مرة واحدة. ويحفظ `mdeck run` الإجابات في `slides.results.json` بجانب العرض.
+:::
+
+---
+:::meta
+layout: chapter
+number: 4
+part: المشاركة
+description: ملف واحد للإرسال، أو PDF، أو مجلد لموقع ويب.
+time: 15s
+:::
+# شاركها.
+
+---
+:::meta
+layout: split
+time: 45s
+:::
+# غيّر المظهر كله
+:::slot left
+```markdown
+---
+theme: work
+palette: lagoon
+---
+```
+:::
+:::slot right
+سطران في أعلى الملف يختاران القالب والألوان لكل الشرائح دفعة واحدة.
+
+لتجربتها دون تغيير الملف، افتح **عرض القارئ** واختر **Look**.
+:::
+
+:::notes
+في mdeck أربعة قوالب مدمجة وخمس لوحات ألوان، كلٌّ منها فاتح أو داكن. يعرضها `mdeck list` كلها، بما فيها المحفوظة في مجلد `extensions` بجانب العرض. ويجد `mdeck themes search` المزيد في مستودع القوالب.
+:::
+
+---
+:::meta
+layout: split
+time: 45s
+:::
+# أرسلها، اطبعها، انشرها
+:::slot left
+```sh
+mdeck send slides.md
+mdeck pdf slides.md
+mdeck build slides.md
+```
+:::
+:::slot right
+`send` يصنع ملف HTML واحدًا بلا ملاحظاتك، وفي داخله PDF. يفتحه الناس في المتصفح.
+
+`pdf` يصنع صفحة لكل شريحة. و`build` يصنع مجلدًا لخادم ويب.
+:::
+
+---
+:::meta
+layout: title
+time: 1m
+:::
+# والآن اصنع عرضك.
+## سلّم شرائحك أو مستنداتك أو ملاحظاتك إلى *مساعد ذكاء اصطناعي*.
+
+:::notes
+`mdeck skill --install claude` (أو codex أو cursor أو copilot أو gemini) يثبّت مهارة `write-slides`، التي تعلّم المساعد mdeck. ثم وجّهه إلى موادك: «أعد بناء lecture-03.pptx كمحاضرة مدتها 20 دقيقة.»
+
+من دون مساعد، يطرح `mdeck new` بضعة أسئلة ثم يبدأ عرضًا جديدًا.
+:::

package/examples/showcase/slides.de.drawings.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "width": 1920,
+  "height": 1080,
+  "slides": {
+    "draw-on-any-slide": [
+      {"id":"tour:underline","tool":"pen","color":"#e11d48","size":7,"points":[[135,464,0.45],[155,466,0.48],[175,468,0.52],[196,469,0.55],[216,470,0.58],[236,471,0.61],[257,471,0.64],[277,470,0.66],[298,469,0.68],[318,467,0.7],[338,466,0.72],[359,464,0.73],[379,462,0.74],[399,461,0.75],[420,460,0.75],[440,460,0.75],[460,461,0.74],[481,462,0.73],[501,463,0.72],[522,465,0.71],[542,467,0.69],[562,469,0.67],[583,471,0.64],[603,472,0.62],[623,473,0.59],[644,474,0.56],[664,474,0.53],[685,473,0.49],[705,472,0.46],[725,470,0.43],[746,469,0.39],[766,467,0.36],[786,466,0.33],[807,464,0.3],[827,464,0.27],[848,463,0.25],[868,464,0.22],[888,464,0.2],[909,466,0.19],[929,468,0.17],[949,470,0.16]]},
+      {"id":"tour:circle","tool":"pen","color":"#e11d48","size":6,"points":[[337,495,0.5],[341,495,0.54],[346,495,0.57],[350,496,0.6],[354,498,0.64],[358,501,0.66],[361,504,0.69],[363,508,0.71],[365,512,0.73],[366,516,0.74],[367,520,0.75],[366,524,0.75],[365,528,0.75],[363,532,0.74],[361,536,0.73],[358,538,0.71],[355,541,0.69],[351,543,0.66],[348,545,0.63],[344,546,0.6],[340,547,0.57],[336,547,0.54],[332,547,0.5],[328,547,0.46],[324,545,0.43],[320,544,0.4],[317,542,0.36],[314,539,0.34],[311,535,0.31],[309,532,0.29],[307,527,0.27],[307,523,0.26],[307,519,0.25],[308,514,0.25],[310,510,0.25],[312,507,0.26],[315,504,0.27],[318,501,0.29],[322,499,0.31],[326,498,0.34],[330,497,0.37],[334,497,0.4],[338,497,0.43],[342,497,0.47],[346,499,0.5],[350,500,0.54]]}
+    ]
+  }
+}