مجموعه‌ی کامل سینتکس Markdown

صفحه‌ی تست داخلی در /test/syntax. این صفحه فرم‌های Markdown (و چند فرم HTML) را که این اپلیکیشن واقعاً با mdsvex، Prism و CSS سایت رندر می‌کند جمع می‌کند. برای بررسی طرح‌بندی، راست‌به‌چپ (RTL)، چپ‌به‌راست (LTR) کد، کادرهای اخطار و رفت‌وبرگشت ویرایشگر از آن استفاده کنید.

فهرست مطالب

• پاراگراف‌ها و تأکید
• سرتیترها و لنگرها
• پیوندها
• تصاویر
• فهرست‌ها
• نقل‌قول‌ها
• تذکرات / کادرهای اخطار
• کد درون‌خطی و کلید کیبورد
• بلوک‌های کد محصور
• جداول
• خط افقی
• برجسته‌سازی با mark
• کارت‌های هاب
• نمونه‌ی مختلط راست‌به‌چپ
• الگوهای صفحه‌ی راهنما (از nix-shell)

---

پاراگراف‌ها و تأکید

یک پاراگراف ساده با متن پررنگ، کج، پررنگ کج، و مقداری inline code که در جمله ترکیب شده‌است تا شکستن خطوط و ایزوله‌سازی قابل‌مشاهده بمانند.

اگر تجزیه‌کننده (parser) آن‌ها را بپذیرد، می‌توانید از پررنگ با زیرخط و کج با زیرخط نیز استفاده کنید.

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

سرتیترها و لنگرها

سرتیتر ۱ (در صفحات محتوایی نادر است)

سرتیتر ۲

سرتیتر ۳

سرتیتر ۴

سرتیتر ۵

سرتیتر ۶

سرتیتر با هدف قطعه (fragment) صریح:

سرتیتر نام‌گذاری‌شده

پیوند به آن قطعه: پرش به سرتیتر نام‌گذاری‌شده.

پیوندها

• مسیر داخلی: گام‌های نخستین
• مستندات داخلی: نصب Nix
• HTTPS خارجی: nixos.org
• گیت‌هاب خارجی: NixOS/nix
• سبک YouTube (آیکون از طریق rehype): ویدیو نمونه
• پیوند خودکار: https://nix.dev/
• پیوند مبتنی بر ارجاع: راهنمای Nix
• پیوند با صفت title: Nixpkgs

شبیه به ایمیل (در صورت مجاز بودن): [email protected]

تصاویر

تصویر درون‌خطی با متن جایگزین (آیکون سایت):

تصویر پیوندداده‌شده:

فهرست‌ها

نامرتب:

• آلفا
• براوو
  • تو در تو ۱
  • تو در تو ۲
• چارلی

مرتب:

1. نخست
2. دوم
   1. مرتب تو در تو
   2. دوباره مرتب تو در تو
3. سوم

فهرست فشرده با کد درون‌خطی: nix، nixos-rebuild، /nix/store.

فهرست غیرفشرده:

• پاراگراف اول در یک آیتم فهرست.

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

• آیتمی دیگر.

سبک وظیفه (GFM، در صورت فعال بودن):

• آیتم انجام‌شده
• آیتم باز

نقل‌قول‌ها

یک نقل‌قول ادبی ساده. کدهای تو در تو مانند hello باید به صورت LTR باقی بمانند.

پاراگراف دوم در همان نقل‌قول.

نقل‌قول‌های تو در تو:

خط نقل‌قول درونی.

تذکرات / کادرهای اخطار

انتشار سایت دستورات MyST را به نقل‌قول‌هایی همراه با <span class="admonition-kind" data-kind="…"></span> و یک خط عنوان تبدیل می‌کند.

نکته

این یک کادر «نکته» است. پیوندها کار می‌کنند: nix.dev.

راهنمایی

برای ابزارهای آنی، nix shell را ترجیح دهید.

راهنمایی

در CSS هم‌خانواده‌ی tip است.

مهم

پیش از ارتقا، این مطلب را بخوانید.

توجه

هم‌خانواده با مهم.

هشدار

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

احتیاط

ابتدا دسترسی‌ها را بررسی کنید.

خطر

عملیات مخرب.

خطا

ساخت با شکست مواجه شد.

همچنین ببینید

مرتبط: واژه‌نامه.

مثال

یک مثال کاربردی کوتاه.

اعلان

نوع اعلان عمومی.

کادر اخطار همراه با بلوک کد محصور در داخل:

نکته

اجرا کنید:

$ nix --version
nix (Nix) 2.11.0

کادر اخطار همراه با فهرست:

راهنمایی

چک‌لیست:

• نصب Nix
• باز کردن یک ترمینال جدید
• اجرای nix --version

کادر قدیمی فقط با عنوان پررنگ (بدون تگ admonition-kind):

توجه

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

کد درون‌خطی و kbd

مسیرها و فلگ‌ها باید در پاراگراف‌های راست‌به‌چپ (RTL) به صورت چپ‌به‌راست (LTR) خوانده شوند: /nix/store، ~/.config/nix/nix.conf، --extra-experimental-features، pkgs.hello.

تراشه‌های شبیه صفحه‌کلید اغلب در این اپلیکیشن با بک‌تیک نوشته می‌شوند (Ctrl+E، Ctrl+K)؛ در صورت نیاز از HTML kbd هم استفاده می‌شود:

برای ویرایش در محیط توسعه، کلیدهای Ctrl+E را فشار دهید.

علامت‌گذاری ترکیبی: استفاده از foo.bar و a/b/c در کنار کلمات فارسی یا انگلیسی.

بلوک‌های کد محصورشده

Nix

{ pkgs ? import <nixpkgs> { } }:

pkgs.mkShell {
  packages = [
    pkgs.hello
    pkgs.cowsay
  ];
}

شل / Bash

$ curl -L https://nixos.org/nix/install | sh -s -- --daemon
$ nix --version

#!/usr/bin/env bash
set -euo pipefail
echo "hello from bash"

نشست شل

$ nix-env -iA nixpkgs.hello
installing 'hello-2.12.1'
$ hello
Hello, world!

تفاوت (Diff)

--- a/flake.nix
+++ b/flake.nix
@@ -1,5 +1,6 @@
 {
   description = "demo";
+  # added line
 }

JSON

{
  "name": "example",
  "version": 1,
  "nested": { "ok": true }
}

متن / plain

/nix/store/b6gvzjyb2pg0…-firefox-33.1

حصار بدون برچسب زبان

plain fence without a language tag
line two

اشاره به حصارها در متن

برای نوشتن یک حصار در مستندات، با سه بک‌تیک و شناسه‌ی زبان مانند nix شروع کنید.

جدول‌ها

پرچم	معنی	پیش‌فرض
max-jobs	درایویشن‌های موازی	1
cores	هسته‌ها به ازای هر ساخت	0 (همه)
NIX_BUILD_CORES	بازنشانی متغیر محیطی	از cores

نمایش ترازسازی:

چپ	وسط	راست
a	b	c
سلول طولانی‌تر	وسط	42

خط افقی

بالای خط.

---

پایین خط.

برجسته‌سازی با mark

Nix یک مدیر بسته‌ی کاملاً تابعی است. برجسته‌سازی به‌صورت HTML <mark> برای mdsvex باقی می‌ماند (در ویرایشگر درون‌صفحه‌ای: Ctrl+H).

کارت‌های هاب

HTML مختص سایت که در هاب‌های nix.dev استفاده می‌شود (توسط مسیر تبدیل HTML به Markdown در ویرایشگر حفظ می‌شود):

نمونه ترکیبی (متن فارسی)

هنگامی که صفحه راست‌به‌چپ (RTL) است، شناسه‌های انگلیسی باید چپ‌به‌راست (LTR) بمانند: با دستور curl -L https://nixos.org/nix/install | sh نصب کنید، سپس nix --version را بررسی کنید. مسیرهای انبار شبیه /nix/store/…-hello-2.12.1 هستند.

هشدار

اطلاعات محرمانه را در مسیری که به انبار کپی می‌شود قرار ندهید، برای مثال ./secrets/token.

الگوهای صفحه‌ی راهنما (از nix-shell)

الگوهای گرفته‌شده از /pages/nix-manual/command-ref/nix-shell (شامل #env-NIX_BUILD_SHELL). دقیقاً مانند نسخه‌ی منتشرشده در سایت نگه‌داشته شده‌اند تا نحوه‌ی رندر شدن و اشکالات قابل‌مشاهده باقی بمانند.

خلاصه (Synopsis) چندخطی

خلاصه‌ی دستور man page را نباید به‌صورت پاراگراف Markdown چندخطی نوشت (خطوط ادغام می‌شوند و بک‌تیک‌ها خراب جفت می‌شوند). شکل درست: بلوک text محصور (مثل صفحه‌ی nix-shell):

nix-shell
  [--arg name value]
  [--argstr name value]
  [{--attr | -A} attrPath]
  [--command cmd]
  [--run cmd]
  [--exclude regexp]
  [--pure]
  [--keep name]
  {{--packages | -p} {packages | expressions} … | [path]}

برای آکولاد خارج از حصار (در متن عادی) هنوز از escapeهای Svelte استفاده کنید: {'{'} و {'}'}.

متن‌های جایگزین اریب (Italic) در کنار پرچم‌ها (Flags)

• --command cmd ، اجرای cmd در یک شل تعاملی.
• --run cmd ، مشابه --command، اما غیرتعاملی.
• --exclude regexp ، رد کردن وابستگی‌هایی که مسیر انبار آن‌ها با regexp مطابقت دارد.
• --keep name ، حفظ متغیر محیطی name تحت --pure.

کد درون‌خطی داخل یک پیوند فرگمنت

همچنین ببینید NIX_BUILD_SHELL و NIX_PATH.

موجودیت‌های HTML: علامت‌های بزرگ‌تر/کوچک‌تر و شناسه‌ی span با escape

متن ساده با شکل موجودیت (entity) از یک مسیر Nix: شل از <nixpkgs> روی NIX_PATH می‌آید.

درون علامت‌های بَک‌تیک (همان‌طور که اغلب منتشر می‌شود): `<nixpkgs>` در مقایسه با حالت خام درون یک بلوک کد:

$ nix-shell '<nixpkgs>' --attr pan

شناسه‌ی محدوده‌ی فراریافته که یک شناسه پیوندخورده را دربر گرفته‌است (شکل انتشاریافته پیرامون متغیرهای محیطی):

• <span id="env-NIX_BUILD_SHELL">NIX_BUILD_SHELL</span>

  شل مورد استفاده برای راه‌اندازی محیط تعاملی. پیش‌فرض آن bash است که از bashInteractive در <nixpkgs> گرفته می‌شود، در غیر این صورت از bash روی PATH استفاده می‌کند.

کادرهای اخطار تو در تو زیر یک آیتم فهرست

• <span id="env-DEMO">DEMO_VAR</span>

  توضیحات متغیر.

  نکته

  یادداشت تو در تو زیر یک آیتم فهرست (فقط عنوان ضخیم، بدون محدوده‌ی admonition-kind).

  مثال

  کادر مثال تو در تو زیر همان آیتم فهرست.

حصار خراب در کادر اخطار (شکل انتشاریافته)

نحوه ارسال کدهای تو در تو در برخی از صفحات راهنما در حال حاضر (حصار باز به‌طور کامل داخل نقل‌قول نیست):

مثال

این کادر ممکن است حصار را به‌طور تمیز احاطه نکند:

  > #!/usr/bin/env -S nix-shell --pure
  > let
  >   pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/854fdc68881791812eddd33b2fed94b954979a8e.tar.gz") {};
  > in
  > pkgs.mkShell {
  >   buildInputs = pkgs.bashInteractive;
  > }
  > ```

### زبان‌های محصور اضافی (نمونه‌های shebang)

<span id="extra-langs"></span>

#### پایتون

```python
#! /usr/bin/env nix-shell
#! nix-shell -i python3 --packages python3 python3Packages.prettytable

import prettytable
print("hello")

پرل

#! /usr/bin/env nix-shell
#! nix-shell -i perl
#! nix-shell --packages perl

use strict;
print "hello\n";

Haskell

#! /usr/bin/env nix-shell
#! nix-shell -i runghc --packages 'haskellPackages.ghcWithPackages (ps: [ps.tagsoup])'

main = putStrLn "hello"

بلوک کد تورفته (بدون علامت fence)

تورفته با چهار فاصله (بدون سه بکتیک):

#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz

حصار تو در تو درست زیر یک کادر اخطار (برای مقایسه)

نکته

هنگامی که حصار به‌طور کامل درون نقل‌قول قرار دارد، این ساختار را ترجیح دهید:

$ nix-shell '<nixpkgs>' --attr pan --pure

---

پایان نمونه جامع. اگر موردی در اینجا به شکل نادرست رندر شد، پیش از دستکاری تک‌تک صفحات مستندات، CSS یا mdsvex را اصلاح کنید.