Learning Markdown

قواعد پایه (Basic Syntax)

در این فصل با قواعد پایه مارک‌دون آشنا می‌شویم. تقریباً همه ویرایشگرها و برنامه‌هایی که از مارک‌دون پشتیبانی می‌کنند، از قواعد پایه‌ای پیروی می‌کنند که در نسخه اصلی توسط جان گروبر معرفی شده است. با این حال، هر مفسر ممکن است تفاوت‌ها و جزئیات خاص خود را داشته باشد که در فصل بعد به آن‌ها پرداخته خواهد شد.

عنوان‌ها (Headings)

برای ایجاد عنوان (Heading) کافی است قبل از متن یا کلمه مورد نظر، از علامت # استفاده کنید. تعداد این علامت‌ها می‌تواند بین ۱ تا ۶ باشد؛ هر چه تعداد # بیشتر باشد، اندازه عنوان کوچکتر خواهد بود.

برای نمونه، عنوان با یک # بزرگ‌ترین و عنوان با شش # کوچک‌ترین است:

# عنوان سطح ۱
## عنوان سطح ۲
### عنوان سطح ۳
#### عنوان سطح ۴
##### عنوان سطح ۵
###### عنوان سطح ۶

روش دیگر برای ایجاد عنوان (فقط سطح ۱ و ۲) این است که در خط بعد از متن، از علامت‌های = یا - استفاده کنید:

عنوان سطح ۱
===========

عنوان سطح ۲
-----------

تعداد علامت‌های = یا - در این روش مهم نیست و می‌تواند متغیر باشد.

پاراگراف‌ها

برای ایجاد پاراگراف در مارک‌دون کافی است بین دو بخش متن یک خط خالی قرار دهید:

این خط اول است

و این خط دوم است.

اگر بین خطوط متن فاصله نگذارید، همه‌ی آن‌ها یک پاراگراف واحد در نظر گرفته می‌شوند.

همچنین توجه داشته باشید اگر پاراگراف داخل یک لیست نیست، آن را با فاصله یا تب (Tab) شروع نکنید.؛ چون این کار باعث تغییر ناخواسته در قالب‌بندی می‌شود.

شکستن خط (Line Break)

گاهی لازم است به خط بعد بروید، بدون آنکه پاراگراف تازه‌ای ساخته شود. این کار در مارک‌دون با گذاشتن دو یا چند فاصله در انتهای خط و سپس فشردن کلید Enter انجام می‌شود:

این خط اول است
و این خط دوم است.

به این روش فاصله پایانی یا trailing whitespace گفته می‌شود. این روش همیشه ایدئال نیست؛ چون این فاصله‌ها در ویرایشگر دیده نمی‌شوند و ممکن است سهواً یا به‌طور عادت بعد از هر جمله گذاشته شوند.

برای شفافیت بیشتر، می‌توانید از تگ <br> استفاده کنید که نتیجه‌ی مشابهی دارد ولی کاملاً قابل‌تشخیص است:

این خط اول است <br>
و این خط دوم است.

تأکید (Emphasis)

در مارک‌دون می‌توان روی بخش‌هایی از متن تأکید کرد تا توجه بیشتری به آن جلب شود. این تأکید می‌تواند به شکل پررنگ، مورب، یا پررنگ و مورب همزمان باشد.

برای اعمال این سبک‌ها، علامت‌های مخصوص باید دقیقاً قبل و بعد از کلمه یا عبارت موردنظر قرار بگیرند، بدون فاصله اضافی بین علامت‌ها و متن:

• برای مورب کردن متن، یک علامت ستاره * یا یک خط زیر _ کافی است.
• برای پررنگ کردن متن، از دو علامت ستاره ** یا دو خط زیر __ در ابتدا و انتهای عبارت استفاده کنید.
• برای پررنگ و مورب همزمان، سه ستاره *** یا سه خط زیر ___ به‌کار می‌رود.

به نمونه‌های زیر توجه کنید:

**این متن پررنگ است**
*این متن مورب است*
***این متن پررنگ و مورب است***
این بخش از متن __پررنگ__ و این بخش هم _مورب_ است
و این بخش **_هردو آن می‌باشد_**

خروجی:

این متن پررنگ است
این متن مورب است
این متن پررنگ و مورب است
این بخش از متن پررنگ و این بخش هم مورب است
و این بخش هردو آن می‌باشد

نقل‌قول (Blockquote)

گاهی لازم است بخشی از متن یا جمله‌ای را به عنوان نقل‌قول بیاورید؛ مثلاً نقل‌قول از یک نویسنده، مستندات رسمی یا حتی تأکید بر یک بخش از متن. برای این کار، کافی است در ابتدای پاراگراف از علامت > استفاده کنید:

> این یک نقل‌قول است.

خروجی:

این یک نقل‌قول است.

نقل‌قول می‌تواند شامل چند پاراگراف باشد. در این حالت باید در خط خالی بین پاراگراف‌ها هم علامت > را بگذارید:

> این پاراگراف اول است.
>
> و این پاراگراف دوم است.

خروجی:

این پاراگراف اول است.

و این پاراگراف دوم است.

لیست‌ها (Lists)

لیست‌ها در مارک‌دون برای سازمان‌دهی محتوا، مرتب کردن مراحل یا نمایش نکات به کار می‌روند. دو نوع اصلی لیست وجود دارد: مرتب و بدون ترتیب. همچنین می‌توان این دو نوع را با هم ترکیب کرد یا لیست‌های تو در تو ساخت.

لیست مرتب (Ordered List)

برای ایجاد لیست مرتب، شماره‌گذاری را قبل از هر آیتم قرار دهید و بعد از آن یک نقطه بگذارید. لازم نیست شماره‌ها دقیق باشند؛ مارک‌دون به‌طور خودکار ترتیب را درست نمایش می‌دهد:

1. آیتم اول
1. آیتم دوم
1. آیتم سوم

خروجی:

1. آیتم اول
2. آیتم دوم
3. آیتم سوم

برای ایجاد لیست‌های تو در تو، آیتم‌های داخلی را با چهار فاصله یا یک تب (Tab) فاصله دهید:

1. آیتم اول
2. آیتم دوم
    1. آیتم تو در تو اول
    2. آیتم تو در تو دوم
3. آیتم سوم

خروجی:

1. آیتم اول
2. آیتم دوم
   1. آیتم تو در تو اول
   2. آیتم تو در تو دوم
3. آیتم سوم

لیست بدون ترتیب (Unordered List)

برای ایجاد لیست بدون ترتیب می‌توانید از خط تیره -، ستاره * و یا علامت جمع + استفاده کنید:

- آیتم اول
- آیتم دوم
- آیتم سوم

* آیتم اول
* آیتم دوم
* آیتم سوم

+ آیتم اول
+ آیتم دوم
+ آیتم سوم

خروجی همه‌ی این روش‌ها یکسان است:

• آیتم اول
• آیتم دوم
• آیتم سوم

لیست‌های بدون ترتیب هم می‌توانند تو در تو باشند؛ کافی است آیتم‌های داخلی را با چهار فاصله یا یک تب (Tab) فاصله دهید:

- آیتم اول
- آیتم دوم
    - آیتم تو در تو اول
    - آیتم تو در تو دوم
- آیتم سوم

خروجی:

• آیتم اول
• آیتم دوم
  • آیتم تو در تو اول
  • آیتم تو در تو دوم
• آیتم سوم

ترکیب لیست‌ها

می‌توانید لیست بدون ترتیب را داخل لیست مرتب قرار دهید یا برعکس:

1. مورد اول
2. مورد دوم
    - آیتم تو در تو اول
    - آیتم تو در تو دوم
3. مورد سوم

خروجی:

1. مورد اول
2. مورد دوم
   • آیتم تو در تو اول
   • آیتم تو در تو دوم
3. مورد سوم

کد (Code)

در مارک‌دون برای نمایش متن به صورت کد، دو روش اصلی وجود دارد: کد درون‌خطی و بلوک کد. علاوه بر این، نوع دیگری به نام بلوک کد حصار‌دار هم وجود دارد که در فصل‌های بعدی به آن پرداخته خواهد شد.

کد درون‌خطی (Inline Code)

برای مشخص کردن یک کلمه یا عبارت به عنوان کد، آن را بین دو بک‌تیک ` قرار دهید:

این `بخش` از جمله یک کد است.

خروجی:

این بخش از جمله یک کد است.

اگر متن شما شامل بک‌تیک باشد، می‌توانید از دو بک‌تیک پشت سر هم استفاده کنید:

``از `code` در فایل خود استفاده کنید.``

خروجی:

از `code` در فایل خود استفاده کنید.

بلوک کد (Code Block)

برای ایجاد یک بلوک کد چند خطی، کافی است هر خط را حداقل چهار فاصله (space) یا یک تب (Tab) به داخل (indent) ببرید:

    def greet(name):
        print(f"Hello, {name}!")

    greet("World")

خروجی:

def greet(name):
    print(f"Hello, {name}!")

greet("World")

نمایش تصویر

برای درج تصویر در مارک‌دون، از علامت تعجب ! قبل از متن جایگزین استفاده می‌کنیم. متن جایگزین را داخل کروشه [] می‌نویسیم و مسیر یا آدرس تصویر را داخل پرانتز () قرار می‌دهیم.

ساختار کلی:

![متن جایگزین](آدرس-یا-مسیر-تصویر)

مثال:

![Tux the Mascot](../files/Markdown/tux.png)

خروجی حاصل به این شکل خواهد بود:

خط جداکننده (Horizontal Rule)

برای ایجاد یک خط افقی که معمولاً برای جدا کردن بخش‌ها یا موضوعات استفاده می‌شود، کافی است سه علامت یا بیشتر از یکی از موارد آورده شده را در یک خط قرار دهید: ستاره (*)، خط تیره (-) یا زیرخط (_).

مثال‌ها:

***

----

________

خروجی رندر شده هر سه حالت یکسان خواهد بود:

لینک‌ها (Links)

در مارک‌دون چند روش برای ایجاد لینک وجود دارد. یکی از متداول‌ترین روش‌ها، ایجاد لینکی با متن دلخواه است. برای این کار، متن لینک را داخل کروشه [ ] و آدرس مقصد را داخل پرانتز ( ) می‌گذاریم. به عنوان مثال:

[Google](https://google.com)

در این نمونه، Google متن قابل کلیک است و https://google.com آدرس مقصد آن می‌باشد. خروجی به شکل زیر است:

Google

با کلیک روی متن، کاربر به آدرس مشخص شده هدایت می‌شود.

روش دیگر برای ایجاد لینک، تبدیل مستقیم یک URL یا آدرس ایمیل به لینک است. کافی است آن‌ها را داخل علامت‌های کوچک‌تر و بزرگ‌تر < > قرار دهید:

<https://eff.org>
<fake@example.com>

خروجی به این صورت خواهد بود و قابل کلیک است:

این روش‌ها باعث می‌شوند متون شما هم برای خواننده و هم برای موتورهای جستجو قابل دسترسی و کاربرپسند باشند.

نمایش کاراکترهای ویژه (Escaping Characters)

گاهی لازم است کاراکتری را که معمولاً در مارک‌دون برای قالب‌بندی استفاده می‌شود، به‌صورت معمولی نمایش دهیم. برای این کار کافی است قبل از آن کاراکتر یک بک‌اسلش (\) قرار دهید.

به عنوان مثال، علامت ستاره (*) معمولاً برای ایجاد لیست بدون ترتیب استفاده می‌شود. اگر بخواهیم بدون ایجاد لیست، فقط خود علامت ستاره را نمایش دهیم، باید از بک‌اسلش قبل آن استفاده کنیم:

\* این علامت ستاره به‌صورت معمولی نمایش داده شده است.

خروجی به شکل زیر خواهد بود:

* این علامت ستاره به‌صورت معمولی نمایش داده شده است.

تمرین‌ها

تمرین ۱

در این تمرین، هدف شما این است که متن خام زیر را با استفاده از مارک‌دون قالب‌بندی کنید و خروجی نهایی را مشابه نمونه در آورید:

1. متن خام را کپی کرده و در ویرایشگر مارک‌دون خود قرار دهید.
2. اطمینان حاصل کنید که:
   • تأکیدها حفظ شده‌اند
   • نقل‌قول به درستی با نمایش داده شده
   • لیست تو در تو، به درستی رندر شود

متن خام قابل کپی

اوپن سورس یک مدل توسعه نرم‌افزار است که کد منبع آن برای همه قابل دسترسی و تغییر است. این رویکرد به توسعه‌دهندگان اجازه می‌دهد تا نوآوری و همکاری را در سطح جهانی تجربه کنند. پروژه‌های اوپن سورس معمولاً توسط جوامع فعال پشتیبانی می‌شوند و این جوامع با به اشتراک گذاشتن دانش و منابع، کیفیت و امنیت نرم‌افزارها را بهبود می‌بخشند. بسیاری از متخصصان معتقدند:

اوپن سورس تنها به تولید نرم‌افزار محدود نمی‌شود؛ بلکه فلسفه‌ای برای آزادی و شفافیت در فناوری است.

مزایای استفاده از اوپن سورس:

دسترسی آزاد به کد منبع
نوآوری و همکاری جهانی
پروژه‌ها توسط جامعه توسعه‌دهندگان بهبود می‌یابند
اشکالات سریع‌تر شناسایی و رفع می‌شوند
انعطاف‌پذیری و سفارشی‌سازی
کاربران می‌توانند کد را تغییر داده و نرم‌افزاری مطابق نیاز خود بسازند

تمرین ۲

در این تمرین، هدف شما این است که متن خام زیر را با استفاده از Markdown قالب‌بندی کنید و خروجی نهایی را مشابه نمونه ایجاد نمایید:

1. قطعه کد پایتون را به صورت بلوک کد نمایش دهید.
2. یک تصویر با متن جایگزین مناسب درج کنید.
3. یک لینک قابل کلیک ایجاد کنید.

متن خام قابل کپی

نمونه کد پایتون به صورت زیر میباشد:

def add(a, b):
    return a + b

result = add(5, 3)
print("result:", result)

همچنین، وبسایت پایتون از اینجا قابل دسترسی میباشد و لوگوی پایتون به شکل زیر است:

def add(a, b):
    return a + b

result = add(5, 3)
print("result:", result)