> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/ar/mqalat-mtamqh/30-how-to-write-in-markdown-on-overleaf.md).
# كيفية الكتابة باستخدام Markdown على Overleaf
**تحديث ما بعد النشر** (أُضيف في 13 مايو 2017): نحن ممتنون لـ Vít Novotný، مؤلف/مُصانِع الـ `ماركداون` الحزمة، على مراسلته لنا ببعض الملاحظات المفيدة بشأن المقال الأصلي. ويسعدنا نشر هذه النسخة المحدَّثة التي تأخذ بنصائحه واقتراحاته بعين الاعتبار وتضمّنها.
### هاه، ماذا؟
[ماركداون](https://kirkstrobeck.github.io/whatismarkdown.com/) هي لغة ترميز خفيفة الوزن (أفهمت؟ 😉) تتيح لك كتابة شيءٍ ما كنص عادي مع بعض *جدًا* القواعد البسيطة، ثم تحويله إلى مخرجات منسقة، مثل HTML. وهي شائعة جدًا بين مطوري البرمجيات والمبرمجين، تحديدًا بسبب بساطتها (وأجرؤ على القول: إنها مثالية أيضًا لتدوين الملاحظات!).
على سبيل المثال، لكتابة قائمة تسوق سريعة:
```
# قائمة المشتريات
*تذكّر* أن نشتري أكبر قدر ممكن خلال [التخفيضات](http://acme-marg.com) القادمة!
## الطعام
- الفاصوليا المخبوزة
- السباغيتي
## القرطاسية
- دفتر كتابة
- أقلام رصاص
```
وستحصل على مخرجات HTML باستخدام أداة مثل [pandoc](http://pandoc.org/):
```html
قائمة المشتريات
تذكّر أن نشتري أكبر قدر ممكن خلال التخفيضات القادمة!
الطعام
- الفاصوليا المخبوزة
- السباغيتي
القرطاسية
```
جميل وبسيط! يمكنك العثور على صيغ أخرى للـ Markdown [هنا](https://daringfireball.net/projects/markdown/syntax).
### فماذا يعني هذا بالنسبة لي؟
يرضى كثير من مستخدمي LaTeX بوثائقهم الجميلة المُصفَّفة بـ LaTeX، لكنهم لا يستطيعون منع أنفسهم من الشعور بوخزة من الغيرة تجاه مستخدمي Markdown—لأن ترميز LaTeX، حسنًا، *يمكن* قد يصبح مطوّلًا جدًا أحيانًا. نعم، أيتها القوائم، نحن نتحدث عن *أنتم*...
والخبر السار هو أن الحزمة الجديدة الرائعة [`ماركداون` لحزمة LaTeX](https://ctan.org/pkg/markdown) تتيح لك كتابة صياغة markdown في مستندات LaTeX الخاصة بك (أي مدخلات أبسط) ومع ذلك تحصل على ملفات PDF منسقة بشكل جميل! كل ما عليك فعله هو تحميل `ماركداون` الحزمة في مستندك، وإحاطة مادة Markdown الخاصة بك داخل `ماركداون` البيئة:
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# قائمة المشتريات
*تذكّر* أن نشتري أكبر قدر ممكن خلال [التخفيضات](http://acme-marg.com) القادمة!
## الطعام
- الفاصوليا المخبوزة
- السباغيتي
## القرطاسية
- دفتر كتابة
- أقلام رصاص
\end{markdown}
\end{document}
```
أو إذا كنت تفضّل وضع مادة Markdown الخاصة بك في `*.md` :
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}
```
رائع! من المرجح جدًا أن يجعل هذا المطورين سعداء للغاية لأنهم يمكنهم الآن ببساطة نسخ `.md` التوثيق!
### هل ما زال بإمكاني استخدام أوامر LaTeX إذا كتبت Markdown؟
نعم، لا يزال بإمكانك استخدام أوامر LaTeX في مادة Markdown الخاصة بك! ما عليك سوى تمرير `الهجين` على `ماركداون`:
```latex
\usepackage[hybrid]{markdown}
...
- دفتر كتابة (من النوع الذي يحمل على الغلاف المعادلة الكبيرة $E=mc^2$)
```
### كيف يمكنني استخدام أحرف حرفية مثل '#' و'\_' (الشرطات السفلية)؟
#### كتابة '#'
لا يمكنك كتابة الحرف '#' *داخل `ماركداون` البيئة*. ولا حتى `\#` سيعمل. تحتاج إلى تعريف أمر مثل `\newcommand{\texthash}{\#}`، ثم تستخدم `\texthash` في `ماركداون` البيئة. وبالمثل بالنسبة للشرطات السفلية، خاصة عندما يكون هناك أكثر من واحد في السطر نفسه، مثلًا `$y = m_1 + n_2$`. أحيانًا قد يكون من الأسهل إنهاء `ماركداون` البيئة وكتابة الأسطر المسببة للمشكلات في وضع LaTeX العادي، ثم بدء أخرى `ماركداون` البيئة.
#### كتابة '\_' (شرطة سفلية) و'\`' (علامة backtick)
**تحديث** (أُضيف في 13 مايو 2017): منذ `ماركداون` الإصدار 2.5 يمكنك ضبط `underscores = false` و `codeSpans = false` لتعطيل الشرطات السفلية وعلامات backtick. وهذا يتيح كتابة الأسس السفلية الرياضية وعلامات الاقتباس في الوضع الهجين من دون الحاجة إلى الهروب. لدينا علامات النجمة للتأكيد، لذا فإن الشيء الوحيد المفقود فعليًا هو أمثلة الشيفرة المضمنة. شكرًا لـ Vít على النصيحة!
#### بيئات ينبغي تجنبها...
ومع أنه يمكنك استخدام backticks لكتابة نص حرفي ضمن السطر، أو إزاحة السطر بمقدار أربع مسافات لكتلة حرفية، فلا تستخدم `lstlisting` ولا `minted` بيئات LaTeX داخل `ماركداون` البيئات. فقط لا تفعل ذلك.
#### استخدام HTML داخل بيئة markdown
ولا، لا يمكنك استخدام HTML داخل بيئة LaTeX `ماركداون` البيئة (حتى وإن كان هذا أمرًا شائعًا في Markdown العادي). عذرًا.
**تحديث** (أُضيف في 13 مايو 2017): اعتبارًا من `ماركداون` الإصدار v2.3، توجد `html` خيار لن يعرض وسوم HTML حرفيًا إذا كانت موجودة في مادة markdown الخاصة بك، رغم أنه لن ينسّق محتوى الوسم أيضًا—أي `مرحبًا!` سيعرض فقط Hello! بخط عادي. لكن كيانات HTML مثل `©` ستُعرض على أنها ©. شكرًا لـ Vít على التنبيه إلى ذلك.
### خيارات حزمة markdown المقترحة
إحدى مجموعات `ماركداون` خيارات الحزمة التي قد تجدها مفيدة هي:
```latex
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
```
تُفعّل هذه الخيارات استخدام
* صياغة markdown للحواشي السفلية (مثل `[^1]`);
* قوائم التعريف و `#` للقوائم المرقمة؛
* النقاط الحذفية «الصحيحة» (…).
إليك [مثال كامل](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) في معرض Overleaf، وإليك [مثالًا آخر](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### الروابط التشعبية والحواشي السفلية: كيف؟
في مثال Overleaf، الرابط التشعبي هو حاشية سفلية. كيف أجعله رابط hyperref تشعبيًا؟
`ماركداون` قابل للتخصيص، لذا يمكنك تحديد الطريقة التي تريد بها عرض العناصر المختلفة. ستؤدي إضافة هذه إلى التمهيد الخاص بك إلى ذلك تمامًا:
```latex
\markdownSetup{renderers={
link = {\href{#2}{#1}}
}}
```
**تحديث** (أُضيف 13 مايو 2017): `rendererPrototypes` استُخدم في النسخة الأولى. يُنصح المستخدمون العاديون باستخدام `renderers` لتعريفاتهم الخاصة، لأن `rendererPrototypes` موجودة لكي يوفّر منشئو الحزم القيم الافتراضية. إذا عدّلت `rendererPrototypes`، فأنت تعرّض نفسك لاحتمال أن تقوم حزمة أخرى بتجاوز إعداداتك. شكرًا لـ Vít على التنبيه إلى ذلك!
### تضمين الصور (محدّث في 8 نوفمبر 2022)
* **ملاحظة**: يستخدم المثال التالي ملف رسومات (`example-image.pdf`) الموفَّر من قِبل `mwe` الحزمة. تُوزَّع ملفات الرسومات هذه مع TeX Live وبالتالي تكون مخزّنة على خوادم Overleaf، مما يجعلها متاحة كعناصر نائبة للصور، مثل المثال أدناه.
يمكن تضمين الصور في Markdown بكتابة ترميز بالشكل التالي:
```latex
```
نأمل أن تكون أسماء المعاملات `النص البديل`, `اسم-الملف` و `"تعليق الصورة"` تصف ما تفعله. إليك مثالًا لتوضيحها:
```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
% توفر حزمة mwe صورًا نموذجية. تحميلها
% ليس ضروريًا لأن تلك الصور موجودة ضمن مسار البحث الخاص بـ LaTeX.
% هنا، نقوم بتحميلها للوضوح في هذا المثال.
\usepackage{mwe}
\begin{document}
\begin{markdown}
يوضح هذا المثال كيفية استيراد ملف رسومات. نحن هنا نستخدم
صورة نموذجية مقدمة من حزمة `mwe`.
% استخدم \setkeys{Gin} إذا احتجت إلى تغيير حجم عرض الصورة
\setkeys{Gin}{width=.5\linewidth}
\end{markdown}
\end{document}
```
[افتح هذا المثال على Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)
ينتج هذا المثال المخرجات التالية:
#### ملاحظة حول عرض الصورة
مثل معظم الحزم، `ماركداون` يقوم بتحميل حزم أخرى، بما في ذلك [`keyval`](https://ctan.org/pkg/keyval?lang=en) و [`graphicx`](https://ctan.org/pkg/graphicx?lang=en)، للاستفادة من الأوامر والميزات التي توفرها. هنا، يتم ضبط عرض الصورة باستخدام الأمر `\setkeys` ، الذي توفره `keyvals`. `Gin` هي "عائلة" من المفاتيح يعرّفها `graphicx` الحزمة.
* **ملاحظة**نظرًا إلى أن أمر LaTeX، هنا `\setkeys`، يُستخدم *داخل* موقع `ماركداون` بيئة، فإن `الهجين` الخيار الخاص بحزمة markdown مطلوب.
#### تغيير محددات موضع العائم (أكثر تقدمًا)
صياغة markdown لتضمين الأشكال لا تتيح لك تحديد محددات موضع العائم مباشرةً، لكن يمكنك تعديلها بإعادة تعريف طريقة عرض الشكل:
```latex
\markdownSetup{renderers={
image = {\begin{figure}[hbt!]
\centering
\includegraphics{#3}%
\ifx\empty#4\empty\else
\caption{#4}%
\fi
\end{figure}}
}}
```
لمزيد من المعلومات راجع [توثيق markdown](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### هل يمكنك إنشاء جداول باستخدام markdown في LaTeX؟ 😀
للأسف، لا. الجداول مدعومة في [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) فقط، وحزمة LaTeX `ماركداون` لا تدعم ذلك حاليًا.
**تحديث** (أُضيف في 13 مايو 2017): استنادًا إلى نصيحة من Vít، من الممكن استخدام `contentBlocks` امتداد الصياغة منذ الإصدار 2.4، أو تعديل `inputFencedCode` المُعرِّض، لتحويل بعض النصوص بأسلوب CSV بسرعة إلى جدول.
### مزيد من مزايا حزمة markdown...؟
كما ذُكر سابقًا، إنها طريقة رائعة لتدوين الملاحظات، وعند دمجها مع بعض فئات مستندات LaTeX الجميلة أو إعدادات الحزم، تتيح لك الحصول على دفتر ملاحظات جميل في نهاية المحاضرة نفسها. على سبيل المثال، يمكنك استخدامها مع [فئات Tufte](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}
```
والصياغة القصيرة والبسيطة التي تجعل كتابة القوائم أكثر سهولة تعني أن لدينا الآن *طريقة سريعة جدًا* لـكتابة [عروض Beamer التقديمية](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) و [الملصقات](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
استمتعوا!
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/latex/ar/mqalat-mtamqh/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.