Это руководство о том, как создать свой собственный сайт с помощью генератора статических сайтов Luasmith и платформы для разработки Codeberg. Предполагается, что у читателя уже есть учётная запись на Codeberg и некоторые базовые знания об использовании git, но сверх того нет никаких требований; вещи, с которыми вы можете быть незнакомы, если никогда не создавали раньше статические сайты, будут объяснены, хотя я постараюсь не слишком углубляться в детали, а потому, надеюсь, эта статья может считать руководством для начинающих. Кроме того, этот текст можно квалифицировать как «журнал разработки», поскольку английскую версию этой статьи я писал непосредственного при создании этого сайта, на котором вы сейчас находитесь; процесс создания демонстрируется пошагово.
О Luasmith
Luasmith — генератор статических сайтов, каковых много, но этот является крошечным (один исполняемый файл размером менее 500КиБ, когда заархивирован с помощью gzip) и предоставляющим ограниченный функционал «из коробки», однако очень гибким и расширяемым. Реализуя необходимый минимум для создания блога или небольшого сайта (конвертирование Markdown в HTML, проверка ссылок, подсветка синтаксиса в блоках кода, и т. д.), он позволяет значительно менять поведение программы, что именно должен генератор делать с вашим контентом и как превратить его в веб-страницы; и для этого не потребуется изучать какие-то новые экзотические языки или разбираться с различными ограничениями (которые встречаются в других генераторах), но всё настраивается с помощью скриптов на языке Lua: старом (как хорошее вино), проверенным временем и распространённым скриптовым языком, так что, если вы уже знакомы с Lua, Luasmith может оказаться подходящим для ваших задач, поскольку в программу встроен стандартный интерпретатор Lua 5.5 со всей стандартной библиотекой и некоторыми дополнениями для удобства. Скачать программу можно со страницы выпусков на Codeberg, там есть сборки для Windows, Linux и «универсальный» исполняемый файл, который также запустится на OS X и большинстве систем BSD. Если же нужно запустить Luasmith на какой-то другой платформе, эта программа компилируется крайне просто.
Примите к сведению, что на момент написания этого руководства последняя версия Luasmith — 0.10. Эта версия прекрасно работает, и вы сможете повторить бóльшую часть руководства и создать свой собственный сайт, однако в одной из частей этой статьи я демонстрирую использовать темы для Luasmith, которая не совместима с версией 0.10, поскольку использует функционал, добавленный в программу после того выпуска. Если вы хотите полностью повторить все шаги в руководстве, и если на момент чтения вами этой статьи версия 0.10 всё ещё является последней, вам придётся скомпилировать Luasmith из свежих исходников.
Создание минимального блога
В этом руководстве я показываю команды терминала, которые работают на Linux в оболочке Bash; при работе в другой среде, не забудьте изменить команды так, как вам нужно. Начнём с создания директории для нашего сайта и инициализации репозитория git:
mkdir -p website/content
cd website
git init
Директорая content — место, где будут лежать все файлы контента, которые Luasmith должен обработать. Наименование «content» — стандартное имя директории, которое Luasmith ожидает найти для контента, однако можно назвать её иначе, если хотите. Писать статьи можно в формате Markdown; если вы не писали раньше тексты с использованием этого языка разметки, он очень прост в изучении, ввиду минималистичного, человеко-читаемого (и легко-человеко-печатаемого) синтаксиса. Помимо стандартного синтаксиса по спецификации CommonMark, Luasmith поддерживает таблицы в стиле GFM, сноски, зачёркнутый текст (с помощью знаков тильды, например ~~текст~~ превращается в текст) и встроенный HTML. Эту страницу я создал в файле Making this website.md1 в директории content, но помимо текста файл также содержит заголовочные данные (front-matter) для Luasmith. Эти данные могут быть написаны на YAML, JSON или Lua, но я рекомендую всегда писать их на Lua, поскольку поддержка других форматов является неполной. Для этой страницы, заголовок такой:
[[
title = 'Making a website using Luasmith and Codeberg'
date = '2026-11-03'
]]
Поле date — дата в формате ГГГГ-ММ-дд или ГГГГ-ММ-дд чч:мм:сс. Какие ещё поля можно добавить в заголовок зависит от темы, которую вы используете (что такое темы будет объяснено далее), но эти два (title, т. е. название, и date) являются базой, которую вы скорее всего всё равно будете писать для большинства страниц. Я также создал файл index.md с текстом, который появится на главной странице моего сайта.
Всё, что вы добавите в директорию контента, появится на вашем сайте, не только файлы Markdown. Допустим, вы хотите добавить изображение и поместили его по пути content/assets/picture.jpg, указать его в файле Markdown можно так: ; т. е. директория контента является «корнем» входных файлов для вашего сайта, и это работает не только для изображений, но и для ссылок на другие страницы (например, [другая страница](page.md)); кстати, если вы обеспокоены, будут ли ссылки на файлы md работать — да, будут, Luasmith автоматически превратит их в ссылки на сгенерированные html страницы. И ещё кое-что: крайне рекомендуется писать пути ссылок относительно текущей страницы, избегайте путей относительно корня (таких как [какая-то страница](/posts/some_page.md)), если только вы не уверены абсолютно, что ваш сайт будет предоставляться сервером из корня адреса (не из поддиректории), в противном случае ссылки сломаются; Luasmith проверит, что все относительные ссылки верны и предупредит, если что-то не так.
После добавления контента, нужно сделать ещё одну вещь: добавить скрипт site.lua вне директории контента (то бишь в website, не в website/content). Этот скрипт должен возвращать таблицу с данными для веб-сайта. В моём случае, скрипт выглядит так:
return {
title = ';',
subtitle = 'A blog of yet another geek',
url = 'https://fita-slovo.grebedoc.dev/semicolon/',
}
Поле url необходимо для лент Atom (RSS). Если у вас нет своего домена, далее в этом руководстве я объясняю, как опубликовать сайт с помощью сервисов Grebedoc и Codeberg Pages.
Теперь, когда есть какой-то контент и site.lua, можно собрать веб-сайт:
luasmith blog
Если вы назвали директорию контента иначе (например, mypages), добавьте дополнительный аргумент к команде с названием директории (по крайней мере, это работает в Luasmith версии 0.10, аргументы командной строки могут поменяться в будущем). И ещё можно добавить один аргумент с названием директории, куда будут записаны выходные файлы (по умолчанию out):
luasmith blog mypages output
Спустя миллисекунды после запуска команды, вы получите ваш веб-сайт в директории выхода. Можете открыть файл index.html в веб-браузере или запустить сервер, чтобы посмотреть на полученный сайт (например, можно запустить python3 -m http.server -d out).

Темы Luasmith
В командах, указанных выше, есть аргумент blog, значение которого я не объяснил: это название темы Luasmith, и тема «Блог» является одной из двух встроенных тем. Тема — это не просто «фасад», набор шаблонов, определяющих внешность сайта, но в первую очередь это «конвеер» (pipeline), который говорит Luasmith что делать. Создание своей темы Luasmith — вне рамок этого руководства, но вы можете начать с руководства из документации Luasmith, если действительно хотите сделать свою тему — и я надеюсь, что вы сделаете и опубликуете, потому что тем пока что, к сожалению, очень мало. Итак, как можно заметить, сайт, на котором вы сейчас находитесь выглядит совсем не так, как на снимке выше, поскольку я решил использовать тему «Нара», которую я написал не только ради другого внешнего вида, но и ради дополнительных возможностей (о которых вы можете прочитать в репозитории темы). И вот как я её добавил:
git submodule add https://codeberg.org/fita-slovo/luasmith-theme-nara.git themes/nara
git submodule update --init --recursive
Заметьте, что тема клонирована по пути themes/nara; это нужно для того, чтобы можно было выполнить команду luasmith nara вместо того, чтобы указывать полный путь, ведущий к файлу theme.lua (мне пришлось бы писать что-то вроде luasmith luasmith-theme-nara/theme.lua). Если нужно обновить тему («Нара», в общем-то, уже полностью готова, но всё же я планирую кое-что добавить в будущем), можно вытянуть изменения в директории темы:
pushd themes/nara
git pull --recurse-submodules
popd
Я хотел дать сайту более «нёрдовский» облик, а потому использовал цвета из палитры Solarized (полагаю, что она довольно узнаваема), и ещё сделал так, чтобы заголовок сайта (та точка с запятой на главной странице) мигал как в терминале; «Нара» позволяет мне сделать всё это не трогая саму тему, в файле site.lua:
local colors = {
light = {
bg = "#fdf6e3",
text = "#586e75",
accent = "#d33682",
dim = "#93a1a1",
code = "#657b83",
},
dark = {
bg = "#002b36",
text = "#93a1a1",
accent = "#d33682",
dim = "#586e75",
code = "#839496",
}
}
return {
title = ';',
subtitle = 'A blog of yet another geek',
url = 'https://fita-slovo.grebedoc.dev/semicolon/',
colors = colors,
customCss = [[
@keyframes blinker {
50% {
color: ]] .. colors.light.bg .. [[;
background-color: ]] .. colors.light.text .. [[;
}
}
p > code { color: ]] .. colors.light.code .. [[;}
@media (prefers-color-scheme: dark) {
@keyframes blinker {
50% {
color: ]] .. colors.dark.bg .. [[;
background-color: ]] .. colors.dark.text .. [[;
}
}
p > code { color: ]] .. colors.dark.code .. [[;}
}
.site-title {
animation: blinker 1s step-start infinite;
font-size: 4em;
margin: 2rem auto;
font-family: monospace;
width: fit-content;
}
]],
}
Теперь можно пересобрать веб-сайт с помощью команды luasmith nara, и спустя некоторое количество миллисекунд (на самом деле, «Наре» требуется больше времени для сборки сайта, чем теме «Блог», поскольку её код гораздо сложнее из-за дополнительного функционала) веб-сайт почти готов к публикации. Обратите внимание, что «Нара» генерирует человекопонятные URL (ЧПУ) по умолчанию, что, по-моему, здорово, но это препятствует тому, чтобы открыть веб-сайт локально в браузере из файловой системы, без запуска сервера. Если вы не хотите запускать сервер для локальной проверки сайта, но хотели бы сохранить ЧПУ при публикации, нет необходимости отключать эту функцию темы, вместо этого установите любое значение переменной окружения NO_PRETTY_LINKS при сборке для локального просмотра, а, когда готовы публиковаться, удалите переменную и пересоберите сайт.
Ещё неплохо будет добавить файл .gitignore и указать в нём директорию выходных файлов, поскольку их мы будем загружать в другую ветку git-репозитория и не хотим случайно добавить их в главную ветку (main).
Публикация
Это руководство, пожалуй, должно было называться «Создание сайта с помощью Luasmith и echo 'codeberg' | rev», потому что сайт я публикую на Grebedoc («Codeberg» наоборот), но я думаю, что код в заголовке — это довольно уродливо, да и заголовок тогда слишком длинный. В любом случае, использовать Grebedoc так же легко как Codeberg Pages, настройка ровно та же самая, меняется только URL. Итак, следующие шаги:
- Создать репозиторий на Codeberg;
- Добавить вебхук для публикации сайта из ветки
pages(сайт Codeberg Pages содержит короткую, но понятную инструкцию для этого), сама же ветка будет создана позже;

- Установить «origin» в локальном репозитории git (Codeberg показывает в пустых репозиториях, как это делается) и закоммитить всё, кроме директории выходных файлов.
Теперь немного сложная часть: пришло время создать рабочий каталог git (git worktree) в директории выходных файлов (в моём случае это out), который будет связан с веткой pages, так что исходники сайта будут в главной ветке, а в pages будут только сгенерированные файлы, которые и окажутся загружены на Grebedoc.
rm -rf out
git worktree add --orphan -B pages out
luasmith nara
cd out
git add -A
git commit -m "Загрузить сайт"
git push --set-upstream origin pages
После push’а, вебхук на Codeberg должен среагировать, и вскоре сайт будет опубликован! В следующий раз для обновления сайта --set-upstream … уже не понадобится, простой git push сработает.
Однако, теперь стоит быть осторожными: не удаляйте выходную директорию целиком, иначе придётся повторить шаги по настройке рабочего каталога. Использовать rm -rf out/* можно, поскольку эта команда не только не удаляет саму директорию, но также и не затрагивает скрытые файлы, включая файл .git в директории, который и нужен для сохранения рабочего каталога. Хорошей идеей будет добавить скрипт (или даже несколько) со всеми командами, необходимыми для работы с сайтом, или, ещё лучше, файл системы GNU Make (Makefile):
LS=luasmith
C=content
O=out
S=site.lua
build: clean
$(LS) nara $(C) $(O) $(S)
clean:
[ "$(O)" ] || exit 1
rm -rf $(O)/*
serve: build
python3 -m http.server -d $(O)
Если хотите, файл можно сделать проще, но я когда-то нашёл необходимым иметь возможность настраивать все аргументы для экспериментов и тестирования различных вещей в моих проектах, использующих Luasmith. Кстати, та загадочная строка — ["$(O)"] || exit 1 — означает «проверить, что $(O) — не пустая переменная, в противном случае выйти»; без этой проверки есть риск воспроизвести старый добрый баг Steam из 2015.
Надеюсь, после прочтения этого руководства вы будете использовать Luasmith для создания классных веб-сайтов, чтобы сделать Интернет лучше.
- Поскольку это руководство было изначально написано на английском, и оно описывает, как я создавал этот сайт, названия файлов и страниц сохранены как в оригинальном тексте.↩