Добрый день, друзья!

Сегодня я хочу рассказать вам о Pelican и о том, как с его помощью можно вести свой блог.

Начнём с того, что же это вообще такое и кому подойдёт. Затем установим Pelican и рассмотрим некоторые неочевидные новичку вещи.

Что это такое?

Pelican - это генератор статических сайтов (SSG 1), реализованный на Python. Статические сайты - те, что не используют какие-либо серверные механизмы построения страниц. Один раз собрали (сгенерировали) контент и потом всегда отображаем его без изменений. Синтаксис файлов - reStructuredText или Markdown (потребуется добавить соответствующий модуль Python).

Для чего это нужно?

Статические сайты - это всё, что не изменяется. Сюда можно отнести сайты-визитки, лендинги 2, прочие сайты, где не требуется динамическая сборка страниц перед выдачей пользователю. И даже блоги, если нет необходимости в CMS и системе прав.

Для чего не подходит?

Ответ следует из написанного выше. Статические сайты не подходят там, где требуется динамика. Они также не подходят, если требуется разграничить права на доступ к страницам. Конечно, можно настроить базовую аутентификацию HTTP, но это будет костыль, который и выглядит не ахти, и возможности имеет очень ограниченные.

Как это работает?

Работает всё довольно просто:

Очень полезный момент - в качестве сервера для статического сайта подходит любой хостинг. Можно даже и без хостинга - использовать GitHub Pages.

Что требуется?

Необходимого немного:

А вот если хочется комфорта, то добавим:

Здесь я буду показывать самый комфортный вариант - с PyCharm. При желании работать с venv вручную, можете обратиться к заметке о нём.

Создадим проект в PyCharm

Меню File > New Project.... Выбираем Pure Python и New environment using Virtualenv.

Создание проекта

Если вы делаете без PyCharm, то просто установите virtualenv, создайте виртуальное окружение, перейдите в него и активируйте.

pip install virtualenv
virtualenv test-blog
cd test-blog
source bin/activate

Установим сам Pelican

Сразу можем указать модули, которые нам потребуются для работы (например, плагинов).

pip install pelican webassets Markdown beautifulsoup4

Открываем внизу PyCharm панель Terminal и запускаем инициализацию генератора.

pelican-quickstart

Нас просят ответить на несколько вопросов.

Запуск pelican-quickstart

После этого в папке проекта появятся:

Установим плагины

Если не планируете вести несколько проектов со статической генерацией сайтов, плагины клонируем в папку нашего проекта. Если же проектов у вас несколько, то лучше плагины клонировать в какую-то общую папку. В любом случае переходим в терминале в ту папку, где будем держать плагины и выполняем команду:

git clone --recursive https://github.com/getpelican/pelican-plugins plugins

После завершения в текущей папке появится папка plugins с плагинами.

Открываем файл pelicanconf.py, ищем там PLUGIN_PATHS. Если не нашли - добавляем. Нашли - изменяем. В итоге нам нужно получить:

PLUGIN_PATHS = ['plugins', ]

если клонировали в текущую папку. Если же вы клонировали в другую папку - вместо 'plugins' указываем путь к этой папке.

Те плагины, что будем использовать, указываем в переменной PLUGINS:

PLUGINS = ['assets', 'neighbors', 'summary']

Установим тему

Чтобы меньше заморачиваться, я рекомендую клонировать себе и все темы из официального репозитория. Делается это аналогично тому, как мы клонировали плагины:

git clone --recursive https://github.com/getpelican/pelican-themes themes

Создаём в папке нашего проекта папку theme. Выбираем тему, которую хотим установить и копируем её в эту папку. Например, я выбрал тему pelican-striped-html5up и скопировал всю её папку в theme.

Копировать тему в отдельную папку я рекомендую по той причине, что может потребоваться её доработка. В таком случае изменять тему в папке, куда клонировали, не лучшая идея - при обновлении официального репозитория придётся чуть больше возиться.

Открываем файл pelicanconf.py и указываем путь к используемой теме:

THEME = 'theme/pelican-striped-html5up'

Настроим конфиг

Настраиваем список ссылок на внешние ресурсы:

LINKS = (
    ("nornad's python", 'https://python.nornad.com/'),
    ('кто такой nornad?', 'https://nornad.com/'),
)
SOCIAL = tuple()  # мне эти ссылки пока не нужны

Указываем, как должны выглядеть ссылки на страницы и куда их надо сохранять:

ARTICLE_URL = '{date:%Y}/{slug}/'                # сделаем адреса статей информативнее
ARTICLE_SAVE_AS = '{date:%Y}/{slug}/index.html'  # укажем, что сохранять файлы надо по папкам
PAGE_URL = '{slug}/'                             # аналогично
PAGE_SAVE_AS = '{slug}/index.html'               #      для страниц
TAG_URL = 'tag/{slug}'                           # аналогично
TAG_SAVE_AS = 'tag/{slug}/index.html'            #      для тегов
CATEGORY_URL = 'category/{slug}'                 # аналогично
CATEGORY_SAVE_AS = 'category/{slug}/index.html'  #      для категорий
CATEGORIES_SAVE_AS = 'categories.html'           # как сохранить страницу списка категорий
TAGS_SAVE_AS = 'tags.html'                       # как сохранить страницу списка тегов
YEAR_ARCHIVE_SAVE_AS = '{date:%Y}/index.html'    # как сохраняем страницу со ссылками на все записи года
MONTH_ARCHIVE_SAVE_AS = '{date:%Y}/{date:%m}/index.html'  # как сохраняем страницу со ссылками на все записи месяца
DAY_ARCHIVE_SAVE_AS = ''                         # дневные архивы мне не нужны
AUTHOR_SAVE_AS = ''                              # убираем страницы со списком статей конкретного автора

Укажем, где у нас хранятся картинки и доп.файлы:

STATIC_PATHS = ['images', 'extra', ]

Осталось настроить только расширения Markdown. Нас интересует в первую очередь markdown.extensions.codehilite:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {
            'css_class': 'highlight',
            'lang_prefix': 'lang-',
            'pygments_formatter': 'html',
        },
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
}

Доработаем тему

Сначала я планировал показать, где и что надо изменить, чтобы понравившаяся мне тема pelican-striped-html5up заработала хотя бы так, как её задумывали. Но этих изменений оказалось слишком много. Поэтому я просто сделал архив (v1:2022-08-14) с доработанной темой. Сразу скажу, что я пока ещё не во все уголки темы залез и наверняка доработка ещё требуется. Буду указывать рядом с архивом дату его обновления и номер версии, чтобы вам проще было понять, изменилось ли что-то.

Создадим заметку

Создание заметки можно условно разделить на два этапа: 1. описание мета-данных (заголовок страницы) 2. написание тела заметки

Создадим в папке content файл hello-world.md. Зададим заголовок:

Title: Hello world!
Date: 2022-08-14 13:50
Author: nornad
Category: hello
Tags: blogging, test
Slug: hello-world
Status: published

Отступаем от заголовка одну пустую строку и пишем саму нашу заметку.

Добавим картинку

Сначала нам надо сохранить картинку в папку content/images. Допустим, ваша картинка называется 1.png. Вставим её на страницу:

Картинка с атрибутом **alt**:
![Моя любимая картинка. Жаль, что она у вас не загрузилась](/images.1.png)
Картинка с атрибутами **alt** и **title**:
![Моя любимая картинка. Жаль, что она у вас не загрузилась](/images.1.png "Скажите же, классная картинка. 😉")

Добавим иконку сайта

Скопируйте свою иконку сайта (формата .ico) в проект в папку content/extra. Укажем в конфиге, что её надо скопировать в корневую папку нашего сайта:

EXTRA_PATH_METADATA = {
    'extra/cowboy_favicon.ico': {'path': 'favicon.ico'},
}

Поиграем с подсветкой синтаксиса

Просто подсвечиваем код так

```python
from os import getenv
print('hello')
```

или так (с отступами)

    :::python
    from os import getenv
    print('hello')

Если нам нужно показать номера строк, делаем так

```{python linenums=True}
from os import getenv
print('hello')
```

или так (с отступами)

    #!python
    from os import getenv
    print('hello')

Соберём наш сайт

В Linux мы можем использовать Makefile, что упрощает команды.

make html       # если нам требуется только сгенерировать сайт
make devserver  # если мы желаем ещё и запустить локальный сервер для проверки

Локальный сервер будет доступен по адресу http://127.0.0.1:8000/.

Если же вы работаете с пеликаном в Windows, то команды будут такими:

# make html
pelican content -o output -s pelicanconf.py
# make devserver
pelican -lr content -o output -s pelicanconf.py

Можно, конечно, в Windows 10/11 использовать интегрированный linux, но лично мне он неудобен.

Что дальше?

Осталось только выгрузить содержимое папки output на ваш сервер и проверить, как всё замечательно работает. Если же у вас пока нет хостинга и понимания, как туда выгрузить файлы - не беда. В будущих заметках я рассмотрю пару вариантов.

Полезные ссылки

  1. SSG - Static Site Generator ↩

  2. Лендинг (landing) - одностраничный сайт, имеющий целью заинтересовать покупателя в приобретении товара или услуги и передать его данные куда-то ещё для обработки менеджерами. ↩