راهنمای نوشتن | حامد صمصامی

این راهنما چیست؟

این یادداشت یک مرجع زنده برای نوشتن یادداشت‌ها در این باغ دیجیتال است. مارک‌داون استاندارد، قابلیت‌های اختصاصی اوبسیدین و فیلدهای فرانت‌متر را پوشش می‌دهد. همه چیزهایی که در زیر می‌بینید از سورس خام رندر شده — پس می‌توانید هر الگویی را مستقیماً کپی کنید.

فرانت‌متر

هر یادداشت باید با یک بلوک فرانت‌متر YAML بین دو خط --- شروع شود. فیلدهای پشتیبانی‌شده:

---
title: "عنوان یادداشت شما"
description: "یک خلاصه تک‌خطی برای نمایش در کارت‌ها و سئو."
date: 2025-02-11
updated: 2025-06-15          # اختیاری — آخرین ویرایش معنادار
tags: [موضوع, زیرموضوع]
lang: fa                      # en یا fa
aliases: [نام-جایگزین, دیگر]  # نام‌های جایگزین برای حل ویکی‌لینک
growth: seedling              # seedling | budding | evergreen
featured: false               # true برای نمایش در صفحه اصلی
draft: false                  # true برای مخفی‌سازی از سایت
image: ./my-cover.jpg         # اختیاری — تصویر کاور هم‌محل (مسیر نسبی)
imageAlt: "متن توصیفی"        # اختیاری — متن جایگزین برای کاور (دسترس‌پذیری و سئو)
---

فیلدهای ضروری

فیلد	توضیح
`title`	عنوان نمایشی یادداشت
`date`	تاریخ ایجاد یا انتشار (`YYYY-MM-DD`)
`tags`	آرایه‌ای از برچسب‌ها برای فیلتر و کشف
`lang`	کد زبان — `en` یا `fa`

فیلدهای اختیاری

فیلد	پیش‌فرض	توضیح
`description`	—	خلاصه کوتاه برای کارت‌ها، جستجو و سئو
`updated`	—	تاریخ آخرین ویرایش معنادار
`aliases`	`[]`	نام‌های جایگزین که `[[ویکی‌لینک‌ها]]` را به این یادداشت حل می‌کنند
`growth`	`seedling`	مرحله بلوغ یادداشت
`featured`	`false`	نمایش در صفحه اصلی
`draft`	`false`	مخفی‌سازی از تمام لیست‌ها و صفحات
`image`	—	تصویر کاور — از مسیر نسبی به فایل هم‌محل استفاده کنید (مثلاً `./cover.jpg`)
`imageAlt`	عنوان	متن توصیفی جایگزین برای تصویر کاور (دسترس‌پذیری و سئو)

مراحل رشد

یادداشت‌ها با گذشت زمان تکامل می‌یابند. از فیلد growth برای نشان دادن بلوغ استفاده کنید:

🌱 seedling — ایده خام، تازه کاشته شده
🌿 budding — در حال شکل‌گیری، هنوز در حال رشد
🌳 evergreen — پخته و پایدار

مارک‌داون پایه

عناوین

از نماد # برای عناوین استفاده کنید. از ## (سطح ۲) به‌عنوان بالاترین سطح عنوان در یادداشت‌ها استفاده کنید چون سطح ۱ برای عنوان یادداشت رزرو شده است.

## عنوان بخش
### زیربخش
#### زیرزیربخش

قالب‌بندی متن

نحو	نتیجه
`پررنگ`	پررنگ
`کج`	کج
`*پررنگ و کج*`	پررنگ و کج
`کد درون‌خطی`	`کد درون‌خطی`
`~~خط‌خورده~~`	~~خط‌خورده~~
`==برجسته==`	==برجسته==

لینک‌ها

لینک‌های استاندارد مارک‌داون:

[متن لینک](https://example.com)
[لینک با عنوان](https://example.com "عنوان هنگام هاور")

لینک‌های خودکار — فقط آدرس را بگذارید تا قابل کلیک شود:

https://example.com

تصاویر

تصاویر استاندارد مارک‌داون:

![متن جایگزین](https://example.com/image.jpg)
![متن جایگزین](https://example.com/image.jpg "عنوان اختیاری")

برای تصاویر محلی، فایل‌ها را در public/images/notes/ قرار دهید و ارجاع دهید:

![توضیح](/images/notes/my-photo.jpg)

یا از روش جاگذاری اوبسیدین استفاده کنید (پایین‌تر توضیح داده شده).

فهرست‌ها

فهرست بدون شماره:

مورد اول
مورد دوم
- مورد تودرتو
  - تودرتوی عمیق‌تر

فهرست شماره‌دار:

مرحله اول
مرحله دوم
مرحله سوم

فهرست وظایف:

وظیفه انجام‌شده
وظیفه در انتظار
وظیفه دیگر در انتظار

نقل‌قول بلوکی

این یک نقل‌قول بلوکی است. می‌تواند چند خط باشد.

و شامل چند پاراگراف باشد.

نقل‌قول تودرتو:

سطح اول

سطح دوم

سطح سوم

خط‌های جداکننده

از ---، *** یا ___ در یک خط جداگانه برای ایجاد جداکننده استفاده کنید.

بلوک کد

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

function greet(name) {
  return `سلام، ${name}!`;
}

def greet(name: str) -> str:
    return f"سلام، {name}!"

.highlight {
  background-color: #fef08a;
  padding: 0.2em 0.4em;
  border-radius: 4px;
}

کد درون‌خطی با بک‌تیک: const x = 42;

جداول

| چپ | وسط | راست |
|:---|:---:|-----:|
| الف |  ب  |    پ |
| ت   |  ث  |    ج |

نتیجه:

چپ	وسط	راست
الف	ب	پ
ت	ث	ج

پاورقی

پاورقی با [^label] اضافه کنید و تعریف آن‌ها را هرجای یادداشت بنویسید:

این ادعا به منبع نیاز دارد[^1].

[^1]: منبع: نویسنده، «عنوان»، ۲۰۲۵.

این ادعا به منبع نیاز دارد¹.

ویکی‌لینک‌های اوبسیدین

ویکی‌لینک‌ها یادداشت‌ها را با [[براکت دوتایی]] به هم وصل می‌کنند. آن‌ها لینک‌های دوطرفه ایجاد می‌کنند که در بک‌لینک‌ها و نمای گراف نمایش داده می‌شوند.

ویکی‌لینک ساده

[[writing-guide]]

با اسلاگ (نام فایل بدون .md) به یادداشت لینک می‌دهد.

ویکی‌لینک با متن دلخواه

[[writing-guide|راهنمای کامل را بخوانید]]

از | برای جداکردن اسلاگ مقصد از متن نمایشی استفاده کنید: راهنمای کامل را بخوانید

لینک به عنوان خاص

[[writing-guide#کالاوت‌های اوبسیدین]]

اضافه کردن #عنوان مستقیماً به یک بخش لینک می‌دهد: writing-guide > کالاوت‌های اوبسیدین

لینک با نام مستعار

اگر یادداشتی aliases: [راهنمای-نحو] در فرانت‌مترش داشته باشد، می‌توانید با آن نام لینک دهید:

[[راهنمای-نحو]]

این به همان یادداشت حل می‌شود.

جاگذاری محتوا (Transclusion)

محتوای یادداشت دیگر را با ![[اسلاگ-یادداشت]] درون یادداشت فعلی جاگذاری کنید:

![[writing-guide]]

جاگذاری یک بخش خاص:

![[writing-guide#فرانت‌متر]]

این محتوا را به‌صورت درون‌خطی وارد می‌کند — عالی برای استفاده مجدد از بخش‌های مشترک بین یادداشت‌ها.

کالاوت‌های اوبسیدین

کالاوت‌ها جعبه‌های استایلی هستند که توجه را جلب می‌کنند. یک نقل‌قول بلوکی را با > [!TYPE] شروع کنید:

انواع موجود

اطلاعات عمومی یا جزئیات تکمیلی.

[!TIP] نکته مفید کالاوت‌ها از عنوان سفارشی پشتیبانی می‌کنند — فقط متن را بعد از نوع اضافه کنید.

هشدار مهم یا چیزی که باید مراقبش باشید.

هشدار بحرانی — چیزی که می‌تواند باعث از دست رفتن داده یا مشکلات جدی شود.

نتیجه مثبت یا اقدام تکمیل‌شده.

سؤالی برای بررسی یا بحث.

[!EXAMPLE] عنوان سفارشی اینجا می‌توانید هر نوع کالاوت را با عنوان سفارشی ترکیب کنید.

زمینه اطلاعاتی اضافی.

برای نقل‌قول‌های منسوب یا مطالب نقل‌شده از این استفاده کنید.

کالاوت‌های تاشونده

برای تاشونده کردن، + یا - را بعد از نوع اضافه کنید:

[!NOTE]+ باز به‌طور پیش‌فرض این کالاوت باز شروع می‌شود. روی عنوان کلیک کنید تا بسته شود.

[!TIP]- بسته به‌طور پیش‌فرض این کالاوت بسته شروع می‌شود. برای باز شدن کلیک کنید. عالی برای بخش‌های اختیاری طولانی یا اسپویلرها.

خلاصه نحو کالاوت

> [!TYPE]
> محتوا اینجا.

> [!TYPE] عنوان سفارشی
> محتوا اینجا.

> [!TYPE]+ باز به‌طور پیش‌فرض
> تاشونده، شروع باز.

> [!TYPE]- بسته به‌طور پیش‌فرض
> تاشونده، شروع بسته.

برجسته‌سازی

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

این یک ==مفهوم کلیدی== است که باید به خاطر بسپارید.

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

جاگذاری تصویر (سبک اوبسیدین)

تصاویر ذخیره‌شده در public/images/notes/ را با نحو اوبسیدین جاگذاری کنید:

![[my-photo.jpg]]
![[my-photo.jpg|متن جایگزین]]

شکل دوم متن جایگزین بعد از | برای دسترسی‌پذیری اضافه می‌کند.

کامنت‌ها

از %% برای اضافه کردن کامنت‌هایی استفاده کنید که در خروجی منتشرشده نامرئی هستند:

%%این یک کامنت مخفی است — فقط در سورس قابل مشاهده است.%%

برای گذاشتن یادداشت به خودتان، کارهای باقی‌مانده یا نکات ویرایشی هنگام نوشتن مفید است.

مرجع سریع

قابلیت	نحو
پررنگ	`متن`
کج	`متن`
برجسته	`==متن==`
خط‌خورده	`~~متن~~`
کد درون‌خطی	`کد`
ویکی‌لینک	`[[اسلاگ-یادداشت]]`
ویکی‌لینک (نام دلخواه)	`[[اسلاگ\|متن نمایشی]]`
جاگذاری یادداشت	`![[اسلاگ-یادداشت]]`
جاگذاری بخش	`![[اسلاگ-یادداشت#عنوان]]`
جاگذاری تصویر	`![[تصویر.jpg\|متن جایگزین]]`
کالاوت	`> [!TYPE] عنوان`
تاشونده (باز)	`> [!TYPE]+ عنوان`
تاشونده (بسته)	`> [!TYPE]- عنوان`
کامنت	`%%متن مخفی%%`
پاورقی	`[^برچسب]`
وظیفه	`- [ ] وظیفه` / `- [x] انجام‌شده`

منبع: نویسنده، «عنوان»، ۲۰۲۵. ↩

این راهنما چیست؟

فرانت‌متر

فیلدهای ضروری

فیلدهای اختیاری

مراحل رشد

مارک‌داون پایه

عناوین

قالب‌بندی متن

لینک‌ها

تصاویر

فهرست‌ها

نقل‌قول بلوکی

خط‌های جداکننده

بلوک کد

جداول

پاورقی

ویکی‌لینک‌های اوبسیدین

ویکی‌لینک ساده

ویکی‌لینک با متن دلخواه

لینک به عنوان خاص

لینک با نام مستعار

جاگذاری محتوا (Transclusion)

کالاوت‌های اوبسیدین

انواع موجود

کالاوت‌های تاشونده

خلاصه نحو کالاوت

برجسته‌سازی

جاگذاری تصویر (سبک اوبسیدین)

کامنت‌ها

مرجع سریع

Footnotes