GitHub

Markdown

تصف هذه القسم صيغة ماركداون الخاصة بجوليا، والتي يتم تفعيلها بواسطة مكتبة ماركداون القياسية. العناصر التالية من ماركداون مدعومة:

Inline elements

هنا "مضمن" يشير إلى العناصر التي يمكن العثور عليها داخل كتل النص، أي الفقرات. تشمل هذه العناصر ما يلي.

Bold

قم بإحاطة الكلمات بنجمتين، **، لعرض النص المحاط بخط عريض.

A paragraph containing a **bold** word.

Italics

قم بإحاطة الكلمات بنجمة واحدة، *، لعرض النص المحاط بخط مائل.

A paragraph containing an *italicized* word.

Literals

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

A paragraph containing a `literal` word.

يجب استخدام الحروف الحرفية عند كتابة نص يشير إلى أسماء المتغيرات أو الدوال أو أجزاء أخرى من برنامج جوليا.

Tip

لإدراج حرف backtick داخل نص حرفي، استخدم ثلاثة backticks بدلاً من واحد لتضمين النص.

A paragraph containing ``` `backtick` characters ```.

من خلال التمديد، يمكن استخدام أي عدد فردي من العلامات الخلفية لتضمين عدد أقل من العلامات الخلفية.

$\LaTeX$

احط النص الذي يجب عرضه كرياضيات باستخدام صيغة $\LaTeX$ مع علامتي اقتباس مزدوجتين، ``.

A paragraph containing some ``\LaTeX`` markup.
Tip

كما هو الحال مع الحروف الحرفية في القسم السابق، إذا كان من الضروري كتابة علامات اقتباس حرفية داخل علامات اقتباس مزدوجة، استخدم عددًا زوجيًا أكبر من اثنين. لاحظ أنه إذا كان من الضروري تضمين علامة اقتباس حرفية واحدة داخل ترميز $\LaTeX$، فإن استخدام علامتي اقتباس مزدوجتين كافٍ.

Note

يجب الهروب من حرف \ بشكل مناسب إذا كان النص مضمنًا في كود مصدر جوليا، على سبيل المثال، "``\\LaTeX`` syntax in a docstring.", حيث يتم تفسيره كقيمة نصية. بدلاً من ذلك، لتجنب الهروب، من الممكن استخدام ماكرو السلسلة raw مع ماكرو @doc:

@doc raw"``\LaTeX`` syntax in a docstring." functionname

يمكن كتابة الروابط إلى الأهداف الخارجية أو الداخلية باستخدام الصيغة التالية، حيث النص المحاط بأقواس مربعة، [ ]، هو اسم الرابط والنص المحاط بأقواس عادية، ( )، هو عنوان URL.

A paragraph containing a link to [Julia](https://www.julialang.org).

من الممكن أيضًا إضافة مراجع متقاطعة إلى وظائف/طرق/متغيرات موثقة أخرى داخل وثائق جوليا نفسها. على سبيل المثال:

"""
    tryparse(type, str; base)

Like [`parse`](@ref), but returns either a value of the requested type,
or [`nothing`](@ref) if the string does not contain a valid number.
"""

سيؤدي هذا إلى إنشاء رابط في الوثائق المولدة إلى وثائق parse (التي تحتوي على مزيد من المعلومات حول ما تفعله هذه الوظيفة فعليًا) وإلى وثائق nothing. من الجيد تضمين المراجع المتقاطعة للإصدارات المتغيرة/غير المتغيرة من وظيفة ما، أو لتسليط الضوء على الفرق بين وظيفتين تبدوان متشابهتين.

Note

المرجع المتقاطع أعلاه ليس ميزة من ميزات Markdown، ويعتمد على Documenter.jl، والذي يُستخدم لبناء وثائق جوليا الأساسية.

Footnote references

يمكن كتابة مراجع الحواشي المسماة والمرقمة باستخدام الصيغة التالية. يجب أن يكون اسم الحاشية كلمة واحدة فقط تتكون من أحرف وأرقام دون علامات ترقيم.

A paragraph containing a numbered footnote [^1] and a named one [^named].
Note

يمكن كتابة النص المرتبط بالحاشية في أي مكان ضمن نفس الصفحة كمرجع الحاشية. يتم مناقشة الصيغة المستخدمة لتعريف نص الحاشية في قسم Footnotes أدناه.

Toplevel elements

يمكن كتابة العناصر التالية إما في "المستوى الأعلى" من الوثيقة أو داخل عنصر "مستوى أعلى" آخر.

Paragraphs

فقرة هي كتلة من النص العادي، قد تحتوي على أي عدد من العناصر المضمنة المحددة في قسم Inline elements أعلاه، مع وجود سطر أو أكثر فارغ فوقها وتحتها.

This is a paragraph.

And this is *another* paragraph containing some emphasized text.
A new line, but still part of the same paragraph.

Headers

يمكن تقسيم المستند إلى أقسام مختلفة باستخدام العناوين. تستخدم العناوين الصيغة التالية:

# Level One
## Level Two
### Level Three
#### Level Four
##### Level Five
###### Level Six

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

Tip

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

Code blocks

يمكن عرض كود المصدر ككتلة حرفية باستخدام مسافة بادئة من أربعة مسافات أو علامة تبويب واحدة كما هو موضح في المثال التالي.

This is a paragraph.

    function func(x)
        # ...
    end

Another paragraph.

بالإضافة إلى ذلك، يمكن احتواء كتل الشيفرة باستخدام ثلاث علامات اقتباس مع "لغة" اختيارية لتحديد كيفية تمييز كتلة الشيفرة.

A code block without a "language":

```
function func(x)
    # ...
end
```

and another one with the "language" specified as `julia`:

```julia
function func(x)
    # ...
end
```
Note

يجب تفضيل كتل الشيفرة "المسيجة" كما هو موضح في المثال الأخير على كتل الشيفرة المائلة لأنه لا يوجد طريقة لتحديد اللغة التي كتبت بها كتلة الشيفرة المائلة.

Block quotes

يمكن اقتباس النصوص من مصادر خارجية، مثل الاقتباسات من الكتب أو المواقع الإلكترونية، باستخدام > أحرف مسبوقة بكل سطر من الاقتباس كما يلي.

Here's a quote:

> Julia is a high-level, high-performance dynamic programming language for
> technical computing, with syntax that is familiar to users of other
> technical computing environments.

لاحظ أنه يجب أن يظهر فراغ واحد بعد حرف > في كل سطر. قد تحتوي الكتل المقتبسة على عناصر أخرى من المستوى الأعلى أو عناصر مضمنة.

Images

الصيغة الخاصة بالصور مشابهة لصيغة الروابط المذكورة أعلاه. إضافة حرف ! قبل الرابط ستعرض صورة من عنوان URL المحدد بدلاً من رابط له.

![alternative text](link/to/image.png)

Lists

يمكن كتابة القوائم غير المرتبة عن طريق إضافة * أو + أو - قبل كل عنصر في القائمة.

A list of items:

  * item one
  * item two
  * item three

لاحظ المسافتين قبل كل * والمسافة الواحدة بعدها.

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

Another list:

  * item one

  * item two

    ```
    f(x) = x
    ```

  * And a sublist:

      + sub-item one
      + sub-item two
Note

يجب أن تتماشى محتويات كل عنصر في القائمة مع السطر الأول من العنصر. في المثال أعلاه، يجب أن يكون كتلة التعليمات البرمجية المحاطة بمسافة بادئة قدرها أربعة مسافات لتتوافق مع i في item two.

تُكتب القوائم المرتبة عن طريق استبدال حرف "النقطة" ، إما * أو + أو - ، برقم صحيح موجب يتبعه إما . أو ).

Two ordered lists:

 1. item one
 2. item two
 3. item three

 5) item five
 6) item six
 7) item seven

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

Display equations

يمكن كتابة المعادلات الكبيرة في $\LaTeX$ التي لا تتناسب مع السطر داخل فقرة كمعادلات عرضية باستخدام كتلة التعليمات البرمجية المحاطة بعلامات "language" math كما في المثال أدناه.

```math
f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta
```

Footnotes

هذه الصيغة مرتبطة بالصيغة المضمنة لـ Footnote references. تأكد من قراءة هذا القسم أيضًا.

نص الحاشية يُعرّف باستخدام الصيغة التالية، التي تشبه صيغة مرجع الحاشية، باستثناء حرف : الذي يُضاف إلى تسمية الحاشية.

[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements
    indented by 4 spaces or one tab.

      * item one
      * item two
      * item three

    ```julia
    function func(x)
        # ...
    end
    ```
Note

لا يتم إجراء أي فحوصات أثناء التحليل للتأكد من أن جميع مراجع الحواشي لها حواشي مطابقة.

Horizontal rules

يمكن تحقيق ما يعادل علامة HTML <hr> باستخدام ثلاثة شرطات (---). على سبيل المثال:

Text above the line.

---

And text below the line.

Tables

يمكن كتابة الجداول الأساسية باستخدام الصيغة الموضحة أدناه. لاحظ أن جداول الماركداون لها ميزات محدودة ولا يمكن أن تحتوي على عناصر علوية متداخلة على عكس العناصر الأخرى التي تم مناقشتها أعلاه - فقط العناصر المضمنة مسموح بها. يجب أن تحتوي الجداول دائمًا على صف رأس مع أسماء الأعمدة. لا يمكن للخلايا أن تمتد عبر صفوف أو أعمدة متعددة من الجدول.

| Column One | Column Two | Column Three |
|:---------- | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |
Note

كما هو موضح في المثال أعلاه، يجب محاذاة كل عمود من أحرف | عموديًا.

يحدد حرف : الموجود في أي طرف من فاصل رأس العمود (الصف الذي يحتوي على أحرف -) ما إذا كان الصف محاذيًا لليسار أو لليمين، أو (عندما يظهر : في كلا الطرفين) محاذيًا في المنتصف. عدم توفير أي أحرف : سيؤدي إلى محاذاة العمود لليمين بشكل افتراضي.

Admonitions

يمكن استخدام الكتل المنسقة بشكل خاص، المعروفة باسم التنبيهات، لتسليط الضوء على ملاحظات معينة. يمكن تعريفها باستخدام بناء الجملة !!! التالي:

!!! note

    This is the content of the note.
    It is indented by 4 spaces. A tab would work as well.

!!! warning "Beware!"

    And this is another one.

    This warning admonition has a custom title: `"Beware!"`.

الكلمة الأولى بعد !!! تعلن نوع التنبيه. هناك أنواع تنبيهات قياسية يجب أن تنتج تنسيقًا خاصًا. وهي (ترتيبًا حسب شدة الخطورة): danger، warning، info/note، و tip.

يمكنك أيضًا استخدام أنواع التحذيرات الخاصة بك، طالما أن اسم النوع يحتوي فقط على أحرف لاتينية صغيرة (a-z). على سبيل المثال، يمكنك أن يكون لديك كتلة terminology مثل هذه:

!!! terminology "julia vs Julia"

    Strictly speaking, "Julia" refers to the language,
    and "julia" to the standard implementation.

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

يمكن توفير عنوان مخصص للصندوق كسلسلة (داخل علامات اقتباس مزدوجة) بعد نوع التحذير. إذا لم يتم تحديد نص العنوان بعد نوع التحذير، فسيتم استخدام اسم النوع كعنوان (مثل "ملاحظة" لنوع التحذير note).

يمكن أن تحتوي التحذيرات، مثل معظم العناصر الرئيسية الأخرى، على عناصر رئيسية أخرى (مثل القوائم، الصور).

Markdown String Literals

تسمح لك ماكرو md"" بإدراج سلاسل Markdown مباشرة في كود جوليا الخاص بك. تم تصميم هذا الماكرو لتبسيط تضمين النصوص المنسقة بتنسيق Markdown داخل ملفات المصدر الخاصة بجوليا.

Usage

result = md"This is a **custom** Markdown string with [a link](http://example.com)."

Markdown Syntax Extensions

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

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

API reference

Markdown.MD — Type
MD

MD يمثل مستند Markdown. لاحظ أن مُنشئ MD لا ينبغي استخدامه مباشرةً، لأنه يقوم بإنشاء الهياكل الداخلية للبيانات. بدلاً من ذلك، يمكنك إنشاء كائنات MD باستخدام الماكروز المصدرة @md_str و @doc_str.

source
Markdown.@md_str — Macro
@md_str -> MD

قم بتحليل السلسلة المعطاة كنص Markdown وأعد كائن MD المقابل.

أمثلة

julia> s = md"# مرحبا، العالم!"
  مرحبا، العالم!
  ≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD
source
Markdown.@doc_str — Macro
@doc_str -> MD

قم بتحليل السلسلة المعطاة كنص Markdown، وأضف معلومات السطر والوحدة وأعد كائن MD المقابل.

يمكن استخدام @doc_str بالتزامن مع وحدة Base.Docs. يرجى أيضًا الرجوع إلى قسم الدليل حول التوثيق لمزيد من المعلومات.

أمثلة

julia> s = doc"f(x) = 2*x"
  f(x) = 2*x

julia> typeof(s)
Markdown.MD
source
Markdown.html — Function
html([io::IO], md)

قم بإخراج محتويات كائن Markdown md بتنسيق HTML، إما عن طريق الكتابة إلى دفق io (اختياري) أو إرجاع سلسلة.

يمكن استخدام show(io, "text/html", md) أو repr("text/html", md) كبديل، والتي تختلف في أنها تغلف الإخراج في عنصر <div class="markdown"> ... </div>.

أمثلة

julia> html(md"hello _world_")
"<p>hello <em>world</em></p>\n"
source
Markdown.latex — Function
latex([io::IO], md)

Output the contents of the Markdown object md in LaTeX format, either writing to an (optional) io stream or returning a string.

One can alternatively use show(io, "text/latex", md) or repr("text/latex", md).

أمثلة

julia> latex(md"hello _world_")
"hello \\emph{world}\n\n"
source