شروع سریع (Quickstart)

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

نصب (Installation)

ابزار Pelican (و اختیاری Markdown در صورت تمایل به استفاده) را روی Python >=3.9 با اجرای دستور زیر در ترمینال دلخواه خود نصب کنید؛ در صورت نیاز به مجوزهای مدیریتی، دستور را با sudo آغاز کنید:

python -m pip install "pelican[markdown]"

ایجاد یک پروژه (Create a project)

نخست، نامی برای پروژه خود انتخاب کنید، دایرکتوری مناسبی برای سایت خود بسازید و وارد آن شوید:

mkdir -p ~/projects/yoursite
cd ~/projects/yoursite

یک پروژه اولیه و خام را از طریق دستور pelican-quickstart بسازید؛ این دستور با پرسیدن چند پرسش پیرامون وب‌سایت شما آغاز می‌شود:

pelican-quickstart

برای پرسش‌هایی که مقادیر پیش‌فرض آن‌ها داخل قلاب نشان داده شده است، می‌توانید با فشردن کلید Return آن مقادیر پیش‌فرض را بپذیرید [1]. هنگامی که از شما پیشوند نشانی وب (URL prefix) خواسته شد، نام دامنه خود را مطابق راهنما (برای نمونه، https://example.com) وارد نمایید..SS ایجاد یک مقاله

تا زمانی که محتوایی ایجاد نکرده باشید، نمی‌توانید Pelican را اجرا کنید. با استفاده از ویرایشگر متنی مورد علاقه خود، نخستین مقاله را با محتوای زیر بسازید:

Title: My First Review
Date: 2010-12-03 10:20
Category: Review
Following is a review of my favorite mechanical keyboard.

با توجه به اینکه این مقاله نمونه در قالب Markdown است، آن را با عنوان ~/projects/yoursite/content/keyboard-review.md ذخیره کنید.

تولید وب‌سایت

از دایرکتوری ریشه پروژه خود، دستور pelican را برای تولید وب‌سایت اجرا کنید:

pelican content

اکنون وب‌سایت شما درون دایرکتوری output/ تولید شده است. (ممکن است هشداری در رابطه با خوراک‌ها مشاهده کنید، اما این مورد هنگام توسعه محلی طبیعی است و فعلاً می‌توان آن را نادیده گرفت.)

پیش‌نمایش وب‌سایت

یک نشست ترمینال جدید باز کنید، به دایرکتوری ریشه پروژه بروید، و دستور زیر را برای راه‌اندازی سرور وب Pelican اجرا کنید:

pelican --listen

با رفتن به http://localhost:8000 در مرورگر خود، پیش‌نمایش وب‌سایت را مشاهده کنید.

برای جزئیات بیشتر به خواندن سایر بخش‌های مستندات ادامه دهید، و صفحه راهنماهای ویکی Pelican https://github.com/getpelican/pelican/wiki/Tutorials را برای پیوندهای مربوط به آموزش‌های ارائه‌شده توسط جامعه کاربری بررسی کنید.

پاورقی‌ها

[1]

می‌توانید با نصب ماژول اختیاری tzlocal https://pypi.org/project/tzlocal به بومی‌سازی فیلدهای پیش‌فرض کمک کنید.

نصب Pelican

در حال حاضر Pelican روی >=3.9 به بهترین شکل اجرا می‌شود؛ نسخه‌های قدیمی‌تر Python پشتیبانی نمی‌شوند.

می‌توانید Pelican را با چندین روش مختلف نصب کنید. ساده‌ترین روش از طریق Pip https://pip.pypa.io است:

python -m pip install pelican

یا، اگر قصد استفاده از Markdown را دارید:

python -m pip install "pelican[markdown]"

(به یاد داشته باشید که در برخی سیستم‌عامل‌ها برای نصب Pelican به صورت سراسری در سیستم، لازم است در ابتدای دستور بالا sudo اضافه کنید.)

اگرچه روش بالا ساده‌ترین شیوه است، اما روش توصیه‌شده ساخت یک محیط مجازی برای Pelican از طریق virtualenv https://virtualenv.pypa.io/en/latest پیش از نصب Pelican است. با فرض اینکه virtualenv https://virtualenv.pypa.io/en/latest را نصب کرده‌اید، می‌توانید یک نشست ترمینال جدید باز کرده و یک محیط مجازی جدید برای Pelican ایجاد کنید:

virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
source bin/activate

پس از ایجاد و فعال‌سازی محیط مجازی، Pelican می‌تواند همان‌طور که در بالا اشاره شد از طریق python -m pip install pelican نصب شود. همچنین، اگر کد منبع پروژه را در اختیار دارید، می‌توانید Pelican را با استفاده از روش distutils نصب کنید:

cd path-to-Pelican-source
python setup.py install

اگر Git نصب دارید و ترجیح می‌دهید آخرین نسخه لبه توسعه (bleeding-edge) Pelican را به جای یک انتشار پایدار نصب کنید، از دستور زیر استفاده کنید:

python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"

پس از نصب Pelican، می‌توانید برای دیدن گزینه‌های پایه‌ای کاربرد، pelican --help را اجرا کنید. برای جزئیات بیشتر، به بخش Publish <> مراجعه کنید..SS بسته‌های اختیاری

اگر قصد دارید از Markdown https://pypi.org/project/Markdown به عنوان یک قالب نشانه‌گذاری استفاده کنید، می‌توانید Pelican را با پشتیبانی از Markdown نصب کنید:

python -m pip install "pelican[markdown]"

بهبودهای تایپوگرافی را می‌توان در فایل تنظیمات فعال کرد، اما ابتدا باید کتابخانهٔ الزامی Typogrify https://pypi.org/project/typogrify نصب شود:

python -m pip install typogrify

وابستگی‌ها

هنگام نصب Pelican، بسته‌های پایتونی وابستهٔ زیر باید به طور خودکار و بدون نیاز به هیچ اقدامی از سوی شما نصب شوند:

ارتقا

اگر نسخهٔ پایدار Pelican را از طریق Pip https://pip.pypa.io نصب کرده‌اید و مایلید آن را به آخرین نسخهٔ پایدار ارتقا دهید، می‌توانید این کار را با افزودن --upgrade انجام دهید:

python -m pip install --upgrade pelican

اگر Pelican را از طریق distutils یا روش توسعهٔ پیشرو (bleeding-edge) نصب کرده‌اید، کافی است همان مرحله را برای نصب جدیدترین نسخه تکرار کنید.

راه‌اندازی سریع وبگاه

پس از نصب Pelican، می‌توانید با استفاده از دستور pelican-quickstart که کار خود را با پرسیدن چند پرسش دربارهٔ وبگاه شما آغاز می‌کند، ساختار اولیهٔ یک پروژه را ایجاد کنید:

pelican-quickstart

اگر در یک محیط مجازی فعال اجرا شود، pelican-quickstart به دنبال مسیر پروژهٔ مرتبط درون $VIRTUAL_ENV/.project خواهد گشت. اگر آن فایل وجود داشته باشد و حاوی مسیر دایرکتوری معتبری باشد، پروژهٔ جدید Pelican در آن مکان ذخیره خواهد شد. در غیر این صورت، پیش‌فرض دایرکتوری کاری جاری است. برای تنظیم مسیر پروژهٔ جدید در فراخوانی اولیه، از این دستور استفاده کنید: pelican-quickstart --path /your/desired/directory

پس از پایان پاسخ‌گویی به تمام پرسش‌ها، پروژهٔ شما شامل ساختار سلسله‌مراتبی زیر خواهد بود (به جز pages — که در زیر درون پرانتز نشان داده شده است — و در صورتی که قصد ایجاد محتوای غیرگاه‌شمارانه دارید می‌توانید خودتان به صورت اختیاری آن را اضافه کنید):

yourproject/
├── content
│   └── (pages)
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

گام بعدی، شروع افزودن محتوا به پوشهٔ content است که برای شما ایجاد شده است.

نوشتن محتوا

مقاله‌ها و صفحه‌ها

‏Pelican موارد گاه‌شمارانه مانند پست‌های وبلاگ را "articles" (مقاله‌ها) در نظر می‌گیرد و از این رو آن‌ها را به یک تاریخ مرتبط می‌سازد.

ایدهٔ نهفته در "pages" (صفحه‌ها) این است که معمولاً ماهیت زمانی ندارند و برای محتوایی استفاده می‌شوند که چندان تغییر نمی‌کند (برای نمونه، صفحه‌های "About" یا "Contact").

می‌توانید محتوای نمونه را در مخزن در مسیر samples/content/ پیدا کنید..SS "فراداده فایل (File metadata)"

Pelican تلاش می‌کند به اندازه کافی هوشمند باشد تا اطلاعات مورد نیاز خود را از سامانه فایل دریافت کند (برای مثال، درباره دسته‌بندی مقاله‌های شما)، اما برخی از اطلاعات را باید در قالب فراداده درون فایل‌های خود ارائه دهید.

اگر محتوای خود را در قالب reStructuredText می‌نویسید، می‌توانید این فراداده را در فایل‌های متنی از طریق نحو زیر ارائه دهید (پسوند .rst را به فایل خود بدهید):

My super title
##############
:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds

فهرست‌های نویسندگان و برچسب‌ها می‌توانند در عوض با نقطه-ویرگول از هم جدا شوند، که به شما امکان می‌دهد نویسندگان و برچسب‌های حاوی کاما بنویسید:

:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan

Pelican افزونه‌ای را برای reStructuredText پیاده‌سازی می‌کند تا پشتیبانی از برچسب HTML به نام abbr فعال شود. برای استفاده از آن، چیزی شبیه به این در پست خود بنویسید:

This will be turned into :abbr:`HTML (HyperText Markup Language)`.

همچنین می‌توانید از نحو Markdown استفاده کنید (با فایلی با پسوند .md، .markdown، .mkd، یا .mdown). تولید Markdown نیازمند این است که ابتدا بسته Python-Markdown https://github.com/Python-Markdown/markdown را به صورت صریح نصب کنید، که می‌تواند از طریق pip install Markdown انجام شود.

همچنین Pelican از Markdown Extensions https://python-markdown.github.io/extensions پشتیبانی می‌کند، که در صورت عدم وجود در بسته پیش‌فرض Markdown ممکن است نیاز باشد جداگانه نصب شوند و می‌توان آن‌ها را از طریق تنظیمات MARKDOWN پیکربندی و بارگذاری کرد.

نحو فراداده برای پست‌های Markdown باید از این الگو پیروی کند:

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds
This is the content of my super blog post.

همچنین می‌توانید کلیدهای فراداده اختصاصی خود را داشته باشید (تا زمانی که با کلمات کلیدی رزرو شده فراداده تداخل نداشته باشند) تا در قالب‌های خود استفاده کنید. جدول زیر حاوی فهرستی از کلمات کلیدی رزرو شده فراداده است:

خواننده‌ها (Readers) برای قالب‌های بیشتر (مانند AsciiDoc https://asciidoc.org) از طریق افزونه‌ها در دسترس هستند، که می‌توانید آن‌ها را از طریق مجموعه Pelican Plugins https://github.com/pelican-plugins و همچنین مخزن قدیمی pelican-plugins https://github.com/getpelican/pelican-plugins بیابید.

همچنین Pelican می‌تواند فایل‌های HTML منتهی به .html و .htm را پردازش کند. Pelican سند HTML را به روشی بسیار ساده تفسیر می‌کند، به این صورت که فراداده را از برچسب‌های meta، عنوان را از برچسب title، و بدنه را از برچسب body می‌خواند:

<html>
    <head>
        <title>My super title</title>
        <meta name="tags" content="thats, awesome" />
        <meta name="date" content="2012-07-09 22:28" />
        <meta name="modified" content="2012-07-10 20:14" />
        <meta name="category" content="yeah" />
        <meta name="authors" content="Alexis Métaireau, Conan Doyle" />
        <meta name="summary" content="Short version for index and feeds" />
    </head>
    <body>
        This is the content of my super blog post.
    </body>
</html>

در مورد HTML، یک استثنای ساده برای فراداده استاندارد وجود دارد: برچسب‌ها را می‌توان هم از طریق فراداده tags (همان‌طور که در Pelican استاندارد است) و هم از طریق فراداده keywords (همان‌طور که در HTML استاندارد است) مشخص کرد. این دو را می‌توان به جای یکدیگر استفاده کرد.

توجه داشته باشید که به جز عنوان، هیچ‌یک از این فراداده‌های محتوا اجباری نیستند: اگر تاریخ مشخص نشده باشد و DEFAULT_DATE روی 'fs' تنظیم شده باشد، Pelican به برچسب زمانی "mtime" فایل تکیه خواهد کرد، و دسته‌بندی می‌تواند از روی دایرکتوری‌ای که فایل در آن قرار دارد تعیین شود. برای مثال، فایلی که در python/foobar/myfoobar.rst قرار دارد، دسته‌بندی foobar را خواهد داشت. اگر می‌خواهید فایل‌های خود را به روش‌های دیگری سازمان‌دهی کنید که در آن نام زیرپوشه نام مناسبی برای دسته‌بندی نیست، می‌توانید مقدار USE_FOLDER_AS_CATEGORY را روی False قرار دهید. هنگام تجزیه تاریخ‌های ارائه‌شده در فراداده صفحه، Pelican از زیرمجموعه پیشنهادی W3C برای ISO 8601 https://www.w3.org/TR/NOTE-datetime پشتیبانی می‌کند.

بنابراین عنوان تنها فراداده الزامی است. اگر این موضوع شما را نگران می‌کند، نگران نباشید. به جای مشخص کردن دستی عنوان در فراداده در هر بار، می‌توانید از نام فایل منبع محتوا به عنوان عنوان استفاده کنید. برای مثال، به یک فایل منبع Markdown با نام Publishing via Pelican.md به طور خودکار عنوان Publishing via Pelican اختصاص داده می‌شود. اگر این رفتار را ترجیح می‌دهید، خط زیر را به فایل تنظیمات خود اضافه کنید:

FILENAME_METADATA = '(?P<title>.*)'

نکته:

مقدار modified باید آخرین زمانی باشد که مقاله را به‌روزرسانی کرده‌اید، و اگر مشخص نشود پیش‌فرض آن date خواهد بود. علاوه بر اینکه می‌توانید modified را در قالب‌ها نمایش دهید، ورودی‌های فید در فیدخوان‌ها زمانی که پس از ویرایش مقاله، modified را به تاریخ فعلی تنظیم کنید، به طور خودکار به‌روزرسانی خواهند شد.

مقدار authors فهرستی از نویسندگان مقاله است که با کاما از هم جدا شده‌اند. اگر تنها یک نویسنده وجود دارد می‌توانید از فیلد author استفاده کنید.

اگر فراداده summary را برای یک پست خاص به طور صریح مشخص نکنید، می‌توان از تنظیم SUMMARY_MAX_LENGTH برای تعیین تعداد کلماتی از ابتدای مقاله که به عنوان خلاصه استفاده می‌شوند، استفاده کرد. همچنین می‌توانید با استفاده از تنظیم SUMMARY_MAX_PARAGRAPHS از N پاراگراف اول مقاله به عنوان خلاصه آن استفاده کنید. اگر از هر دو تنظیم استفاده شود، تعداد پاراگراف‌های مشخص‌شده استفاده خواهد شد اما ممکن است برای رعایت حداکثر طول مشخص‌شده کوتاه شوند.

همچنین می‌توانید از طریق یک عبارت باقاعده که در تنظیم FILENAME_METADATA تعیین می‌شود، هر فراداده‌ای را از نام فایل استخراج کنید. همه گروه‌های نام‌گذاری‌شده‌ای که تطبیق داده شوند در شیء فراداده قرار خواهند گرفت. مقدار پیش‌فرض برای تنظیم FILENAME_METADATA تنها تاریخ را از نام فایل استخراج می‌کند. برای مثال، اگر می‌خواهید هم تاریخ و هم slug را استخراج کنید، می‌توانید مقداری شبیه به این تنظیم کنید: '(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

لطفاً توجه داشته باشید که فراداده موجود درون فایل‌های شما بر فراداده استخراج‌شده از نام فایل اولویت دارد..SS برگه‌ها (Pages)

اگر پوشه‌ای به نام pages در پوشهٔ content ایجاد کنید، تمام فایل‌های درون آن برای تولید برگه‌های ایستا، مانند برگه‌های About یا Contact استفاده خواهند شد. (نمونه ساختار سیستم‌فایل را در زیر ببینید.)

می‌توانید از تنظیم DISPLAY_PAGES_ON_MENU برای کنترل اینکه آیا همهٔ این برگه‌ها در منوی ناوبری اصلی نمایش داده شوند یا خیر استفاده کنید. (پیش‌فرض True است.)

اگر می‌خواهید برگه‌ای را از پیوند داده شدن یا فهرست شدن در منو مستثنی کنید، ویژگی status: hidden را به فراداده‌های (metadata) آن بیفزایید. این ویژگی برای مواردی مانند ساخت برگه‌های خطا که با پوستهٔ تولیدشدهٔ وب‌گاه شما هم‌خوانی دارند، مفید است.

محتوای ایستا (Static content)

فایل‌های ایستا، فایل‌هایی غیر از مقاله‌ها و برگه‌ها هستند که بدون پردازش و به همان شکل به‌صورت مستقیم در پوشهٔ خروجی کپی می‌شوند. می‌توانید فایل‌های ایستای کپی‌شده را با تنظیم STATIC_PATHS در فایل pelicanconf.py پروژه کنترل کنید. پیکربندی پیش‌فرض Pelican شامل دایرکتوری images برای این منظور است، اما سایر موارد باید به‌صورت دستی افزوده شوند. علاوه بر این، فایل‌های ایستایی که صراحتاً پیوند داده شده‌اند نیز گنجانده می‌شوند (زیر را ببینید).

نکته:

محتوای مختلط در یک دایرکتوری (Mixed content in the same directory)

از نسخهٔ Pelican 3.5 به بعد، فایل‌های ایستا می‌توانند بدون افشای سورس برگه‌ها در وب‌گاه تولیدشده، با فایل‌های سورس برگه‌ها در یک دایرکتوری مبدأ به اشتراک گذاشته شوند. هر دایرکتوری از این دست باید به هر دوی STATIC_PATHS و PAGE_PATHS (یا STATIC_PATHS و ARTICLE_PATHS) افزوده شود. Pelican فایل‌های سورس برگه را به‌طور عادی شناسایی و پردازش می‌کند و باقی فایل‌ها را به‌گونه‌ای کپی می‌کند که گویی در دایرکتوری مجزایی مخصوص فایل‌های ایستا قرار دارند.

نکته: قرار دادن فایل‌های ایستا و فایل‌های سورس محتوا در کنار هم در یک دایرکتوری مبدأ، تضمین نمی‌کند که آن‌ها در وب‌گاه تولیدشده نیز در همان مکان قرار گیرند. ساده‌ترین راه برای انجام این کار، استفاده از ساختار پیوند {attach} است (در زیر توضیح داده شده است). همچنین، می‌توان تنظیمات STATIC_SAVE_AS، PAGE_SAVE_AS و ARTICLE_SAVE_AS (و تنظیمات متناظر *_URL) را برای قرار دادن فایل‌هایی از انواع مختلف در کنار هم پیکربندی کرد، درست همانند نسخه‌های پیشین Pelican.

پیوند به محتوای داخلی (Linking to internal content)

از نسخهٔ Pelican 3.1 به بعد، اکنون امکان تعیین پیوندهای درون‌وب‌گاهی به فایل‌ها در سلسله‌مراتب محتوای مبدأ به‌جای فایل‌ها در سلسله‌مراتب تولیدشده وجود دارد. این کار پیوند دادن از پست فعلی به محتواهای دیگری را که ممکن است در کنار آن پست قرار داشته باشند آسان‌تر می‌کند (به‌جای اینکه نیاز باشد مکان قرارگیری محتوای دیگر پس از تولید وب‌گاه مشخص شود).

برای پیوند به محتوای داخلی (فایل‌های موجود در دایرکتوری content)، از ساختار زیر برای مقصد پیوند استفاده کنید: {filename}path/to/file. نکته: اسلش رو به جلو، /، در دستورالعمل {filename} در تمام سیستم‌عامل‌ها، از جمله Windows، جداکنندهٔ مسیر اجباری است.

برای نمونه، یک پروژهٔ Pelican ممکن است ساختاری شبیه به این داشته باشد:

website/
├── content
│   ├── category/
│   │   └── article1.rst
│   ├── article2.md
│   └── pages
│       └── about.md
└── pelican.conf.py

در این مثال، article1.rst می‌تواند به این شکل باشد:

The first article
#################
:date: 2012-12-01 10:02
See below intra-site link examples in reStructuredText format.
`a link relative to the current file <{filename}../article2.md>`_
`a link relative to the content root <{filename}/article2.md>`_

و article2.md:

Title: The second article
Date: 2012-12-01 10:02
See below intra-site link examples in Markdown format.
[a link relative to the current file]({filename}category/article1.rst)
[a link relative to the content root]({filename}/category/article1.rst)

پیوند به فایل‌های ایستا (Linking to static files)

می‌توانید با استفاده از {static}path/to/file به محتوای ایستا پیوند دهید. فایل‌هایی که با این ساختار پیوند داده می‌شوند، به‌طور خودکار در دایرکتوری خروجی کپی خواهند شد، حتی اگر دایرکتوری‌های مبدأ حاوی آن‌ها در تنظیم STATIC_PATHS فایل pelicanconf.py پروژه گنجانده نشده باشند.

برای نمونه، دایرکتوری محتوای یک پروژه ممکن است چنین ساختاری داشته باشد:

content
├── images
│   └── han.jpg
├── pdfs
│   └── menu.pdf
└── pages
    └── test.md

فایل test.md شامل این موارد خواهد بود:

![Alt Text]({static}/images/han.jpg)
[Our Menu]({static}/pdfs/menu.pdf)

سپس فرایند تولید وب‌گاه، فایل han.jpg را در output/images/han.jpg و فایل menu.pdf را در output/pdfs/menu.pdf کپی کرده و پیوندهای مناسب را در test.md درج می‌کند.

اگر از {static} برای پیوند به یک مقاله یا برگه استفاده کنید، این پیوند به پیوندی به کد سورس آن تبدیل خواهد شد..SS پیوست کردن فایل‌های ایستا

از Pelican 3.5 به بعد، فایل‌های ایستا را می‌توان با استفاده از این نحو برای مقصد پیوند به یک صفحه یا مقاله "پیوست" کرد: {attach}path/to/file. این نحو مانند نحو {static} عمل می‌کند، اما علاوه بر آن، فایل ایستا را به دایرکتوری خروجیِ سند پیونددهنده نیز منتقل می‌کند. اگر فایل ایستا در یک زیردایرکتوری زیر منبع سند پیونددهنده قرار داشته باشد، آن رابطه در خروجی حفظ خواهد شد. در غیر این صورت، در کنار سند پیونددهنده (در همان سطح) قرار خواهد گرفت.

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

برای نمونه، دایرکتوری محتوای (content) یک پروژه ممکن است چنین ساختاری داشته باشد:

content
├── blog
│   ├── icons
│   │   └── icon.png
│   ├── photo.jpg
│   └── testpost.md
└── downloads
    └── archive.zip

فایل pelicanconf.py شامل این موارد خواهد بود:

PATH = 'content'
ARTICLE_PATHS = ['blog']
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
ARTICLE_URL = '{date:%Y}/{slug}.html'

فایل testpost.md شامل این موارد خواهد بود:

Title: Test Post
Category: test
Date: 2014-10-31
![Icon]({attach}icons/icon.png)
![Photo]({attach}photo.jpg)
[Downloadable File]({attach}/downloads/archive.zip)

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

output
└── 2014
    ├── archive.zip
    ├── icons
    │   └── icon.png
    ├── photo.jpg
    └── test-post.html

توجه کنید که تمام فایل‌های پیوند داده شده با استفاده از {attach} در دایرکتوری خروجی مقاله یا زیردایرکتوری‌های آن قرار گرفته‌اند.

اگر به یک فایل ایستا چندین بار پیوند داده شود، ویژگی جابه‌جاییِ {attach} تنها برای اولین پیوندی که پردازش می‌شود عمل خواهد کرد. پس از اولین پیوند، Pelican با {attach} همانند {static} رفتار خواهد کرد. این کار از شکسته شدن پیوندهایی که قبلاً پردازش شده‌اند جلوگیری می‌کند.

هنگام پیوند دادن به یک فایل از چندین سند، احتیاط کنید: از آن‌جا که نخستین پیوند به یک فایل مکان آن را نهایی می‌کند و Pelican ترتیبی برای پردازش اسناد مشخص نمی‌کند، استفاده از {attach} برای فایلی که در چندین سند پیوند داده شده است می‌تواند موجب تغییر مکان آن از یک ساخت سایت به ساخت بعدی شود. (اینکه آیا این اتفاق در عمل رخ می‌دهد یا خیر، به سیستم‌عامل، سیستم فایل، نسخه Pelican و اسنادی که به پروژه اضافه، ویرایش یا حذف می‌شوند بستگی دارد.) در نتیجه، ممکن است پیوندهای هر سایت بیرونی که به مکان پیشین فایل پیوند دارد شکسته شود. بنابراین توصیه می‌شود تنها در صورتی از {attach} استفاده کنید که آن را در تمامی پیوندها به آن فایل به کار ببرید، و تنها در صورتی که اسناد پیونددهنده در یک دایرکتوری مشترک قرار داشته باشند. تحت این شرایط، مکان خروجی فایل در ساخت‌های بعدی تغییر نخواهد کرد. در مواردی که رعایت این احتیاط‌ها ممکن نیست، استفاده از پیوندهای {static} را به جای {attach} مد نظر قرار دهید و اجازه دهید مکان فایل بر اساس تنظیمات STATIC_SAVE_AS و STATIC_URL پروژه تعیین شود. (بازنویسی‌های جداگانه برای هر فایل با save_as و url را همچنان می‌توان در EXTRA_PATH_METADATA تعیین کرد.)

نکته:

پیوند دادن به نویسندگان، دسته‌ها، نمایه و برچسب‌ها

می‌توانید با استفاده از نحو {author}name، {category}foobar، {index} و {tag}tagname به نویسندگان، دسته‌ها، نمایه و برچسب‌ها پیوند دهید.

نحو منسوخ پیوند درونی

جهت حفظ سازگاری با نسخه‌های پیشین، Pelican همچنان علاوه بر آکولاد ({}) از خطوط عمودی (||) برای پیوندهای درونی پشتیبانی می‌کند. برای نمونه: |filename|an_article.rst، |tag|tagname، |category|foobar. این نحو از || به {} تغییر یافت تا از تداخل با افزونه‌های Markdown یا رهنمودهای reST جلوگیری شود. به طور مشابه، Pelican هنوز هم از پیوند دادن به محتوای ایستا با {filename} پشتیبانی می‌کند. این نحو به {static} تغییر پیدا کرد تا پیوند دادن هم به مقاله‌ها و صفحه‌های تولیدشده و هم به منابع ایستای آن‌ها امکان‌پذیر باشد.

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

هر دو نحو Markdown و reStructuredText سازوکارهایی را برای این کار ارائه می‌دهند.

در ادامه چند مثال برای reStructuredText با استفاده از راهنمای include http://docutils.sourceforge.net/docs/ref/rst/directives.html#include آمده است:

.. include:: file.rst

گنجاندن بخشی از یک فایل که با دو شناسه مشخص شده است، به همراه رنگ‌آمیزی نحو برای C++ (برش زدن بر اساس شماره خطوط نیز ممکن است):

.. include:: main.cpp
    :code: c++
    :start-after: // begin
    :end-before: // end

گنجاندن یک فایل خام HTML (یا یک SVG درون‌خطی) و قرار دادن مستقیم آن در خروجی بدون هیچ‌گونه پردازشی:

.. raw:: html
    :file: table.html

برای Markdown باید به یک افزونه متکی بود. برای مثال با استفاده از پلاگین mdx_include https://github.com/neurobin/mdx_include:

```html
{! template.html !}
```

وارد کردن یک سایت موجود

امکان وارد کردن سایت شما از چندین سرویس وبلاگ‌نویسی دیگر (مانند WordPress، Tumblr و...) با استفاده از یک اسکریپت ساده وجود دارد. بخش وارد کردن یک سایت موجود را ببینید <#import>.

ترجمه‌ها

ترجمه مقاله‌ها امکان‌پذیر است. برای این کار باید مشخصه فراداده lang را به مقاله‌ها/صفحات خود اضافه کرده و تنظیم DEFAULT_LANG (که به‌طور پیش‌فرض انگلیسی [en] است) را مشخص کنید. با اعمال این تنظیمات، تنها مقاله‌های دارای زبان پیش‌فرض فهرست خواهند شد و هر مقاله با فهرستی از ترجمه‌های دردسترس برای آن مقاله همراه خواهد بود.

نکته:

به‌طور پیش‌فرض، Pelican از "slug" در نشانی مقاله استفاده می‌کند تا تشخیص دهد آیا دو یا چند مقاله ترجمه یکدیگر هستند یا خیر. (این رفتار با تنظیم ARTICLE_TRANSLATION_ID قابل تغییر است.) مقدار slug می‌تواند به‌صورت دستی در فراداده فایل تنظیم شود؛ در صورتی که به‌طور صریح تنظیم نشود، Pelican به‌طور خودکار slug را از عنوان مقاله تولید خواهد کرد.

در اینجا مثالی از دو مقاله آورده شده است، یکی به زبان انگلیسی و دیگری به فرانسوی.

مقاله انگلیسی:

Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
That's true, foobar is still alive!

و نسخه فرانسوی:

Foobar n'est pas mort !
#######################
:slug: foobar-is-not-dead
:lang: fr
Oui oui, foobar est toujours vivant !

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

اگر نمی‌خواهید نسخه اصلی یک مقاله خاص با تنظیم DEFAULT_LANG شناسایی شود، از فراداده translation برای مشخص کردن اینکه کدام پست‌ها ترجمه هستند استفاده کنید:

Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
:translation: true
That's true, foobar is still alive!

.. code-block:: python
   print("Pelican is a static site generator.")

There are two ways to specify the identifier:
    :::python
    print("The triple-colon syntax will *not* show line numbers.")
To display line numbers, use a path-less shebang instead of colons:
    #!python
    print("The path-less shebang syntax *will* show line numbers.")

.. code-block:: identifier
    :classprefix: pgcss
    :linenos: table
    :linenostart: 153
   <indented code block goes here>

PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}

DEFAULT_METADATA = {
    'status': 'draft',
}

پست‌های پنهان (Hidden Posts)

همانند برگه‌ها، پست‌ها را نیز می‌توان با مشخصهٔ Status: hidden به صورت hidden نشانه‌گذاری کرد. پست‌های پنهان طبق انتظار در مسیر ARTICLE_SAVE_AS خروجی داده می‌شوند، اما به صورت پیش‌فرض در فهرست‌های برچسب، دسته‌بندی و نویسنده، و همچنین در فید اصلی مقالات قرار نخواهند گرفت. این عمل اثری معادل ایجاد یک پست «فهرست‌نشده» ("unlisted") دارد.

صرف‌نظر از پست‌ها (Skip Posts)

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

انتشار سایت (Publish your site)

تولید سایت (Site generation)

پس از نصب Pelican و در دست داشتن محتوا (مثلاً در قالب Markdown یا reST)، می‌توانید با استفاده از دستور pelican و مشخص کردن مسیر محتوا و (به طور اختیاری) مسیر فایل تنظیمات <>، محتوای خود را به HTML تبدیل کنید:

pelican /path/to/your/content/ [-s path/to/your/settings.py]

دستور فوق سایت شما را تولید کرده و آن را در پوشهٔ output/ ذخیره می‌کند و با استفاده از پوستهٔ پیش‌فرض، سایتی ساده می‌سازد. پوستهٔ پیش‌فرض شامل HTML بسیار ساده و فاقد استایل ظاهری است تا افراد بتوانند از آن به عنوان پایه‌ای برای ساخت پوسته‌های اختصاصی خود استفاده کنند.

شما همچنین می‌توانید به Pelican دستور دهید تا تغییرات فایل‌ها را پایش کند، به جای اینکه هر بار برای مشاهدهٔ تغییرات دستور را دستی اجرا کنید. برای فعال‌سازی این مورد، دستور pelican را با گزینهٔ -r یا --autoreload اجرا کنید. در محیط‌های غیر از ویندوز، این گزینه را می‌توان با گزینهٔ -l یا --listen ترکیب کرد تا هم‌زمان خروجی به صورت خودکار بازتولید شده و در آدرس http://localhost:8000 ارائه شود:

pelican --autoreload --listen

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

pelican --help

مشاهده فایل‌های تولیدشده (Viewing the generated files)

فایل‌های تولیدشده توسط Pelican از نوع ایستا (static) هستند، بنابراین برای مشاهدهٔ آن‌ها نیاز به ابزار خاصی ندارید. می‌توانید از مرورگر خود برای باز کردن مستقیم فایل‌های HTML تولیدشده استفاده کنید:

firefox output/index.html

از آنجا که روش فوق ممکن است در یافتن مسیر فایل‌های CSS و سایر دارایی‌های پیوندیافته با مشکل مواجه شود، اجرای وب‌سرور داخلی سادهٔ Pelican معمولاً تجربهٔ پیش‌نمایش مطمئن‌تری ارائه می‌دهد:

pelican --listen

پس از راه‌اندازی وب‌سرور، می‌توانید سایت خود را در نشانی زیر پیش‌نمایش کنید: http://localhost:8000

استقرار (Deployment)

پس از تولید سایت، پیش‌نمایش آن در محیط توسعهٔ محلی و آماده شدن برای استقرار در محیط عملیاتی (production)، ممکن است ابتدا بخواهید سایت خود را با تنظیمات خاص محیط عملیاتی (مانند سرویس‌های تحلیل آماری، فیدها و غیره) که تعریف کرده‌اید، مجدداً بازتولید کنید:

pelican content -s publishconf.py

برای پایه‌گذاری پیکربندی انتشار خود بر روی pelicanconf.py، می‌توانید تنظیمات pelicanconf را با افزودن خط زیر به فایل publishconf.py وارد (import) کنید:

from pelicanconf import *

اگر فایل publishconf.py را با استفاده از دستور pelican-quickstart ایجاد کرده باشید، این خط به صورت پیش‌فرض در آن گنجانده شده است.

مراحل استقرار سایت شما به بستر میزبانی آن بستگی دارد. اگر دسترسی SSH به سروری دارید که Nginx یا Apache را اجرا می‌کند، می‌توانید از ابزار rsync برای انتقال فایل‌های سایت خود استفاده نمایید:

rsync -avc --delete output/ host.example.com:/var/www/your-site/

گزینه‌های استقرار متعدد دیگری نیز در دسترس هستند که برخی از آن‌ها را می‌توان هنگام راه‌اندازی اولیهٔ سایت از طریق دستور pelican-quickstart پیکربندی کرد. برای جزئیات مربوط به انتشار از طریق GitHub Pages، صفحهٔ Tips <> را ببینید..SS "خودکارسازی (Automation)"

در حالی که دستور pelican روش استاندارد و مرجع برای تولید وب‌سایت شما است، ابزارهای خودکارسازی می‌توانند برای ساده‌سازی و بهبود فرآیند تولید و انتشار به کار روند. یکی از پرسش‌هایی که در طول فرآیند pelican-quickstart پرسیده می‌شود، مربوط به این است که آیا مایلید تولید و انتشار وب‌سایت را خودکارسازی کنید یا خیر. اگر به آن پرسش پاسخ "yes" داده باشید، یک فایل tasks.py و یک Makefile در ریشهٔ پروژهٔ شما تولید خواهد شد. این فایل‌ها که با اطلاعات مشخصی برگرفته از سایر پاسخ‌های ارائه شده در طول فرآیند pelican-quickstart از پیش پر شده‌اند، به عنوان یک نقطهٔ شروع در نظر گرفته شده‌اند و باید متناسب با نیازها و الگوهای مصرف خاص شما سفارشی‌سازی شوند. اگر احساس می‌کنید یک یا هر دوی این ابزارهای خودکارسازی کاربرد محدودی برای شما دارند، این فایل‌ها در هر زمان قابل حذف هستند و تأثیری بر استفاده از دستور اصلی و استاندارد pelican نخواهند گذاشت.

در ادامه ابزارهای خودکارسازی آورده شده‌اند که دستور pelican را پوشش می‌دهند ("wrap" می‌کنند) و می‌توانند فرآیند تولید، پیش‌نمایش، و بارگذاری سایت شما را ساده‌تر نمایند.

Invoke

مزیت Invoke https://www.pyinvoke.org این است که به زبان Python نوشته شده و بنابراین می‌تواند در طیف گسترده‌ای از محیط‌ها استفاده شود. نکتهٔ منفی آن این است که باید به صورت جداگانه نصب شود. برای نصب Invoke از دستور زیر استفاده کنید؛ در صورتی که محیط شما نیاز دارد، sudo را به ابتدای آن بیفزایید:

python -m pip install invoke

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

invoke build

اگر ترجیح می‌دهید Pelican هر بار با تشخیص یک تغییر، سایت شما را به‌طور خودکار بازتولید کند (که هنگام آزمایش و بررسی محلی بسیار سودمند است)، در عوض از دستور زیر استفاده کنید:

invoke regenerate

برای ارائهٔ (serve) سایت تولیدشده به طوری که بتوان آن را در مرورگر در نشانی http://localhost:8000 پیش‌نمایش کرد:

invoke serve

برای ارائهٔ سایت تولیدشده به همراه بارگذاری مجدد خودکار در مرورگر با هر بار تشخیص تغییر، ابتدا دستور python -m pip install livereload را اجرا کرده، سپس دستور زیر را به کار ببرید:

invoke livereload

اگر در حین فرآیند pelican-quickstart هنگام پرسش دربارهٔ تمایل به بارگذاری سایت از طریق SSH پاسخ "yes" داده‌اید، می‌توانید از دستور زیر برای انتشار سایت خود از طریق rsync بر بستر SSH استفاده نمایید:

invoke publish

این‌ها تنها چند مورد از دستورهای موجود به طور پیش‌فرض هستند؛ بنابراین در بررسی tasks.py و مشاهدهٔ سایر دستورهای موجود تردید نکنید. مهم‌تر از آن، بدون درنگ tasks.py را بر اساس نیازها و ترجیحات خاص خود سفارشی‌سازی کنید.

Make

یک Makefile نیز زمانی که در حین فرآیند pelican-quickstart به پرسش مربوطه پاسخ "yes" بدهید، به طور خودکار برای شما ایجاد می‌شود. مزیت این روش در این است که دستور make به طور توکار در اغلب سیستم‌های POSIX وجود دارد و از این رو برای استفاده از آن نیازی به نصب مورد دیگری نیست. نکتهٔ منفی این است که سیستم‌های غیر POSIX (مانند Windows) شامل make نیستند، و نصب آن بر روی این سیستم‌ها می‌تواند کار دشوار و غیربدیهی باشد.

اگر می‌خواهید از make برای تولید سایت با استفاده از تنظیمات موجود در pelicanconf.py استفاده کنید، دستور زیر را اجرا کنید:

make html

جهت تولید سایت برای محیط عملیاتی (production)، با بهره‌گیری از تنظیمات publishconf.py، دستور زیر را اجرا کنید:

make publish

اگر ترجیح می‌دهید Pelican با هر بار شناسایی تغییرات سایت شما را به‌طور خودکار مجدداً تولید کند (که هنگام آزمایش محلی بسیار مفید است)، به جای آن از دستور زیر استفاده کنید:

make regenerate

برای ارائهٔ سایت تولیدشده به گونه‌ای که بتوان آن را در مرورگر در آدرس http://localhost:8000 پیش‌نمایش کرد:

make serve

در حالت عادی لازم است دستورهای make regenerate و make serve را در دو نشست پایانهٔ جداگانه اجرا کنید، اما می‌توانید هر دو را به صورت هم‌زمان با دستور زیر اجرا نمایید:

make devserver

دستور فوق به‌طور هم‌زمان Pelican را در حالت بازتولید اجرا کرده و خروجی را نیز در نشانی http://localhost:8000 ارائه می‌دهد.

هنگامی که آمادهٔ انتشار سایت خود شدید، می‌توانید آن را از طریق روش(هایی) که در طول پرسشنامهٔ pelican-quickstart برگزیده‌اید بارگذاری نمایید. برای این مثال، از rsync بر بستر ssh استفاده می‌کنیم:

make rsync_upload

کار تمام است! اکنون وب‌سایت شما باید زنده و برخط باشد.

(اسکریپت‌های پیش‌فرض Makefile و devserver.sh از فایل‌های اجرایی python و pelican برای انجام وظایف خود استفاده می‌کنند. در صورت تمایل به استفاده از فایل‌های اجرایی دیگر، مانند python3، می‌توانید به ترتیب متغیرهای محیطی PY و PELICAN را تنظیم کنید تا نام فایل‌های اجرایی پیش‌فرض را بازنویسی کنند.).SS تنظیمات (Settings)

Pelican به لطف یک فایل تنظیمات که می‌توانید به خط فرمان بدهید، قابل پیکربندی است:

pelican content -s path/to/your/pelicanconf.py

اگر از دستور pelican-quickstart استفاده کرده باشید، فایل تنظیمات اصلی شما به‌طور پیش‌فرض pelicanconf.py نام خواهد داشت.

همچنین می‌توانید تنظیمات را از طریق پرچم‌های گزینهٔ -e / --extra-settings مشخص کنید. این گزینه هم تنظیمات پیش‌فرض و هم هر تنظیم تعریف‌شده درون فایل تنظیمات را بازنویسی خواهد کرد. توجه داشته باشید که مقادیر باید از نشانه‌گذاری JSON پیروی کنند:

pelican content -e SITENAME='"A site"' READERS='{"html": null}' CACHE_CONTENT=true

متغیرهای محیطی نیز می‌توانند در اینجا استفاده شوند، اما باید به‌درستی گریزدهی (escape) شوند:

pelican content -e API_KEY=''\"$API_KEY\"''

نکته:

تنظیمات در قالب یک ماژول پایتون (یک فایل) پیکربندی می‌شوند. یک فایل تنظیمات نمونه در https://raw.githubusercontent.com/getpelican/pelican/main/samples/pelican.conf.py برای ارجاع در دسترس است.

برای مشاهدهٔ فهرستی از تنظیمات فعلی در محیط خود، شامل مقادیر پیش‌فرض و هر مقدار سفارشی‌شده، دستور زیر را اجرا کنید (برای دیدن مقادیر فقط مربوط به تنظیماتی خاص، یک یا چند نام تنظیم را به عنوان آرگومان اضافه کنید):

pelican --print-settings

تمام شناسه‌های تنظیمات باید با حروف بزرگ نوشته شوند، در غیر این صورت پردازش نخواهند شد. مقادیر تنظیمی که عدد (5، 20 و غیره)، مقادیر بولی (True، False، None و غیره)، دیکشنری یا تاپل هستند نباید در علامت نقل‌قول قرار گیرند. تمام مقادیر دیگر (یعنی رشته‌ها) باید درون علامت نقل‌قول قرار داده شوند.

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

در ادامه فهرستی از تنظیمات Pelican آمده است:

تنظیمات پایه (Basic settings)

OUTPUT_RETENTION = [".hg", ".git", ".bzr"]

import sys
sys.path.append('to/your/path')
from custom_filter import urlencode_filter
JINJA_FILTERS = {'urlencode': urlencode_filter}

LOG_FILTER = [(logging.WARN, 'TAG_SAVE_AS is set to False')]

READERS = {'html': None}

READERS = {'foo': FooReader}

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
}

تنظیمات URL (URL settings)

نخستین نکته این است که در حال حاضر دو روش پشتیبانی‌شده برای ساخت URL وجود دارد: relative (نسبی) و absolute (مطلق). نشانی‌های نسبی هنگام آزمایش محلی مفید هستند و نشانی‌های مطلق قابل‌اطمینان‌تر بوده و هنگام انتشار بیشترین کاربرد را دارند. یکی از روش‌ها برای پشتیبانی از هر دو، داشتن یک فایل پیکربندی Pelican برای توسعه محلی و فایلی دیگر برای انتشار است. برای مشاهده نمونه‌ای از این راه‌اندازی، از اسکریپت pelican-quickstart مطابق با توضیحات بخش Installation <> استفاده کنید که دو فایل پیکربندی جداگانه به‌ترتیب برای توسعه محلی و انتشار تولید خواهد کرد.

می‌توانید نشانی‌های URL و مکان‌هایی که فایل‌ها ذخیره می‌شوند را سفارشی کنید. متغیرهای *_URL و *_SAVE_AS از رشته‌های قالب‌بندی (format strings) پایتون استفاده می‌کنند. این متغیرها به شما امکان می‌دهند تا مقاله‌های خود را در مکانی مانند {slug}/index.html قرار دهید و برای داشتن نشانی‌های تمیز، پیوند آن‌ها را به‌صورت {slug} بنویسید (مثال زیر را ببینید). این تنظیمات انعطاف‌پذیری لازم را برای قرار دادن مقاله‌ها و صفحه‌ها در هر جایی که می‌خواهید فراهم می‌کنند.

نکته:

اگر به این سطح از انعطاف نیازی ندارید و ترجیح می‌دهید مسیرهای خروجی تولیدشده دقیقاً ساختار درختی مسیرهای فایل‌سیستم محتوای مبدأ شما را بازتاب دهند، تنظیمات زیر را امتحان کنید:

PATH_METADATA = '(?P<path_no_ext>.*)\..*'
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = '{path_no_ext}.html'

در غیر این صورت، می‌توانید از ویژگی‌های فراداده‌ای گوناگون فایل درون تنظیمات مربوط به URL استفاده کنید:

نمونه کاربرد:

ARTICLE_URL = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'
ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'
PAGE_URL = 'pages/{slug}/'
PAGE_SAVE_AS = 'pages/{slug}/index.html'

این کار مقاله‌های شما را در مکانی شبیه به /posts/2011/Aug/07/sample-post/index.html و صفحه‌های شما را در /pages/about/index.html ذخیره می‌کند، و آن‌ها را به‌ترتیب در نشانی‌های /posts/2011/Aug/07/sample-post/ و /pages/about/ در دسترس قرار می‌دهد.

نکته:

نکته:

Pelican می‌تواند به صورت اختیاری بایگانی‌های سالانه، ماهانه و روزانه از پست‌های شما ایجاد کند. این بایگانی‌های ثانویه به طور پیش‌فرض غیرفعال هستند، اما در صورتی که رشته‌های قالب‌بندی (format strings) را برای تنظیمات _SAVE_AS مربوطه‌شان مشخص کنید، به طور خودکار فعال می‌شوند. بایگانی‌های دوره‌ای به صورت شهودی با مدل سلسله‌مراتبی نشانی‌های اینترنتی سازگار هستند و می‌توانند پیمایش در میان پست‌هایی را که در طول زمان نوشته‌اید برای خوانندگان آسان‌تر کنند.

نمونه کاربرد:

YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'
YEAR_ARCHIVE_URL = 'posts/{date:%Y}/'
MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'
MONTH_ARCHIVE_URL = 'posts/{date:%Y}/{date:%b}/'

با این تنظیمات، Pelican یک بایگانی از تمامی پست‌های سال شما در (برای نمونه) posts/2011/index.html و یک بایگانی از تمامی پست‌های ماه در posts/2011/Aug/index.html ایجاد خواهد کرد. این بایگانی‌ها به ترتیب از طریق نشانی‌های posts/2011/ و posts/2011/Aug/ قابل دسترسی خواهند بود.

نکته:

DIRECT_TEMPLATES کمی متفاوت از موارد ذکر شده در بالا عمل می‌کنند. فقط تنظیمات _SAVE_AS موجود هستند، اما این قابلیت برای هر قالب مستقیمی در دسترس است.

نشانی‌های URL برای برگه‌های قالب مستقیم به پوسته وابسته هستند. برخی پوسته‌ها از تنظیم *_URL مربوطه به عنوان رشته استفاده می‌کنند، در حالی که برخی دیگر آن‌ها را به‌صورت سخت‌کدشده قرار می‌دهند: 'archives.html'، 'authors.html'، 'categories.html'، 'tags.html'.

زمان و تاریخ (Time and Date)

DATE_FORMATS = {
    'en': '%a, %d %b %Y',
    'jp': '%Y-%m-%d(%a)',
}

# On Unix/Linux
DATE_FORMATS = {
    'en': ('en_US','%a, %d %b %Y'),
    'jp': ('ja_JP','%Y-%m-%d(%a)'),
}
# On Windows
DATE_FORMATS = {
    'en': ('usa','%a, %d %b %Y'),
    'jp': ('jpn','%Y-%m-%d(%a)'),
}

LOCALE = ('usa', 'jpn',      # On Windows
          'en_US', 'ja_JP'   # On Unix/Linux
)

[1]

پیش‌فرض، تنظیمات محلی (locale) سیستم است..SS صفحه‌های قالب (Template pages)

TEMPLATE_PAGES = {'src/books.html': 'dest/books.html',
                  'src/resume.html': 'dest/resume.html',
                  'src/contact.html': 'dest/contact.html'}

متاداده (Metadata)

FILENAME_METADATA = r'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

نیازی نیست همه متاداده‌ها در خود فایل منبع جاسازی شوند <#internal-metadata>. برای نمونه، پست‌های وبلاگ اغلب طبق الگوی YYYY-MM-DD-SLUG.rst نام‌گذاری می‌شوند یا در دایرکتوری‌های تودرتوی YYYY/MM/DD-SLUG قرار می‌گیرند. برای استخراج متاداده از نام فایل یا مسیر، FILENAME_METADATA یا PATH_METADATA را روی عبارت‌های باقاعده‌ای تنظیم کنید که از شیوه‌نام‌گذاری گروه‌ها در پایتون https://docs.python.org/3/library/re.html#regular-expression-syntax (?P<name>…) استفاده می‌کنند. اگر می‌خواهید متاداده‌های بیشتری پیوست کنید اما مایل نیستید آن‌ها را در مسیر درج نمایید، می‌توانید EXTRA_PATH_METADATA را تنظیم کنید:

EXTRA_PATH_METADATA = {
    'relative/path/to/file-1': {
        'key-1a': 'value-1a',
        'key-1b': 'value-1b',
        },
    'relative/path/to/file-2': {
        'key-2': 'value-2',
        },
    }

این کار می‌تواند روشی مناسب برای تغییر مکان نصب یک فایل خاص باشد:

# Take advantage of the following defaults
# STATIC_SAVE_AS = '{path}'
# STATIC_URL = '{path}'
STATIC_PATHS = [
    'static/robots.txt',
    ]
EXTRA_PATH_METADATA = {
    'static/robots.txt': {'path': 'robots.txt'},
    }

استفاده از الگوهای صفحه‌بندی (Using Pagination Patterns)

به‌طور پیش‌فرض، صفحه‌های بعد از .../foo.html به‌صورت .../foo2.html و غیره ایجاد می‌شوند. از تنظیم PAGINATION_PATTERNS می‌توان برای تغییر این رفتار استفاده کرد. این تنظیم دنباله‌ای از سه‌تایی‌ها را می‌پذیرد که هر سه‌تایی شامل موارد زیر است:

(minimum_page, page_url, page_save_as,)

برای page_url و page_save_as می‌توانید از چندین متغیر استفاده کنید. {url} و {save_as} به‌ترتیب متناظر با مقادیر *_URL و *_SAVE_AS نوع صفحه مربوطه هستند (مانند ARTICLE_SAVE_AS). اگر {save_as} == foo/bar.html باشد، آنگاه {name} == foo/bar و {extension} == .html خواهد بود. مقدار {base_name} برابر با {name} است، با این تفاوت که پسوند پایانی /index را در صورت وجود حذف می‌کند. {number} برابر با شماره صفحه است.

به‌عنوان مثال، اگر می‌خواهید صفحه اول بدون تغییر بماند، اما صفحه‌های بعدی در .../page/2/ و غیره قرار گیرند، می‌توانید PAGINATION_PATTERNS را به‌صورت زیر تنظیم کنید:

PAGINATION_PATTERNS = (
    (1, '{url}', '{save_as}'),
    (2, '{base_name}/page/{number}/', '{base_name}/page/{number}/index.html'),
)

اگر می‌خواهید الگویی بر آخرین صفحه در فهرست اعمال شود، از -1 به‌عنوان مقدار minimum_page استفاده کنید:

(-1, '{base_name}/last/', '{base_name}/last/index.html'),

ترجمه‌ها (Translations)

پروژه Pelican روشی برای ترجمه مقاله‌ها ارائه می‌دهد. برای اطلاعات بیشتر بخش محتوا <> را ببینید.

[3]

{lang} کد زبان است.SS مرتب‌سازی محتوا

تم‌ها

ساخت تم‌های Pelican در یک بخش اختصاصی بررسی شده است (نگاه کنید به تم‌ها <#theming-pelican>). با این حال، در اینجا تنظیمات مربوط به تم‌ها آمده است.

{% extends '!theme/article.html' %}

به‌طور پیش‌فرض، دو تم در دسترس هستند. می‌توانید آن‌ها را با استفاده از تنظیم THEME یا با ارسال گزینه -t به دستور pelican مشخص کنید:

تعدادی تم دیگر در نشانی https://github.com/getpelican/pelican-themes در دسترس است. Pelican به همراه pelican-themes <>، یک اسکریپت کوچک برای مدیریت تم‌ها، ارائه می‌شود.

شما می‌توانید تم خود را چه با شروع از ابتدا و چه با تکثیر و ویرایش یک تم از پیش‌موجود ایجاد کنید. راهنمایی برای نحوه ساخت تم شما در <> موجود است.

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

# مشخص کردن نام یک تم پیش‌ساخته
THEME = "notmyidea"
# مشخص کردن نام تم نصب‌شده از طریق ابزار pelican-themes
THEME = "chunk"
# مشخص کردن تم سفارشی از طریق مسیر نسبی نسبت به فایل تنظیمات
THEME = "themes/mycustomtheme"
# مشخص کردن تم سفارشی از طریق مسیر مطلق
THEME = "/home/myuser/projects/mysite/themes/mycustomtheme"

تم توکار simple را می‌توان با استفاده از تنظیمات زیر سفارشی‌سازی کرد.

تم توکار notmyidea می‌تواند از تنظیمات زیر به‌خوبی بهره ببرد. شما نیز آزاد هستید که از آن‌ها در تم‌های خود استفاده کنید.

ANALYTICS = """
    <script src="/theme/js/primary-analytics.js"></script>
    <script>
        [ … in-line Javascript code for secondary analytics … ]
    </script>
"""

علاوه بر این، می‌توانید با افزودن خط زیر به پیکربندی خود، از نسخه "wide" (عریض) تم notmyidea استفاده کنید:

CSS_FILE = "wide.css"

import logging
LOG_FILTER = [(logging.WARN, 'TAG_SAVE_AS is set to False')]

import logging
LOG_FILTER = [(logging.WARN, 'Empty alt attribute for image %s in %s')]

خواندن تنها محتوای تغییریافته (Reading only modified content)

برای افزایش سرعت فرایند ساخت، Pelican می‌تواند به صورت اختیاری فقط مقاله‌ها و برگه‌های دارای محتوای تغییریافته را بخواند.

هنگامی که Pelican در شرف خواندن یک فایل منبع محتوا است:

اگر CONTENT_CACHING_LAYER روی 'reader' (پیش‌فرض) تنظیم شده باشد، محتوای خام و متادیتا (metadata) بازگردانده‌شده توسط یک reader در حافظه موقت ذخیره می‌شوند. اگر این تنظیم به جای آن روی 'generator' تنظیم شود، شیء محتوای پردازش‌شده در حافظه موقت ذخیره می‌شود. ذخیره شیء محتوای پردازش‌شده در حافظه موقت ممکن است با افزونه‌ها (به دلیل رد شدن برخی سیگنال‌های مربوط به خواندن) و قابلیت WITH_FUTURE_DATES (زیرا وضعیت draft اشیاء محتوای ذخیره‌شده در حافظه موقت به طور خودکار در گذر زمان تغییر نخواهد کرد) تداخل داشته باشد.

بررسی زمان‌های ویرایش سریع‌تر از مقایسه هش‌های فایل است، اما به اندازه آن قابل اعتماد نیست زیرا اطلاعات mtime ممکن است از بین برود، برای مثال هنگام کپی کردن فایل‌های منبع محتوا با استفاده از دستورهای cp یا rsync بدون حالت حفظ mtime (که برای rsync با ارسال پرچم --archive فعال می‌شود).

فایل‌های حافظه موقت از نوع pickle پایتون هستند، بنابراین ممکن است توسط نسخه‌های مختلف Python خوانا نباشند زیرا قالب pickle اغلب تغییر می‌کند. در صورت مواجهه با چنین خطایی، این خطا دریافت شده و فایل حافظه موقت به طور خودکار در قالب جدید بازسازی می‌شود. همچنین فایل‌های حافظه موقت پس از تغییر تنظیم GZIP_CACHE بازسازی خواهند شد.

گزینه خط فرمان --ignore-cache زمانی مفید است که کل حافظه موقت نیاز به بازسازی داشته باشد، مانند اعمال تغییراتی در فایل تنظیمات که بر محتوای ذخیره‌شده در حافظه موقت اثر می‌گذارد، یا صرفاً برای مقاصد اشکال‌زدایی. هنگامی که Pelican در حالت بارگذاری خودکار (autoreload) اجرا می‌شود، در صورتی که AUTORELOAD_IGNORE_CACHE برابر True باشد، ویرایش فایل تنظیمات باعث می‌شود حافظه موقت به طور خودکار نادیده گرفته شود.

توجه داشته باشید که حتی هنگام استفاده از محتوای حافظه موقت، تمام خروجی همیشه نوشته می‌شود، بنابراین زمان‌های ویرایش فایل‌های *.html تولیدشده همیشه تغییر خواهند کرد. از این رو، بارگذاری مبتنی بر rsync می‌تواند از گزینه --checksum بهره‌مند شود..SS تنظیمات نمونه (Example settings)

AUTHOR = "Alexis Métaireau"
SITENAME = "Alexis' log"
SITESUBTITLE = "A personal blog."
SITEURL = "http://blog.notmyidea.org"
TIMEZONE = "Europe/Paris"
# can be useful in development, but set to False when you're ready to publish
RELATIVE_URLS = True
GITHUB_URL = "http://github.com/ametaireau/"
DISQUS_SITENAME = "blog-notmyidea"
REVERSE_CATEGORY_ORDER = True
LOCALE = "C"
DEFAULT_PAGINATION = 4
DEFAULT_DATE = (2012, 3, 2, 14, 1, 1)
FEED_ALL_RSS = "feeds/all.rss.xml"
CATEGORY_FEED_RSS = "feeds/{slug}.rss.xml"
LINKS = (
    ("Biologeek", "http://biologeek.org"),
    ("Filyb", "http://filyb.info/"),
    ("Libert-fr", "http://www.libert-fr.com"),
    ("N1k0", "http://prendreuncafe.com/blog/"),
    ("Tarek Ziadé", "http://ziade.org/blog"),
    ("Zubin Mithra", "http://zubin71.wordpress.com/"),
)
SOCIAL = (
    ("twitter", "http://twitter.com/ametaireau"),
    ("lastfm", "http://lastfm.com/user/akounet"),
    ("github", "http://github.com/ametaireau"),
)
# global metadata to all the contents
DEFAULT_METADATA = {"yeah": "it is"}
# path-specific metadata
EXTRA_PATH_METADATA = {
    "extra/robots.txt": {"path": "robots.txt"},
}
# static paths will be copied without parsing their contents
STATIC_PATHS = [
    "images",
    "extra/robots.txt",
]
# custom page generated with a jinja2 template
TEMPLATE_PAGES = {"pages/jinja2_template.html": "jinja2_template.html"}
# there is no other HTML content
READERS = {"html": None}
# code blocks with line numbers
PYGMENTS_RST_OPTIONS = {"linenos": "table"}
# foobar will not be used, because it's not in caps. All configuration keys
# have to be in caps
foobar = "barbaz"

افزونه‌ها (Plugins)

از نسخهٔ 3.0، Pelican از افزونه‌ها پشتیبانی می‌کند. افزونه‌ها راهکاری برای افزودن قابلیت‌ها به Pelican بدون نیاز به تغییر مستقیم هستهٔ آن هستند.

نحوهٔ استفاده از افزونه‌ها (How to use plugins)

از نسخهٔ 4.5، Pelican به ساختار جدیدی از افزونه‌ها مبتنی بر بسته‌های فضای‌نام (namespace packages) مهاجرت کرد که به‌سادگی از طریق Pip https://pip.pypa.io قابل نصب هستند. افزونه‌هایی که از این ساختار پشتیبانی می‌کنند، ذیل بستهٔ فضای‌نام pelican.plugins نصب می‌شوند و می‌توانند به‌طور خودکار توسط Pelican شناسایی گردند. برای مشاهدهٔ فهرستی از افزونه‌های فضای‌نام نصب‌شده توسط Pip که در محیط شما فعال هستند، دستور زیر را اجرا کنید:

pelican-plugins

اگر تنظیم PLUGINS را روی مقدار پیش‌فرض (None) باقی بگذارید، Pelican به‌طور خودکار افزونه‌های فضای‌نام را شناسایی و ثبت می‌کند. در مقابل، اگر تنظیم PLUGINS را به عنوان فهرستی از افزونه‌ها مشخص کنید، این شناسایی خودکار غیرفعال خواهد شد. در این حالت، تنها افزونه‌هایی که مشخص کرده‌اید ثبت می‌شوند و باید هر افزونهٔ فضای‌نام را نیز صراحتاً در فهرست قید نمایید.

در صورت استفاده از تنظیم PLUGINS، می‌توانید افزونه‌ها را به دو روش مشخص کنید. در روش نخست، افزونه‌ها به عنوان فهرستی از رشته‌ها تعیین می‌شوند. افزونه‌های فضای‌نام را می‌توان با نام کامل (pelican.plugins.myplugin) یا با نام کوتاه آن‌ها (myplugin) مشخص کرد:

PLUGINS = ['package.myplugin',
           'namespace_plugin1',
           'pelican.plugins.namespace_plugin2']

به عنوان روش جایگزین، می‌توانید آن‌ها را در فایل تنظیمات خود وارد (import) کرده و ماژول‌ها را ارسال کنید:

from package import myplugin
from pelican.plugins import namespace_plugin1, namespace_plugin2
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]

نکته:

اگر افزونه‌های شما در مسیری قابل وارد کردن (importable) قرار ندارند، می‌توانید فهرستی از مسیرها را از طریق تنظیم PLUGIN_PATHS مشخص کنید. همان‌طور که در مثال زیر نشان داده شده است، مسیرها در فهرست PLUGIN_PATHS می‌توانند به صورت مطلق یا نسبت به فایل تنظیمات، نسبی باشند:

PLUGIN_PATHS = ["plugins", "/srv/pelican/plugins"]
PLUGINS = ["assets", "liquid_tags", "sitemap"]

نحوه ساخت پلاگین‌ها (How to create plugins)

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

تنها قانونی که باید برای پلاگین‌ها رعایت شود، تعریف یک شیء فراخوانی‌پذیر (callable) به نام register است که در آن سیگنال‌ها را به منطق پلاگین خود متصل می‌کنید. بیایید یک مثال ساده را در نظر بگیریم:

import logging
from pelican import signals
log = logging.getLogger(__name__)
def test(sender):
    log.debug(""%s initialized !!", sender)
def register():
    signals.initialized.connect(test)

نکته:

اگر چندین پلاگین به یک سیگنال متصل شوند، پلاگین‌ها به ترتیبی که ثبت شده‌اند فراخوانی خواهند شد. هنگامی که تنظیمات PLUGINS تعریف شده باشد، ترتیب فراخوانی پلاگین‌ها همان ترتیبی خواهد بود که در تنظیمات PLUGINS فهرست شده‌اند. اگر به پلاگین‌های فضای‌نامِ شناسایی‌شده به صورت خودکار تکیه می‌کنید و تنظیم PLUGINS را تعریف نکرده‌اید، پلاگین‌ها به همان ترتیبی که شناسایی می‌شوند فراخوانی خواهند شد (همان ترتیبی که در خروجی دستور pelican-plugins فهرست شده است). اگر می‌خواهید ترتیب را به صورت صریح مشخص کنید، شناسایی خودکار را با تعریف PLUGINS با ترتیب دلخواه غیرفعال کنید.

ساختار پلاگین‌های فضای‌نام (Namespace plugin structure)

پلاگین‌های فضای‌نام برای اینکه به درستی کار کنند باید از ساختار مشخصی پیروی کنند. آن‌ها باید قابل نصب باشند (یعنی شامل setup.py یا معادل آن باشند) و ساختار پوشه‌ای به صورت زیر داشته باشند:

myplugin
├── pelican
│   └── plugins
│       └── myplugin
│           ├── __init__.py
│           └── ...
├── ...
└── setup.py

بسیار حیاتی است که پوشهٔ pelican یا pelican/plugins حاوی فایل __init__.py نباشد. در واقع، برای جلوگیری از هرگونه مشکل، بهتر است این پوشه‌ها به جز پوشه‌های فهرست‌شده در ساختار بالا خالی باشند و فایل‌های مربوط به پلاگین خود را صرفاً در پوشهٔ pelican/plugins/myplugin نگه دارید.

برای راه‌اندازی آسان ساختار مناسب، یک قالب cookiecutter برای پلاگین‌ها https://github.com/getpelican/cookiecutter-pelican-plugin ارائه شده است. برای دستورالعمل‌های نحوه استفاده از آن، به فایل README آن پروژه مراجعه کنید.

فهرست سیگنال‌ها (List of signals)

در اینجا فهرست سیگنال‌هایی که در حال حاضر پیاده‌سازی شده‌اند آمده است:

هشدار:

نکته:

نحوه ایجاد یک reader جدید

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

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

بدون توضیح بیشتر — در اینجا یک مثال آورده شده است:

from pelican import signals
from pelican.readers import BaseReader
# Create a new reader class, inheriting from the pelican.reader.BaseReader
class NewReader(BaseReader):
    enabled = True  # Yeah, you probably want that :-)
    # The list of file extensions you want this reader to match with.
    # If multiple readers were to use the same extension, the latest will
    # win (so the one you're defining here, most probably).
    file_extensions = ['yeah']
    # You need to have a read method, which takes a filename and returns
    # some content and the associated metadata.
    def read(self, filename):
        metadata = {'title': 'Oh yeah',
                    'category': 'Foo',
                    'date': '2012-12-01'}
        parsed = {}
        for key, value in metadata.items():
            parsed[key] = self.process_metadata(key, value)
        return "Some content", parsed
def add_reader(readers):
    readers.reader_classes['yeah'] = NewReader
# This is how pelican works.
def register():
    signals.readers_init.connect(add_reader)

افزودن یک generator جدید

افزودن یک generator جدید نیز بسیار آسان است. برای اطلاعات بیشتر درباره نحوه ایجاد generator اختصاصی خود، ممکن است بخواهید نگاهی به ساختار درونی Pelican (Pelican internals) <> بیندازید.

def get_generators(pelican_object):
    # define a new generator here if you need to
    return MyGenerator
def register():
    signals.get_generators.connect(get_generators)

افزودن یک writer جدید

افزودن یک writer به شما این امکان را می‌دهد که قالب‌های فایل بیشتری را در دیسک ذخیره کنید، یا نحوه نوشتن قالب‌های موجود بر روی دیسک را تغییر دهید. توجه داشته باشید که در هر زمان تنها یک writer فعال خواهد بود، بنابراین مطمئن شوید که یا از کلاس Writer توکار (built-in) ارث‌بری می‌کنید، یا آن را کاملاً از نو پیاده‌سازی می‌نمایید.

در اینجا یک مثال پایه‌ای از نحوه راه‌اندازی writer اختصاصی شما آورده شده است:

from pelican.writers import Writer
from pelican import signals
class MyWriter(Writer):
    # define new writer functionality
    pass
def add_writer(pelican_object):
    # use pelican_instance to setup stuff if needed
    return MyWriter
def register():
    signals.get_writer.connect(add_writer)

استفاده از افزونه‌ها برای تزریق محتوا

شما می‌توانید با استفاده از افزونه‌ها مقاله‌ها یا صفحه‌ها را به صورت برنامه‌نویسی‌شده تزریق کنید. این ویژگی برای نمونه در صورتی که بخواهید مقاله‌ها را از یک API دریافت کنید، می‌تواند مفید باشد.

در ادامه یک مثال ساده از نحوه ساخت افزونه‌ای آورده شده است که با استفاده از سیگنال article_generator_pretaxonomy یک مقاله سفارشی را تزریق می‌کند:

import datetime
from pelican import signals
from pelican.contents import Article
from pelican.readers import BaseReader
def addArticle(articleGenerator):
    settings = articleGenerator.settings
    # Author, category, and tags are objects, not strings, so they need to
    # be handled using BaseReader's process_metadata() function.
    baseReader = BaseReader(settings)
    content = "I am the body of an injected article!"
    newArticle = Article(content, {
        "title": "Injected Article!",
        "date": datetime.datetime.now(),
        "category": baseReader.process_metadata("category", "fromAPI"),
        "tags": baseReader.process_metadata("tags", "tagA, tagB")
    })
    articleGenerator.articles.insert(0, newArticle)
def register():
    signals.article_generator_pretaxonomy.connect(addArticle)

ساخت پوسته‌ها

برای تولید خروجی HTML،‏ Pelican به دلیل انعطاف‌پذیری و نحو سرراست موتور قالب‌ساز Jinja https://palletsprojects.com/p/jinja از آن استفاده می‌کند. اگر مایلید پوستهٔ خودتان را بسازید، می‌توانید از پوستهٔ "simple" در https://github.com/getpelican/pelican/tree/main/pelican/themes/simple/templates الهام بگیرید.

برای تولید سایت خود با استفاده از پوسته‌ای که ساخته‌اید (یا به صورت دستی بارگیری کرده و سپس تغییر داده‌اید)، می‌توانید آن پوسته را از طریق پرچم -t مشخص کنید:

pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme

اگر ترجیح می‌دهید پوسته را در هر بار اجرای دستور مشخص نکنید، می‌توانید متغیر THEME را در تنظیمات خود تعریف کنید تا به مکان پوستهٔ مورد نظر شما اشاره کند.

ساختار

برای ساخت پوستهٔ خود، باید ساختار زیر را رعایت کنید:

├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         // to display archives
    ├── article.html          // processed for each article
    ├── author.html           // processed for each author
    ├── authors.html          // must list all the authors
    ├── categories.html       // must list all the categories
    ├── category.html         // processed for each category
    ├── index.html            // the index (list all the articles)
    ├── page.html             // processed for each page
    ├── period_archives.html  // to display time-period archives
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.

قالب‌ها و متغیرها

ایدهٔ اصلی استفاده از نحو ساده‌ای است که بتوانید آن را درون صفحات HTML خود بگنجانید. این سند توضیح می‌دهد چه قالب‌هایی باید در یک پوسته وجود داشته باشند، و چه متغیرهایی در زمان تولید به هر قالب ارسال خواهند شد.

تمام قالب‌ها متغیرهای تعریف‌شده در فایل تنظیمات شما را دریافت خواهند کرد، مادامی که با حروف بزرگ (all-caps) باشند. می‌توانید مستقیماً به آن‌ها دسترسی داشته باشید.

متغیرهای عمومی

تمام این تنظیمات در دسترس همهٔ قالب‌ها خواهند بود.

category.html

این قالب برای هر یک از دسته‌های موجود پردازش می‌شود و خروجی بر اساس تنظیم CATEGORY_SAVE_AS (پیش‌فرض: category/{slug}.html) تولید می‌گردد. اگر صفحه‌بندی فعال باشد، صفحات بعدی به‌طور پیش‌فرض در category/{slug}{number}.html قرار خواهند گرفت.

هر فراداده‌ای که در سرآیند فایل منبع مقاله قرار دهید، به عنوان فیلدهایی در شیء article در دسترس خواهد بود. نام فیلد با نام فیلد فراداده یکسان خواهد بود، با این تفاوت که تمام نویسه‌ها به حروف کوچک تبدیل می‌شوند.

برای مثال، می‌توانید فیلدی به نام FacebookImage را همانند نمونهٔ زیر به فراداده‌های مقالهٔ خود اضافه کنید:

Title: I love Python more than music
Date: 2013-11-06 10:06
Tags: personal, python
Category: Tech
Slug: python-je-l-aime-a-mourir
Author: Francis Cabrel
FacebookImage: http://franciscabrel.com/images/pythonlove.png

این فرادادهٔ جدید به صورت article.facebookimage در قالب article.html شما در دسترس خواهد بود. برای مثال، این ویژگی به شما امکان می‌دهد تصویری را برای برچسب‌های open graph فیس‌بوک مشخص کنید که برای هر مقاله تغییر کند:

<meta property="og:image" content="{{ article.facebookimage }}"/>

page.html

این قالب برای هر برگه پردازش خواهد شد و خروجی بر اساس تنظیم PAGE_SAVE_AS (پیش‌فرض: pages/{slug}.html) تولید می‌شود. هنگام رندر، متغیرهای زیر در دسترس هستند.

tag.html

این قالب برای هر برچسب پردازش خواهد شد و خروجی بر اساس تنظیم TAG_SAVE_AS (پیش‌فرض: tag/{slug}.html) تولید می‌شود. اگر صفحه‌بندی فعال باشد، صفحه‌های بعدی به‌طور پیش‌فرض در tag/{slug}{number}.html قرار می‌گیرند.

می‌توانید نمونه‌ای از نحوه استفاده از period را در قالب period_archives.html از پوسته "simple" مشاهده کنید: https://github.com/getpelican/pelican/blob/main/pelican/themes/simple/templates/period_archives.html.

فهرست‌بندی و پیوند به آرشیوهای دوره‌ای (Listing and Linking to Period Archives)

متغیر period_archives می‌تواند برای ایجاد فهرستی از پیوندها به مجموعه‌ای از آرشیوهای دوره‌ای که Pelican تولید می‌کند، استفاده شود. به عنوان یک متغیر عمومی، در هر قالبی قابل استفاده است؛ بنابراین می‌توانید چنین نمایه‌ای را در یک قالب مستقیم سفارشی یا در یک نوار کناری که در صفحات مختلف سایت قابل مشاهده است، پیاده‌سازی کنید.

period_archives یک دیکشنری (dict) است که بسته به فعال بودن هر یک از تنظیمات *_ARCHIVE_SAVE_AS، ممکن است شامل کلیدهای year، month و/یا day باشد. مقدار متناظر، فهرستی از دیکشنری‌ها است که هر دیکشنری به نوبه خود نمایانگر یک دوره زمانی (مرتب‌شده بر اساس تنظیمات NEWEST_FIRST_ARCHIVES) با کلیدها و مقادیر زیر است:

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

<ul>
{% for archive in period_archives.month %}
    <li>
        <a href="{{ SITEURL }}/{{ archive.url }}">
            {{ archive.period | reverse | join(' ') }} ({{ archive.articles|count }})
        </a>
    </li>
{% endfor %}
</ul>

می‌توانید بر اساس سطح جزئیات دوره زمانی مورد نظر، period_archives.month را در عبارت for به دلخواه به period_archives.year یا period_archives.day تغییر دهید..SS اشیاء (Objects)

جزئیات ویژگی‌های اشیایی که در قالب‌ها در دسترس و کاربردی هستند را شرح می‌دهد. همهٔ ویژگی‌ها در اینجا فهرست نشده‌اند؛ این بخش مجموعه‌ای گزینش‌شده از ویژگی‌هایی است که برای استفاده در قالب مفید ارزیابی شده‌اند.

مقاله (Article)

نمایش رشته‌ای یک Article، ویژگی source_path است.

[1]

برای شیء Author، برگرفته از :authors: یا AUTHOR.

صفحه (Page)

نمایش رشته‌ای یک صفحه (Page)، صفت source_path است.

گزینه‌های اختیاری (Optional arguments)

مثال‌ها (Examples)

برای Blogger:

$ pelican-import --blogger -o ~/output ~/posts.xml

برای Dotclear:

$ pelican-import --dotclear -o ~/output ~/backup.txt

برای Medium:

$ pelican-import --medium -o ~/output ~/medium-export/posts/

برون‌بری Medium یک فایل zip است. آن را از حالت فشرده خارج کرده و این ابزار را به زیردایرکتوری "posts" هدایت کنید. برای کسب اطلاعات بیشتر دربارهٔ نحوهٔ برون‌بری، ببینید: https://help.medium.com/hc/en-us/articles/115004745787-Export-your-account-data.

برای Tumblr:

$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_key>

برای WordPress:

$ pelican-import --wpfile -o ~/output ~/posts.xml

برای Medium (یک مثال از استفاده از خوراک RSS):

نکته:

پرسش‌های متداول (FAQ)

در اینجا برخی از پرسش‌های متداول پیرامون Pelican آورده شده است.

بهترین راه برای مطرح کردن یک مشکل، پرسش یا پیشنهاد چیست؟

لطفاً شیوه‌نامه‌های بازخورد ما را در <> مطالعه کنید.

چگونه می‌توانم کمک کنم؟

راه‌های متعددی برای کمک کردن وجود دارد. نخست، می‌توانید هرگونه پیشنهاد یا مشکل مربوط به Pelican را از طریق گفتگوهای Pelican در https://github.com/getpelican/pelican/discussions مطرح کنید. لطفاً ابتدا فهرست گفتگوها و مشکلات (هم باز و هم بسته) موجود را بررسی کنید تا از ارسال موضوعاتی که پیش‌تر پوشش داده شده‌اند، خودداری شود.

اگر قصد مشارکت دارید، لطفاً مخزن Git به نشانی https://github.com/getpelican/pelican را فورک کنید، یک شاخه ویژگی جدید بسازید، تغییرات خود را اعمال کرده و یک pull request ارسال کنید. در اسرع وقت تغییرات شما بازبینی خواهد شد. لطفاً برای جزئیات بیشتر به بخش نحوه مشارکت <> مراجعه کنید.

همچنین می‌توانید با ساخت پوسته‌ها و بهبود مستندات مشارکت داشته باشید.

آیا فایل تنظیمات Pelican اجباری است؟

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

تغییرات در فایل تنظیمات اعمال نمی‌شوند

هنگام آزمایش تنظیمات مختلف (به‌ویژه تنظیمات مربوط به متادیتا)، کش (caching) ممکن است تداخل ایجاد کند و تغییرات قابل مشاهده نباشند. در چنین مواردی، مطمئن شوید که کش از طریق LOAD_CONTENT_CACHE = False غیرفعال شده است یا از سوییچ خط فرمان --ignore-cache استفاده کنید.

در حال ساخت پوسته خود هستم؛ چگونه از Pygments برای برجسته‌سازی نحو استفاده کنم؟

ابزار Pygments تعدادی کلاس به محتوای تولیدشده اضافه می‌کند. این کلاس‌ها توسط پوسته‌ها برای استایل‌دهی به برجسته‌سازی نحو کد از طریق CSS استفاده می‌شوند. به‌طور مشخص، می‌توانید ظاهر برجسته‌سازی نحو خود را از طریق کلاس .highlight pre در فایل CSS پوسته سفارشی‌سازی کنید. برای نمونه، جهت مشاهده چگونگی استفاده از سبک‌های گوناگون برای رندر کردن کد Django، از منوی کشویی انتخاب سبک در بالا سمت راست در سایت پیش‌نمایش پروژه Pygments به نشانی https://pygments.org/demo استفاده کنید.

می‌توانید از دستورهای نمونه زیر برای تولید یک فایل CSS اولیه از یکی از سبک‌های داخلی Pygments (در این مورد، "monokai") استفاده کرده و سپس فایل CSS تولیدشده را در پوسته جدید خود کپی کنید:

pygmentize -S monokai -f html -a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/

فراموش نکنید که فایل pygment.css خود را در فایل CSS اصلی‌تان import کنید.

چگونه پوسته خودم را بسازم؟

لطفاً به بخش پوسته‌ها <#theming-pelican> مراجعه کنید.

آیا می‌توانم بدون فورک کردن کل پوسته، قالب‌های تکی را بازنویسی کنم؟

بله، می‌توانید قالب‌های موجود در پوسته‌ای را که استفاده می‌کنید بازنویسی کرده یا قالب‌های جدیدی را از طریق متغیر THEME_TEMPLATES_OVERRIDES بیفزایید. برای نمونه، جهت بازنویسی قالب برگه (page)، می‌توانید مکان قالب‌های خود را به این صورت تعریف کنید:

THEME_TEMPLATES_OVERRIDES = ["templates"]

سپس می‌توانید یک قالب سفارشی در templates/page.html تعریف کنید. برای جزئیات، بخش پوسته‌ها <#settings-themes> را ببینید.

می‌خواهم از Markdown استفاده کنم، اما با خطا مواجه شدم.

اگر بدون نصب کتابخانه Markdown سعی در تولید محتوای Markdown داشته باشید، ممکن است پیامی با مضمون No valid files found in content دریافت کنید. کتابخانه Markdown یک وابستگی اجباری برای Pelican نیست، بنابراین اگر محتوایی در قالب Markdown دارید، باید کتابخانه Markdown را به‌طور صریح نصب کنید. می‌توانید این کار را با وارد کردن دستور زیر انجام دهید (در صورت نیاز به دسترسی‌ها، sudo را در ابتدای آن قرار دهید):

python -m pip install markdown

آیا می‌توانم از متادیتای دلخواه در قالب‌های خود استفاده کنم؟

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

Modified: 2012-08-08

برای reStructuredText، این متادیتا مسلماً باید با یک دونقطه (colon) آغاز شود:

:Modified: 2012-08-08

سپس می‌توان در قالب‌هایی مانند article.html از طریق زیر به این متادیتا دسترسی پیدا کرد:

{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}

اگر می‌خواهید متادیتا را در قالب‌های خارج از زمینه مقاله (مانند base.html) بگنجانید، عبارت شرطی if باید در عوض به صورت زیر باشد:

{% if article and article.modified %}

USE_FOLDER_AS_CATEGORY = False
PATH_METADATA = "(?P<path_no_ext>.*)\..*"
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = "{path_no_ext}.html"

چگونه قالب‌های سفارشی را به ازای هر برگه اختصاص دهم؟

این کار به سادگی افزودن یک خط متادیتا به هر برگه یا مقاله‌ای است که می‌خواهید قالب مخصوص به خود را داشته باشد. برای مثال، نحوه انجام این کار برای محتوا در قالب reST به این صورت است:

:template: template_name

برای محتوا در قالب Markdown:

Template: template_name

سپس کافی است مطمئن شوید پوسته (theme) شما حاوی فایل قالب مربوطه باشد (مانند template_name.html). اگر صرفاً می‌خواهید یک قالب سفارشی جدید را به یک پوسته موجود اضافه کنید، می‌توانید آن را در پوشه‌ای که توسط THEME_TEMPLATES_OVERRIDES مشخص شده قرار دهید (به بخش پوسته‌ها <#settings-themes> مراجعه کنید).

چگونه می‌توانم نشانی URL تولیدشده یک برگه یا مقاله خاص را بازنویسی کنم؟

متادیتای url و save_as را در هر برگه یا مقاله‌ای که می‌خواهید URL تولیدشده آن را بازنویسی کنید، قرار دهید. در اینجا نمونه‌ای از یک برگه در قالب reST آمده است:

Override url/save_as page
#########################
:url: override/url/
:save_as: override/url/index.html

با این متادیتا، برگه در مسیر override/url/index.html نوشته خواهد شد و Pelican از نشانی override/url/ برای پیوند به این برگه استفاده خواهد کرد.

چگونه می‌توانم از یک برگه ایستا به عنوان صفحه اصلی استفاده کنم؟

از قابلیت بازنویسی (override) ذکرشده در بالا می‌توان برای تعیین یک برگه ایستا به عنوان صفحه اصلی استفاده کرد. نمونه Markdown زیر می‌تواند در content/pages/home.md ذخیره شود:

Title: Welcome to My Site
URL:
save_as: index.html
Thank you for visiting. Welcome!

اگر همچنان به صفحه اصلی وبلاگ (blog index) نیاز است، می‌توان با تنظیم INDEX_SAVE_AS = 'blog_index.html' برای قالب مستقیم 'index'، آن را در مکان دیگری ذخیره کرد.

چگونه می‌توانم تولید خوراک (feed) را غیرفعال کنم؟

برای غیرفعال کردن تولید خوراک، تمام تنظیمات خوراک باید بر روی None تنظیم شوند. به جز سه مورد، مقدار پیش‌فرض تمام تنظیمات خوراک از قبل None است؛ بنابراین اگر می‌خواهید تولید تمام خوراک‌ها را غیرفعال کنید، تنها کافی است تنظیمات زیر را مشخص کنید:

FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

کلمه None نباید داخل علامت نقل‌قول قرار گیرد. لطفاً توجه داشته باشید که None و '' یکسان نیستند.

هشداری درباره تولید خوراک‌ها بدون تنظیم صحیح SITEURL دریافت می‌کنم

خوراک‌های RSS و Atom نیازمند آن هستند که تمام پیوند‌های URL مطلق باشند https://validator.w3.org/feed/docs/rss2.html#comments. برای تولید صحیح پیوندها در Pelican، باید SITEURL را روی مسیر کامل سایت خود تنظیم کنید.

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

آیا می‌توانم خوراک‌های Atom را مجبور به نمایش خلاصه به جای متن کامل مقاله کنم؟

اکثریت قاطع افرادی که از خوراک‌خوان‌ها استفاده می‌کنند، ترجیح می‌دهند محتوا را در خود برنامه‌خوان مطالعه کنند تا این‌که مجبور باشند پنجره جداگانه‌ای را در مرورگر باز کنند. عمدتاً به همین دلیل، Pelican از محدود کردن خوراک‌های Atom به خلاصه‌ها پشتیبانی نمی‌کند. برخلاف خوراک‌های Atom، مشخصات فنی خوراک RSS فیلد جداگانه‌ای به نام content ندارد، بنابراین Pelican به‌طور پیش‌فرض خوراک‌های RSS را تنها با خلاصه منتشر می‌کند (اما می‌توان آن را به صورت اختیاری برای انتشار محتوای کامل در خوراک‌های RSS نیز تنظیم کرد). در نتیجه، رفتار پیش‌فرض تولید خوراک برای کاربران یک حق انتخاب فراهم می‌کند: عضویت در خوراک‌های Atom برای دسترسی به محتوای کامل یا خوراک‌های RSS تنها برای دریافت خلاصه‌ها.

آیا Pelican فقط برای وبلاگ‌ها مناسب است؟

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

TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''

چگونه تنها زیرمجموعه‌ای از تمام مقاله‌ها را پردازش کنیم؟

اغلب برای اهداف اشکال‌زدایی مفید است که مثلاً تنها ۱۰ مقاله پردازش شوند. این کار را می‌توان با مشخص کردن صریح نام فایل‌های آن مقاله‌ها در ARTICLE_PATHS انجام داد. فهرستی از چنین نام فایل‌هایی را می‌توان با دستوری مشابه cd content; find -name '*.md' | head -n 10 به دست آورد.

ابر برچسب‌های من پس از ارتقای Pelican ناپدید/خراب شده است

در راستای تلاش مداوم برای بهینه‌سازی و ساده‌سازی Pelican، تولید ابر برچسب‌ها (tag cloud) از هستهٔ Pelican خارج شده و به یک افزونهٔ جداگانه https://github.com/pelican-plugins/tag-cloud منتقل شده است. برای اطلاعات بیشتر دربارهٔ سامانهٔ افزونه‌های Pelican، مستندات Plugins <#plugins> را مشاهده کنید.

از زمان ارتقای Pelican برگه‌های من دیگر رندر نمی‌شوند

برگه‌ها (Pages) در پوسته‌ها هم به صورت حروف کوچک pages و هم با حروف بزرگ PAGES در دسترس بودند. برای هماهنگی با بخش Templates and Variables <#templates-variables>، متغیر PAGES حذف شده است. این مشکل با به‌روزرسانی پوسته جهت پیمایش روی pages به جای PAGES به‌سرعت حل می‌شود. کافی است:

{% for pg in PAGES %}

را با چیزی شبیه به این جایگزین کنید:

{% for pg in pages %}

چگونه می‌توان از تلاش Pelican برای تجزیهٔ فایل‌های ایستا به عنوان محتوا جلوگیری کرد؟

تولیدکننده‌های مقاله‌ها و برگه‌های Pelican پیش از تولیدکنندهٔ فایل‌های ایستای آن اجرا می‌شوند. این بدان معناست که اگر تنظیمی مشابه با پیکربندی پیش‌فرض داشته باشید، که در آن یک پوشهٔ منبع ایستا درون یک تنظیم *_PATHS تعریف شده باشد، تمامی فایل‌هایی که پسوند فایل محتوایی معتبر دارند (.html، .rst، .md و ...) قبل از آنکه به عنوان فایل ایستا در نظر گرفته شوند، به عنوان مقاله یا برگه پردازش خواهند شد.

برای دور زدن این مشکل، یا از تنظیم مناسب *_EXCLUDES استفاده کنید یا خوانندهٔ مربوطه (reader) را در صورتی که نیازی به آن ندارید، از طریق READERS غیرفعال نمایید.

چرا [نحو دلخواه Markdown] پشتیبانی نمی‌شود؟

پردازش Markdown مستقیماً توسط Pelican انجام نمی‌شود و در عوض این کار به پروژهٔ Python-Markdown https://github.com/Python-Markdown/markdown واگذار شده است که هستهٔ آن عمداً از قواعد نحو اولیهٔ Markdown پیروی می‌کند و نه از انبوه «طعم‌ها» ("flavors")ی Markdown که پس از آن گسترش یافته‌اند. با این حال، پروژهٔ Python-Markdown https://github.com/Python-Markdown/markdown کاملاً پیمانه‌ای است و نحو مورد نظر شما ممکن است توسط یکی از افزونه‌های متعدد Markdown Extensions https://python-markdown.github.io/extensions ارائه شده باشد. از سوی دیگر، برخی کاربران افزونه‌هایی برای Pelican ایجاد کرده‌اند که از نگارش‌های مختلف Markdown پشتیبانی می‌کنند؛ بنابراین اگر می‌خواهید هنگام نوشتن محتوای خود از نگارش خاصی استفاده کنید، ممکن است این افزونه‌ها بهترین گزینه باشند.

نکات

در اینجا چند نکتهٔ کاربردی دربارهٔ Pelican آورده شده است.

صفحه‌های ۴۰۴ سفارشی

هنگامی که یک مرورگر منبعی را درخواست می‌کند که وب‌سرور قادر به یافتن آن نیست، وب‌سرور معمولاً یک صفحهٔ خطای پیش‌فرض «پرونده یافت نشد» (404) را نمایش می‌دهد که اغلب ساده و نازیبا است. یکی از راه‌های ارائهٔ یک صفحهٔ خطا که با پوستهٔ سایت شما همخوانی داشته باشد، ایجاد یک برگهٔ ۴۰۴ سفارشی (نه یک مقاله) است؛ مانند این نمونه با فرمت Markdown که در content/pages/404.md ذخیره شده است:

Title: Not Found
Status: hidden
Save_as: 404.html
The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?

گام بعدی، پیکربندی وب‌سرور جهت نمایش این برگهٔ سفارشی به جای صفحهٔ ۴۰۴ پیش‌فرض آن است. برای Nginx، عبارت زیر را به بلوک location در فایل پیکربندی خود بیفزایید:

error_page 404 /404.html;

برای Apache:

ErrorDocument 404 /404.html

برای Amazon S3، ابتدا در کنسول AWS به منوی Static Site Hosting در تنظیمات باکت بروید. از آنجا:

Error Document: 404.html

انتشار یک وب‌سایت پروژه در GitHub Pages از یک شاخه

برای انتشار یک وب‌سایت Pelican به‌صورت یک صفحه پروژه (Project Page)، باید محتوای دایرکتوری output تولیدشده توسط Pelican را به شاخه gh-pages یک مخزن در GitHub دستور push کنید.

ابزار عالی ghp-import https://github.com/davisp/ghp-import که با pip قابل نصب است، این فرایند را بسیار آسان می‌کند.

به‌عنوان مثال، اگر منبع وب‌سایت Pelican شما در یک مخزن GitHub قرار دارد، و می‌خواهید آن وب‌سایت Pelican را در قالب Project Pages در این مخزن منتشر کنید، می‌توانید از دستورهای زیر استفاده کنید:

$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push origin gh-pages

دستور ghp-import output شاخه محلی gh-pages را با محتوای دایرکتوری output به‌روزرسانی می‌کند (در صورتی که شاخه از قبل وجود نداشته باشد، آن را ایجاد می‌کند). دستور git push origin gh-pages شاخه دوردست gh-pages را به‌روز کرده و عملاً وب‌سایت Pelican را منتشر می‌سازد.

نکته:

انتشار یک وب‌سایت کاربری در GitHub Pages از یک شاخه

برای انتشار یک وب‌سایت Pelican در قالب صفحات کاربری (User Pages)، باید محتوای دایرکتوری output تولیدشده توسط Pelican را به شاخه main مخزن <username>.github.io خود در GitHub ارسال (push) کنید.

بار دیگر، می‌توانید از ابزار ghp-import بهره ببرید:

$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:main

دستور git push شاخه محلی gh-pages (که به‌تازگی توسط دستور ghp-import به‌روز شده است) را به شاخه main در مخزن elemoine.github.io در GitHub ارسال (push) می‌کند.

نکته:

گزینه دیگر برای انتشار به‌صورت User Pages، تولید فایل‌های خروجی در دایرکتوری ریشه پروژه است.

برای مثال، پوشه اصلی پروژه شما <username>.github.io است و می‌توانید پروژه Pelican را در یک زیردایرکتوری با نام Pelican ایجاد کنید. سپس از داخل پوشه Pelican می‌توانید اجرا کنید:

$ pelican content -o .. -s pelicanconf.py

اکنون می‌توانید کل پروژه <username>.github.io را به شاخه main مخزن GitHub خود push کنید:

$ git push origin main

(با فرض اینکه origin روی مخزن دوردست شما تنظیم شده باشد).

انتشار در GitHub Pages با استفاده از یک جریان کاری سفارشی GitHub Actions

وب‌سایت‌های مبتنی بر Pelican می‌توانند از طریق یک جریان کاری سفارشی https://github.com/getpelican/pelican/blob/main/.github/workflows/github_pages.yml در GitHub Pages منتشر شوند. برای استفاده از آن:

name: Deploy to GitHub Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
jobs:
  deploy:
    uses: "getpelican/pelican/.github/workflows/github_pages.yml@main"
    permissions:
      contents: "read"
      pages: "write"
      id-token: "write"
    with:
      settings: "publishconf.py"

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

نکات:

برای اطلاعات بیشتر، مستندات GitHub در مورد جریان‌های کاری با قابلیت استفاده مجدد (reusable workflows) را ببینید https://docs.github.com/en/actions/using-workflows/reusing-workflows.

هنگام فراخوانی جریان کاری، تعدادی ورودی اختیاری را می‌توان به بلوک with: اضافه کرد، برای مثال:

with:
  settings: "publishconf.py"
  requirements: "pelican[markdown] typogrify"
  theme: "https://github.com/seanh/sidecar.git"
  python: "3.12"

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