انتقل إلى المحتوى

Markdown

يعرض ليڤانت غيت (LevantGit) ملفات Markdown بلهجة GitHub Flavoured Markdown نفسها تقريبًا، مع إضافات خاصة به: حلّ الروابط النسبية داخل الـ repository، والإشارة إلى الـ issues بأرقامها، والتعابير الرياضية بصيغة LaTeX، وترويسة YAML تتحكّم بجدول المحتويات. تشرح هذه الصفحة كلًّا منها بأمثلة.

ما هو Markdown؟

Markdown صيغة نص عادي لكتابة مستندات منسّقة؛ تتعرّف عليها بالامتداد .md. تكتب نصًا بسيطًا مع علامات خفيفة (مثل # للعناوين و** للخط العريض) فيعرضه ليڤانت غيت منسّقًا، مع بقاء الملف الأصلي مقروءًا كما هو. ستصادفه في ملف README وفي وصف الـ issues والـ pull requests والتعليقات والـ wiki.

توجد لهجات كثيرة من Markdown، ويحاول ليڤانت غيت الالتزام بـ «GitHub Flavoured Markdown (GFM)» قدر الإمكان، وهي امتداد لمعيار CommonMark الذي تستخدمه معظم المنصات الكبرى. فإن كنت قادمًا من GitHub فلن تجد مفاجآت تُذكر.

لمقدمة سريعة في الصياغة انظر وثائق GitHub:

كيف تُحلّ الروابط

عند عرض الروابط والصور والفيديو (<a href> و<img src> و<video src>) يحلّ ليڤانت غيت المسار بحسب السياق:

  • إن كان الرابط كاملًا يبدأ بـ https:// فيُترك كما هو.
  • إن كان مسارًا نسبيًا فيُحلّ بالنسبة إلى مسار أساس يعتمد على الموضع:
    • في سياق التعليقات (الـ issues، الـ pull requests، رسائل الـ commits) المسار الأساس هو صفحة الـ repository: /owner-name/repo-name.
    • في ملف Markdown داخل الـ repository المسار الأساس هو مسار الـ branch أو الـ commit الحالي.

رموز خاصة في الروابط

  • /:root: يُحلّ دائمًا إلى جذر الموقع https://levantgit.com، مهما كان موضع الملف.
  • ?raw=1: يدعم ليڤانت غيت هذه المعلمة المأخوذة من GitHub. طلب /owner-name/repo-name/src/branch/main/file?raw=1 يُحوَّل إلى /owner-name/repo-name/raw/branch/main/file، وهكذا تصل إلى المحتوى الخام (raw) من رابط نسبي (عادةً يضيف ليڤانت غيت الجزء src/ تلقائيًا ولا يمكنك تغييره).

أمثلة

لنفترض أنك تعرض ملف Markdown في /owner-name/repo-name/src/branch/main/dir:

  1. رابط كامل: https://example.org يبقى كما هو.
  2. نسبي من الملف الحالي: sub/file يصبح /owner-name/repo-name/src/branch/main/dir/sub/file.
  3. نسبي من جذر الـ repository: /sub/file (لاحظ الشرطة المائلة في البداية) يصبح /owner-name/repo-name/src/branch/main/sub/file.
  4. وسائط خام: إن كان الرابط في src لصورة أو فيديو فيُحلّ إلى /owner-name/repo-name/raw/....
  5. خام نسبي: sub/file?raw=1 يصبح /owner-name/repo-name/src/branch/main/dir/sub/file?raw=1 ثم يُحوَّل إلى /owner-name/repo-name/raw/branch/main/dir/sub/file.
  6. جذر صريح: /:root/any-path يصبح دائمًا https://levantgit.com/any-path دون أي معالجة أخرى.

نصيحة

إن كانت صورك في مجلد داخل الـ repository فاستخدم روابط نسبية عادية (images/logo.png) وسيعرضها ليڤانت غيت من المحتوى الخام تلقائيًا. لا تحتاج ?raw=1 إلا لرابط تنزيل مباشر.

الإشارة إلى الـ issues والـ pull requests

اكتب أرقام الـ issues أو الـ pull requests في قائمة:

* #123
* #456

فتُعرض مع عناوينها:

* the issue title (#123)
* the other issue title (#456)

التعابير الرياضية

يدعم ليڤانت غيت صياغة التعابير الرياضية (LaTeX) على غرار GitHub.

داخل السطر

  • $\alpha$: بين علامتي دولار مفردتين $.
  • $$\alpha$$: بين علامتي دولار مزدوجتين $$.
  • $`\alpha`$: دولار ثم علامات اقتباس مائلة، ويمكن تكرار علامات الاقتباس كما في كتل الكود العادية.

ككتلة مستقلة

باستخدام $$:

$$
\alpha
$$

أو بكتلة كود لغتها math:

```math
\alpha
```

الترويسة (frontmatter) وجدول المحتويات

الترويسة كتلة YAML في أول ملف Markdown بين سطرين من ---. يعرضها ليڤانت غيت افتراضيًا كجدول صغير فوق المحتوى، ولا يولّد جدول المحتويات (TOC) افتراضيًا. يمكنك تغيير السلوكين من الترويسة نفسها:

  • لتفعيل جدول المحتويات أضف include_toc: true.
  • لإخفاء الترويسة أضف gitea: none.

مثال:

---
include_toc: true
gitea: none
---

عند معاينة هذا الملف في ليڤانت غيت لن تظهر الترويسة، وسيظهر جدول محتويات في أعلى الصفحة مبني على عناوين الملف.

ماذا بعد؟

هذه الصفحة مبنية على وثائق Gitea (رخصة MIT) بعد ترجمتها وتبسيطها.