From 423468a50b7165950b4406b90fbb0db5b0dac3cd Mon Sep 17 00:00:00 2001 From: ge Date: Mon, 3 Oct 2022 13:03:39 +0300 Subject: [PATCH] upd --- content/projects.rst | 2 +- content/this_blog.rst | 339 ------------------------------------------ 2 files changed, 1 insertion(+), 340 deletions(-) delete mode 100644 content/this_blog.rst diff --git a/content/projects.rst b/content/projects.rst index 8b6e0ec..59eb395 100644 --- a/content/projects.rst +++ b/content/projects.rst @@ -13,6 +13,6 @@ * `vk-toot `_ -- кросспостер VK -> Mastodon * `piglet `_ -- клиент DNS API Porkbun * roadwarrior -- менеджер подключений к VPN и прокси -* `n! ` -- консольный менеджер заметок +* `n! `_ -- консольный менеджер заметок Остальное есть в `Gitea `_. diff --git a/content/this_blog.rst b/content/this_blog.rst deleted file mode 100644 index 673aaa3..0000000 --- a/content/this_blog.rst +++ /dev/null @@ -1,339 +0,0 @@ -:title: Как я написал этот блог -:date: 5 Aug 22 -:type: page - -.. note:: - - Статья малось устарела и не соответсвует текущей действительности. - -======================= -Как я написал этот блог -======================= - -Я очень давно планировал написать блог. Именно что написать CMS для ведения -блога. Если погуглить, то CMS для этих целей сотни на разных языках с разным -позиционированием и фичами. Но мне хотелось своего. - -Первые попытки создать сайт были на `Flask`_, особым успехом не увенчались, -но это была хорошая практика и я немного прокачал свой уровень программирования. - -Для блога я не хотел использовать базу данных. Вместо этого я хранил статьи в -исходном Markdown, а метаданные по каждой статье писал в отдельный JSON, который -заменял мне БД. С тем же успехом я мог бы использовать SQLite, но мне нужно было -хранить контент в text/plain. - -Блог даже работал, но мне хотелось сделать админку, чтобы можно было писать -прямо в браузере. На этой части разработка заглохла и я окончательно запутался в -импортах в Python) - -Прошло ещё много времени, я вернулся к идее, но решил сделать ставку на простоту -и начал писать на `Bottle`_. Здесь разработка остановилась не дойдя даже до -варианта хоть как-то работающей системы. Причины скорее всего надо искать в -лени. - -Устав я взял `CMS Bludit`_ и стал вести свои редкие заметки в нём. Решение не -самое плохое, но и не супер отличное. Для простой кастомизации футера пришлось -городить костыли. - -.. _Flask: https://flask.palletsprojects.com/ -.. _Bottle: https://bottlepy.org/ -.. _CMS Bludit: https://www.bludit.com/ru/ - -Статика VS динамика -=================== - -Преимуществ у статических сайтов много. Об этом уже много написано. Мне больше -всего в статических сайтах нравится то, что: - -* роутингом запросов не управляет какой-либо скрипт, я могу свободно - распоряжаться тем, что у меня есть в DocumentRoot; -* не нужно настраивать application-сервер и реверс-прокси на него. - -С редактированием сайта чуть сложнее, так как сперва надо внести изменения -локально, а затем заменить изменившиеся файлы на сервере. Но и тут есть -какие-то решения. - -Я рассматривал уже готовые генераторы статических сайтов, но у них всех были -фатальные недостатки: - -* они сложные и требуют изучения документации чтобы начать писать; -* написать собственную тему задача весьма непростая; -* они написаны не мной. - -Здесь и рождается мой велосипед, которому я не придумал названия. Буду называть -его `генератором`. - -*re*\ **Structured**\ *Text* -============================ - -Я очень долго писал на Markdown, но в один момент понял, что возможностей языка -стало нехватать. Тут пришёлся очень кстати `Python-Markdown`_ к которому можно -было прикручивать `расширения`_. Одно даже сам `написал`_. - -Постепенно я пришёл к `reStructuredText`_. Все приколюхи, которые в нём есть -существуют не за счёт расширения синтаксиса плагинами, а заложены в спецификации. -Функциональности из коробки хватает чтобы писать даже `формулы`_. - -Такие вещи делаются через `роли` и `директивы`. Некоторые готовые директивы есть -в системе документации `Sphinx`_. Их я собираюсь потихоньку скопировать к себе. - -Ещё одно большое преимущество перед Markdown состоит в том, что reStructuredText -поддерживает атрибуты. Вот как это выглядит: - -.. code-block:: rst - - :title: Как я написал этот блог - :date: 5 Aug 2022 - -Это нативная фича, которую можно использовать в статьях для добавления метаданных. - -По сути это место, где можно сделать настройки, касающиеся отдельно взятой статьи. - -Большинство генераторов статических сайтов колхозят нечно подобное в Markdown, делая -исходник статьи непригодным для парсинга другими инструментами. Это причина по -которой в старой реализации блога мне пришлось использовать JSON для метаданных. - -.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html -.. _Python-Markdown: https://python-markdown.github.io/ -.. _расширения: https://python-markdown.github.io/extensions/ -.. _написал: https://pypi.org/project/markdown-alerts/ -.. _rST: https://docutils.sourceforge.io/rst.html -.. _формулы: https://docutils.sourceforge.io/docs/ref/rst/mathematics.html - -Обзор -===== - -Сайт состоит из следующих частей. - -rst_blg.py - Непосредственно код генератора. Сейчас там всего около 200 строк без учёта - комментариев. - -requirements.txt - Список зависимостей. Стараюсь держать минимум. Пока что там: `docutils`, - `jinja2`, `toml` и `pygments`. - -settings.toml - Файл с настройками. Здесь можно переопределить практически всё. - -Makefile - Через него запускаются команды для сборки сайта и некоторые другие. Не - является обязательным, но с ним удобнее. - -layouts - Директория для шаблонов Jinja2. - -assets - Директория для хранения статических файлов, будь то CSS, JS или изображения. - Всё что нужно для визуального оформления страниц. Внутренняя структура - каталога может быть произвольной. - -content - Директория с исходниками статей в reStructuredText. Сюда можно также - положить любые файлы и директории. - -build - В эту директорию копируются ассеты, файлы и сгенерированный HTML. - -Статьи, шаблоны и ассеты могут быть оформлены абсолютно любым образом. Скрипту -безразлично что собирать. Пути и имена всех директорий можно переопределить в -settings.toml. - -Исходники с небольшой инструкцией я положил сюда: https://git.nxhs.cloud/ge/blog - -Написание постов -================ - -Тут всё предельно просто. Пишем файл и кладём в директорию `content`. В файле -должны быть указаны обязательные атрибуты ``:title:`` и ``:date:``. - -Блог пока не умеет работать с вложенной структурой статей. Поэтому всё будет -свалено в кучу в корневую директорию сайта. - -Все статьи добавляются в список постов и отображаются на главной странице. - -Для того, чтобы сделать "отдельную" страницу, надо добавить атрибут -``:not_a_post:``. - -================= ======= =========== ==================================== -Атрибут Тип Умолчание Описание -================= ======= =========== ==================================== -``:title:`` Строка Заголовок статьи -``:date:`` Дата Дата публикации, формат задаётся в - settings.toml -``:not_a_post:`` Флаг для одиночных страниц -================= ======= =========== ==================================== - -Темы оформления -=============== - -Никаких готовых тем. Пишем CSS вручную. Генератору сайтов всё равно что там -будет. От уровеня представления он никак не зависит. Так что можно писать любые -шаблоны и стили для них. - -Отдельно можно задать тему для блоков кода. Список тем для Pygments с превью -есть на странице https://pygments.org/styles/ - -Чтобы поменять тему, например, на `default` надо выполнить команду: - -.. code-block:: shell - - make css default - # или - pygmentize -f html -S default -a .highlight > assets/css/pygments/default.css - -Затем поменять значение ``theme`` в секции ``pygments`` settings.toml. - -.. code-block:: toml - - [pygments] - theme = 'default' - -Шаблоны -======== - -Шаблоны можно писать какие угодно. Для этогой сайта я написал три файла. -Приведу их без лишних строк. - -**base.j2** - -.. code-block:: html+jinja - - - - - - - - - - - {{ page_title }} | {{ site_title }} - - - -
-

- {% if posts %} - {{ site_title }} - {% else %} - {{ site_title }} / {{ page_title }}

- {% endif %} -

-
- - {% block content %}{% endblock %} - -
- -
- - - - -**post.j2** - -.. code-block:: html+jinja - - {% extends "base.j2" %} - {% block content %} - -
- {{ post | safe }} -
- - {% endblock %} - -**index.j2** - -.. code-block:: html+jinja - - {% extends "base.j2" %} - {% block content %} - -
-
    - {% for post in posts %} -
  • - {{ post['title'] }} - — {{ post['date'] }} -
    • - {% endfor %} -
-
- - {% endblock %} - -settings.toml -============= - -Сначала я хотел использовать обычный INI, но мне нужно было получать из конфига -словарь. Немного подумал и выбрал TOML. Он отлично сериализируется в словарь, -визуально повторяет INI. - -**settings.toml** разделён на несколько секций. - -site - Данные касающиеся непосредственно сайта. - - title - Название сайта - - index_page_title - Заголовок главной страницы. Для всех остальных страниц заголовок - берётся из атрибута. - - datatime_format - Формат даты для атрибута ``:date:``. - -build - Параметры, используетмые при сборке. - - build_dir - Директория, куда будет сохранён собранный сайт. - - content_dir - Директория с исходниками статей. - - templates_dir - Директория с шаблонами Jinja2. - - assets_dir - Директория с ассетами. - -pygments - Параметры подсветки синтаксиса в блоках кода. - - theme - Стиль Pygments. - -docutils - Конфигурация для docutils. Здесь можно указать любые параметры, которые - есть здесь: https://docutils.sourceforge.io/docs/user/config.html - - Мне достаточно: - - .. code-block:: toml - - [docutils] - initial_header_level = 2 - section_self_link = true - syntax_highlight = 'short' - -Что ещё хочется сделать -======================= - -В перспективе я планирую добавить следующие фичи. - -- RSS -- OpenGraph -- Webmention -- Расширить возможности rST до уровня Sphinx -- Улучшить CSS -- Комментарии -- Кастомный лейаут для отдельных статей -- Поддержка вложенной структуры статей - -.. * https://jinja.palletsprojects.com/en/3.0.x/templates/ - * https://docutils.sourceforge.io/docs/user/config.html -