Як писати для цього сайту, /bˈɒləks/

Сайт зібрано на Zola 0.23. Кожна сторінка — це Markdown-файл у content/ з блоком TOML на початку. Zola пропускає кожен файл спершу через свій шаблонізатор Tera, потім через Markdown, а шаблони з templates/ перетворюють результат на пронумерований документ із датами, як-от цей.

Попередній перегляд

nix develop -c zola serve

Ця команда відкриває сайт на http://127.0.0.1:1111 і перезбирає його після кожного збереження. Биті внутрішні посилання та невідомі мови коду тут одразу видно як помилки, тож тримайте її запущеною в терміналі, поки пишете.

Перед публікацією зберіть сайт так само, як це робить розгортання:

nix flake check

Вона падає на тих самих помилках, що й zola serve, тож якщо перевірка пройшла, сайт збереться.

Куди класти сторінку

Види сторінок

Що пишете	Файл	Нумерація
Допис	`content/writing/slug.uk.md`	W-001, за датою
Допис із зображеннями	`content/writing/slug/index.uk.md`, зображення поруч	W-001, за датою
Коротку нотатку	`content/notes/slug.uk.md`	N-001, за датою
Посібник	`content/guides/category/slug.uk.md`	NIX-01, за вагою
Англійську версію	та сама назва без `.uk`	рахується окремо

Назва файлу стає адресою: content/writing/pinning-nixpkgs/index.uk.md публікується за адресою /uk/writing/pinning-nixpkgs/. Пишіть назви малими латинськими літерами через дефіс, навіть для української сторінки, щоб адреса лишалася читабельною, коли нею діляться.

Номери не зберігаються, а рахуються. Допис із датою, ранішою за найновіший, зсуває номери після себе; посібник із меншою вагою зсуває посібники після себе. Якщо номер не повинен змінюватися ніколи, закріпіть його ключем id у [extra].

Шапка сторінки

Блок між рядками +++ — це TOML. Ключі, які знає Zola, ідуть угорі; ключі, які додає цей сайт, — під [extra]. Ключ не на своєму місці мовчки ігнорується, тож якщо налаштування ні на що не впливає, перевірте, з якого боку від [extra] він стоїть.

Дописи

+++
title = "Пінимо nixpkgs без флейків"
date = 2026-10-21
updated = 2026-10-27           # необов'язково; показується як «Переглянуто»
description = "Одне речення під назвою та в превʼю посилань."
[taxonomies]
tags = ["nix"]
[extra]
toc = true                     # зміст під блоком із даними документа
revisions = [                  # необов'язково; остання — поточна редакція
  { rev = "A", date = "2026-10-21", note = "Перша публікація." },
  { rev = "B", date = "2026-10-27", note = "Що змінилося, одним рядком." },
]
# numbered = false             # без номерів розділів у заголовках
# id = "W-100"                 # закріпити номер документа
+++

Додаючи редакцію, змініть і updated. Зі списку редакцій складається таблиця наприкінці сторінки, а updated використовують реєстр і стрічка.

Нотатки

Нотатці потрібна лише дата. Якщо назви немає, реєстр показує замість неї перший рядок тексту.

+++
date = 2026-10-25
[taxonomies]
tags = ["nix"]
+++

Посібники

Посібник приймає все те саме, що й допис, плюс weight і status:

+++
title = "Збирання сміття та місце на диску"
date = 2026-06-30
updated = 2026-10-20
weight = 20                    # місце в категорії; лишайте проміжки
[taxonomies]
tags = ["nix"]
[extra]
status = "stable"              # draft, stable або outdated
# outdated_note = "Написано для fish 3.6, ще не перевірено з fish 4."
+++

Ваги 10, 20, 30 лишають місце, щоб пізніше вставити посібник між двома іншими, не переписуючи всі файли.

draft і outdated додають під назвою банер. outdated_note замінює його стандартний текст, тож напишіть, що саме застаріло і відколи.

Нова категорія посібників

Категорія — це тека в content/guides/ з файлом _index.uk.md:

+++
title = "Nix"
weight = 1                     # порядок на /uk/guides/
sort_by = "weight"
template = "category.html"
generate_feeds = true          # /uk/guides/nix/atom.xml
[extra]
code = "NIX"                   # NIX-01, NIX-02…
+++

Один рядок про те, що є в цій категорії.

Без _index.uk.md тека не з’явиться українською, а її посібники не отримають номерів. Для англійської версії категорії потрібен окремий _index.md.

Заголовки

Починайте розділи з ##. Назва сторінки — єдиний #. Заголовки ## і ### отримують номери розділів (1, 1.1…) і потрапляють до змісту; глибше за ### ідіть лише для низки коротких пунктів.

Zola робить якір кожного заголовка з його тексту, тож перейменований заголовок ламає посилання на нього. Щоб якір не змінювався, або щоб дати українському заголовку короткий латинський якір, задайте його самі:

## Майстер-пароль {#master-pass}

Текст

Розумна пунктуація ввімкнена: -- стає коротким тире, а --- — довгим. Прямі лапки "так" стають англійськими «кучерявими», тож українські «ялинки» набирайте безпосередньо. Апостроф ' теж стає типографським.

<mark>текст</mark> виділяє одну фразу на сторінці, яка важить найбільше. Використовуйте це раз, якщо взагалі.

Для глосаріїв є списки визначень:

Замикання
: Шлях у сховищі та все, на що він посилається.

Сирий HTML можна писати прямо в Markdown, коли більше нічого не підходить.

Посилання

На іншу сторінку посилайтеся через її файл, починаючи з @/:

[збирання сміття](@/guides/nix/garbage-collection.md)
[паролі](@/guides/cybersecurity/passwords.uk.md#master-pass)

Zola перевіряє такі посилання під час збирання. Якщо сторінку перенесли чи видалили, збирання падає, а не публікує мертве посилання, і на цільовій сторінці в розділі «Посилаються» видно всі сторінки, що на неї посилаються. Шлях завжди починається від content/ і містить .uk, якщо файл український: без .uk посилання веде на англійську версію.

Посилання на інші сайти — звичайний Markdown.

Код

Вказуйте мову після відкривальних апострофів. Невідома назва ламає збирання, а не тихо показує простий текст, тож описки на кшталт bahs не проскочать. Для виводу, який не є кодом, пишіть txt.

Назву файлу та підсвічені рядки задають опції після коми:

```nix,name=shell.nix,hl_lines=2-3
{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  packages = [ pkgs.zola ];
}
```

Виглядає це так:

{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  packages = [ pkgs.zola ];
}

Виноски-попередження

Синтаксис сповіщень GitHub, п’ять видів:

> [!WARNING]
> Ця команда видаляє всі старі покоління.

Примітка (NOTE) і Порада (TIP) мають чорний колір, Важливо (IMPORTANT) — синій, Попередження (WARNING) і Обережно (CAUTION) — червоний. Червоний лишайте для того, що знищує дані або доступ.

Заголовка в такої виноски немає. Щоб підписати її, почніть із жирної фрази: > **Аналогія.** ….

Примітки та бічні нотатки

Примітка — це звичайний Markdown:^[1]

Твердження, якому потрібне джерело.[^src]

[^src]: Джерело.

Надавайте перевагу приміткам. Бічну нотатку беріть лише тоді, коли читач із телефона має відкрити її на місці, не стрибаючи в кінець:На телефоні торкніться номера, щоб відкрити. Markdown усередині працює.

Речення, якому потрібна нотатка.{{ <sidenote text="Нотатка." /> }}

Таблиці

Звичайна Markdown-таблиця працює. Щоб пронумерувати її та дати назву, обгорніть її:

{% <tbl caption="Порівняння підходів"> %}
| Підхід | Чим оновлювати |
|---|---|
| npins | `npins update` |
{% </tbl> %}

Перед підписом з’явиться «Таблиця 1.», рахуючи від початку сторінки.

Рисунки та зображення

{{ <figure src="diagram.svg" alt="Що зображено" caption="Необов'язково, *Markdown* можна" /> }}

До підпису додається «Рисунок 1.»; на широкому екрані підпис переїжджає на поле. alt пишіть для того, хто не бачить зображення: що на ньому, а не як воно називається. Підпис — для всіх, і в ньому може бути посилання; саме там місце для зазначення автора.

Від того, де лежить файл, залежить, як писати src:

Поруч зі сторінкою. Перетворіть post.uk.md на post/index.uk.md і покладіть зображення в post/. Тоді src="diagram.svg". Українська версія може мати власне зображення, diagram.uk.svg.
У static/. static/images/x.png доступний за адресою /images/x.png, тож src="/images/x.png". Так робіть із зображенням, спільним для кількох сторінок, або для посібника з одного файлу.

Для схем беріть SVG. Фотографії тримайте в межах кількох сотень кілобайтів.

Позначки змін

Коли редакція змінює абзац, позначте його, щоб ті, хто повертається, знайшли нове:

{% <changed rev="B"> %}
Абзац, що змінився.
{% </changed> %}

Поруч на полі з’являється смуга, а на широкому екрані — ще й літера редакції. Не забудьте додати редакцію в revisions у шапці.

Списки завдань

- [ ] Встановити менеджер паролів.
- [ ] Змінити пароль пошти.

Вони показуються як порожні квадратики — для списку «зробіть сьогодні» наприкінці посібника. Позначити їх не можна.

Фігурні дужки шаблонів

Tera читає сторінку раніше за Markdown, тож буквальні {{ або {% будь-де в тексті, навіть усередині блоку коду, вважаються тегом шаблону і зазвичай ламають збирання. Обгортайте такі фрагменти:

{% raw %}
Усе, що містить {{ або {%.
{% endraw %}

Приклади на цій сторінці обгорнуто саме так.

Мови

Українська сторінка — це та сама назва файлу з .uk перед .md, поруч з англійською: passwords.md і passwords.uk.md. Коли є обидві, перемикач мови в шапці веде просто між ними; інакше — на головну сторінку іншої мови.

Кожна може існувати сама по собі. Кожна мова має власні номери, теги та стрічку, тож сторінка, яка є лише українською, отримує номер лише серед інших українських сторінок.

Розділам потрібен власний _index.uk.md, щоб вони взагалі з’явилися українською. Текст інтерфейсу, тобто підписи довкола вмісту, лежить у zola.toml у [languages.uk.translations].

Перед публікацією

nix flake check проходить.
description — одне речення, яке каже, що отримає читач.
Кожне зображення має alt.
Переглянута сторінка має новий запис у revisions і нову дату updated.
Посібник має weight і status.
Якщо є переклад, він має ту саму назву файлу з .uk або без.

Як-от ця. На широкому екрані вона стоїть на полі, а на телефоні чекає наприкінці, у розділі «Примітки». ↩