f4d75a4e5b
* feat(callout): revamp of the callouts * fix: doc * chore: refactor gh alert * feat: same colors on callouts and gh alerts * docs: more relevant examples * docs: i18n * docs: update existing callouts
12 KiB
title, weight, prev
| title | weight | prev |
|---|---|---|
| سازماندهی فایل‌ها | 1 | /docs/guide |
ساختار دایرکتوری
به‌طور پیش‌فرض، Hugo فایل‌های Markdown را در دایرکتوری content جستجو می‌کند و ساختار این دایرکتوری تعیین‌کننده ساختار نهایی خروجی وبسایت شماست.
این سایت را به عنوان مثال در نظر بگیرید:
{{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/file name="_index.md" >}} {{< filetree/folder name="docs" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="getting-started.md" >}} {{< filetree/folder name="guide" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="organize-files.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< filetree/folder name="blog" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="post-1.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}
هر یک از فایل‌های _index.md صفحه اصلی مربوط به بخش خود هستند. سایر فایل‌های Markdown صفحات معمولی هستند.
content
├── _index.md // <- /
├── docs
│ ├── _index.md // <- /docs/
│ ├── getting-started.md // <- /docs/getting-started/
│ └── guide
│ ├── _index.md // <- /docs/guide/
│ └── organize-files.md // <- /docs/guide/organize-files/
└── blog
├── _index.md // <- /blog/
└── post-1.md // <- /blog/post-1/
طرح‌بندی‌ها
Hextra سه طرح‌بندی برای انواع مختلف محتوا ارائه می‌دهد:
| طرح‌بندی | دایرکتوری | ویژگی‌ها |
|---|---|---|
docs |
content/docs/ |
مناسب برای مستندات ساختاریافته، مشابه این بخش. |
blog |
content/blog/ |
برای پست‌های وبلاگ، با نمایش لیست و مقاله‌های تفصیلی. |
default |
سایر دایرکتوری‌ها | نمایش تک‌صفحه‌ای مقاله بدون نوار کناری. |
برای سفارشی‌سازی یک بخش به منظور تقلید رفتار یک طرح‌بندی داخلی، نوع مورد نظر را در front matter فایل _index.md بخش مشخص کنید.
---
title: مستندات من
cascade:
type: docs
---
مثال پیکربندی بالا تضمین می‌کند که فایل‌های محتوا در content/my-docs/ به‌طور پیش‌فرض به عنوان مستندات (نوع docs) در نظر گرفته می‌شوند.
ناوبری نوار کناری
ناوبری نوار کناری به‌طور خودکار بر اساس سازماندهی محتوا به ترتیب الفبایی ایجاد می‌شود. برای پیکربندی دستی ترتیب نوار کناری، می‌توانیم از پارامتر weight در front matter فایل‌های Markdown استفاده کنیم.
---
title: راهنما
weight: 2
---
{{< callout type="info" >}} توصیه می‌شود نوار کناری را خیلی عمیق نگه ندارید. اگر محتوای زیادی دارید، آن‌ها را به چند بخش تقسیم کنید. {{< /callout >}}
ناوبری بخش
ترتیب صفحه‌بندی بخش
ترتیب صفحات، که از طریق PAGE.PrevInSection و PAGE.NextInSection در یک مجموعه صفحه قابل دسترسی هستند، به‌طور پیش‌فرض معکوس شده است.
برای غیرفعال کردن این ترتیب معکوس، می‌توانید پارامتر سفارشی reversePagination را در front matter صفحه به false تنظیم کنید. به‌طور پیش‌فرض reversePagination روی true تنظیم شده است.
مثال
با توجه به ساختار دایرکتوری زیر:
{{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/file name="_index.md" >}} {{< filetree/folder name="blog" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/folder name="my-blog-series" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/folder name="post-a" state="open" >}} {{< filetree/file name="index.md" >}} {{< /filetree/folder >}} {{< filetree/folder name="post-b" state="open" >}} {{< filetree/file name="index.md" >}} {{< /filetree/folder >}} {{< filetree/folder name="post-c" state="open" >}} {{< filetree/file name="index.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}
و front matter زیر در پست‌ها:
---
title: پست A
weight: 1
---
---
title: پست B
weight: 2
---
---
title: پست C
weight: 3
---
اگر خواننده در انتهای post-b/index.md باشد، می‌بیند که صفحه بعدی post-a و صفحه قبلی post-c است. این به دلیل تنظیم reversePagination روی true به‌طور پیش‌فرض است. این زمانی مناسب است که بخواهیم پست‌ها به ترتیب زمانی از جدیدترین به قدیمی‌ترین نمایش داده شوند. اما در مورد یک سری وبلاگ که چندین بخش دارد، معمولاً می‌خواهیم افراد ابتدا پست اول را بخوانند، سپس به پست دوم و غیره بروند. بنابراین می‌خواهیم ترتیب معکوس را غیرفعال کنیم.
می‌توانیم reversePagination را در هر پست وبلاگ در این سری با اضافه کردن front matter زیر به my-blog-series/_index.md خاموش کنیم:
---
title: سری وبلاگ من
cascade:
params:
reversePagination: false
---
در اینجا از cascade استفاده می‌کنیم تا این تنظیم به تمام پست‌های my-blog-series منتقل شود و reversePagination برای تمام فرزندان روی false تنظیم شود. این اکنون تضمین می‌کند که وقتی خواننده در post-b/index.md است، صفحه بعدی post-c و صفحه قبلی post-a خواهد بود.
ناوبری مسیر راهنما
مسیرهای راهنما به‌طور خودکار بر اساس ساختار دایرکتوری /content ایجاد می‌شوند.
به عنوان مثال، ساختار فایل نمایش داده شده در بالا را در نظر بگیرید. با توجه به آن ساختار، مسیرهای راهنمای بالای صفحه در /docs/guide/organize-files/ به‌صورت خودکار به این شکل نمایش داده می‌شوند:
مستندات > راهنما > سازماندهی فایل‌ها
سفارشی‌سازی عنوان لینک‌های مسیر راهنما
به‌طور پیش‌فرض، هر لینک مسیر راهنما بر اساس پارامتر title آن صفحه ایجاد می‌شود. می‌توانید این را با مشخص کردن linkTitle سفارشی کنید.
به عنوان مثال، اگر به جای Organize Files می‌خواستیم مسیر راهنما Foo Bar باشد:
---
linkTitle: Foo Bar
title: سازماندهی فایل‌ها
---
این اکنون مسیرهای راهنمای زیر را ایجاد می‌کند:
مستندات > راهنما > Foo Bar
مخفی کردن مسیرهای راهنما
می‌توانید مسیرهای راهنما را به‌طور کامل از یک صفحه با مشخص کردن breadcrumbs: false در front matter آن مخفی کنید:
---
breadcrumbs: false
title: سازماندهی فایل‌ها
---
پیکربندی دایرکتوری محتوا
به‌طور پیش‌فرض، دایرکتوری ریشه content/ توسط Hugo برای ساخت سایت استفاده می‌شود.
اگر نیاز به استفاده از دایرکتوری دیگری برای محتوا دارید، مثلاً docs/، این کار را می‌توان با تنظیم پارامتر contentDir در پیکربندی سایت hugo.yaml انجام داد.
اضافه کردن تصاویر
برای اضافه کردن تصاویر، ساده‌ترین راه این است که فایل‌های تصویر را در همان دایرکتوری فایل Markdown قرار دهید.
به عنوان مثال، یک فایل تصویر image.png را در کنار فایل my-page.md اضافه کنید:
{{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/file name="my-page.md" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}
سپس می‌توانیم از سینتکس Markdown زیر برای اضافه کردن تصویر به محتوا استفاده کنیم:
همچنین می‌توانیم از ویژگی page bundles Hugo استفاده کنیم تا فایل‌های تصویر را همراه با فایل Markdown سازماندهی کنیم. برای این کار، فایل my-page.md را به یک دایرکتوری my-page تبدیل کنید و محتوا را در یک فایل به نام index.md قرار دهید و فایل‌های تصویر را داخل دایرکتوری my-page قرار دهید:
{{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/folder name="my-page" >}} {{< filetree/file name="index.md" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}
به‌عنوان جایگزین، می‌توانیم فایل‌های تصویر را در دایرکتوری static قرار دهیم، که تصاویر را برای تمام صفحات قابل دسترس می‌کند:
{{< filetree/container >}} {{< filetree/folder name="static" >}} {{< filetree/folder name="images" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/file name="my-page.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}}
توجه کنید که مسیر تصویر با یک اسلش / شروع می‌شود و نسبت به دایرکتوری static است:
