Luasmith Plugins

Локализация

2026-09-18T00:00:00.000Z

Плагин i18n для Luasmith предоставляет инструменты для создания многоязычных сайтов. Он использует Lettext, реализацию Gettext для Lua, позволяя переводить строки в шаблонах вашего сайта с использованием распространённого формата файлов PO. Плагин автоматически извлекает строки и генерирует PO(T) файлы при сборке веб-сайта, так что вам не понадобятся стандартные утилиты Gettext (такие как xgettext и msgmerge) — Lettext и плагин делают всё необходимое, чтобы упростить создание многоязычных сайтов.

Плагин не доделан. Хотя основные вещи завершены, все ещё есть некоторые важные нереализованные части. Ожидаются кардинальные изменения.

Структура содержимого

Для указания языка страницы вы можете либо использовать поле lang в метаданных, либо добавить суффикс к имени файла. Суффикс удобен, когда вы хотите использовать некоторые страницы как переводы друг для друга, и плагин учтёт это, позволяя создать переключатель языков (как тот, что вы можете видеть вверху этой страницы).

Предположим, каталог content выглядит следующим образом:

content/
 | index.md
 | index.ru.md
 | some_page.md

И в some_page.md указано lang = ru; на выходе будет такая структура:

out/
 | index.html
 | ru/
    | index.html
    | some_page.md

Плагин сам отредактирует ссылки в содержимом страниц, так что их следует указывать так, как это корректно для структуры директории content, не беспокойтесь о том, что путь к корню поменяется.

Пайплайн

Для локализации ваших страниц потребуется всего 2 узла в пайплайне.

i18n.localize(defaultLang, potAsDefault)

Этот узел проходит через все страницы, меняя пути и относительные ссылки так, как нужно; необходимые специфические поля у каждого элемента (item) также будут установлены.

defaultLang — код языка по умолчанию для вашего сайта. Страницы без указанного поля lang и без кода языка в суффиксе имени файла будут считаться страницами на языке по умолчанию. Если defaultLang - nil, то язык по умолчанию будет en.

potAsDefault устанавливает, будет ли файл messages.pot использоваться как резервный источник перевода строк для языка по умолчанию. Если язык по умолчанию имеет несколько форм множественного числа (как русский язык, например), то будет недостаточно использовать только msgid и msgid_plural для корректного отображения; если potAsDefault является true, вы можете добавить msgstr в POT файл, чтобы обойти ограничение и плагин успешно отобразит корректные строки; но это может быть несколько неправильно — писать "перевод" в POT файле (поскольку это PO Template, то есть шаблон), и в этом случае вы можете предпочесть указать false для potAsDefault, тогда отдельный PO файл будет сгенерирован для языка по умолчанию, а POT файл можно будет оставить чистым. Если potAsDefault - nil, то это то же, что он равен true.

Если вы используете плагин i18n вместе с другими плагинами, которые меняют пути страниц (поле path), тогда i18n.localize должен быть вызван до узлов других плагинов, чтобы не потерять суффиксы с кодами языков.
i18n.writeTranslations()

Этот узел записывает все файлы для перевода в директорию po. PO-файл будет сгенерирован для каждого языка, который плагин обнаружит, так что вам не нужно редактировать LINGUAS и/или создавать PO-файлы самостоятельно. Этот узел следует вызывать после применения шаблонов и других преобразований, которые вызывают фукнции перевода строк, чтобы плагин собрал все необходимые строки.

Также ещё пока что есть i18n.setLang(path, lang) как замена отсутствующему функционалу, чтобы установить язык и прочие вещи для страниц, сгенерированных в пайплайне (то есть не из папки content). Этот узел скорее всего будет удалён в будущем.

Использование в шаблонах

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

<% if .nlangs > 1 then -%>
<div><%= _'Languages' .. ':' -%>
<%  for lang, path in iterLangs() do
    if l == lang then -%>
    <b><%= getLangName(l) %></b>
    <% else -%>
    <a href="<%= p %>"><%= getLangName(l) %></a>
    <% end -%>
<%  end -%>
</div>
<% end -%>

nlangs — счётчик количества языков, на которых страница доступна. Для этой страницы непосредственно nlangs равен 2. Значение поля задаётся автоматически, не редактируйте его самостоятельно.

_'Languages' — строка для перевода. Если вы когда-нибудь писали код с использованием Gettext, то вам могут быть знакомы функции _(...), _p(...), _n(...) and _np(...) — это функции для перевода строк, со слегка отличающимися опциями, но главная задача у них одна: строка будет заменена на перевод из каталога сообщений для текущего языка (или оригинальная строка будет возвращена, если перевода нет). Посмотрите на демонастрционный скрипт Lettext для изучения детального использования этих фукнций.

Если посмотреть в файле ru.po среди исходников этого сайта, можно найти перевод для указанной строки:

msgid "Languages"
msgstr "Языки"

iterLangs() перебирает языки страницы, возвращая код языка и путь к странице на другом языке. Итератор также выдаст текущую страницу, что можно обнаружить, сравнив возвращённый код языка с кодом текущей страницы (lang).

getLangName(lang) возвращает название языка для предоставленного кода. На данный момент функция возвращает название на английском, но это изменится в будущем. Так что сейчас функция возвращает "English" для en и "Russian" для ru независимо от языка текущей страницы.

А теперь, ещё одна вещь, которую можно использовать в шаблонах:

getLangRoot() возвращает путь к корневой директории языка текущей страницы.

Планируемые изменения

Добавление функции для получения даты и времени в локализованном формате;
Добавление опции для создания поддиректории для языка по умолчанию (чтобы можно было сделать выбор языков на странице index.html, а всё остальное поместить в поддиректории, подобно тому, что делает Википедия, с той разницей, что Википедия использует поддомены, а не поддиректории);
getLangName будет возвращать локализованные названия языков;
Добавление простого способа создания локализованных индексных и других сгенерированных в пайплайне страниц.

Localization

2026-09-18T00:00:00.000Z

i18n plugin for Luasmith provides tools to create multi-language websites. It uses Lettext, a Gettext implementation for Lua, allowing you to translate strings in your website templates utilizing a commonly used PO file format. The plugin automatically extracts strings and generates PO(T) files when building the website, so you don't have to have standard Gettext utilities (such as xgettext and msgmerge) being installed — everything is handled by Lettext and the plugin to simplify creation of multi-language websites.

The plugin is unfinished. While the core things are complete, there are still some important missing parts. Breaking changes are expected.

Content structure

You can use either lang field in front-matter or add a filename suffix to set the language of a page. A suffix is useful when you want some pages to be translations to each other, and the plugin will be aware of that, so you will be able to create a language switcher (like you can see one on the top of this page).

Assuming we have this content directory structure:

content/
 | index.md
 | index.ru.md
 | some_page.md

With some_page.md having lang = ru, this structure will be produced on output:

out/
 | index.html
 | ru/
    | index.html
    | some_page.md

Changing the links in the content of pages is done by the plugin, so you should write relative links' paths as they are in your content folder and there's no need to be bothered of the fact that the path to root will change.

Pipeline

There are just 2 things that you need to call in your pipeline for your content to be localized.

i18n.localize(defaultLang, potAsDefault)

This node walks over all items, changing their paths and relative links in the content as needed; it will also set required plugin-specific item fields.

defaultLang is the language code for the default language of your website. Pages without lang field set and with no language code in file suffix are assumed to be pages in the default language. If defaultLang is nil, it will be set to en.

potAsDefault defines whether the generated messages.pot file should be used as a fallback for strings translations for the default language. If the default language has multiple plural forms, it may be insufficient to use only msgid and msgid_plural to provide proper strings; if potAsDefault is true, you can add msgstr in the POT file to workaround that and the plugin will read proper strings, but that may not feel right to write "translations" into the POT file (which is the PO Template file), in such case you may want to set potAsDefault to false and then a separate PO file for your default language will be generated, allowing you to keep the POT file clean. If potAsDefault is nil, it will be set to true.

If you use i18n plugin together with some other plugins that modify items' paths (such as anyslug or prettyurls) then i18n.localize must be called before other plugins' nodes to avoid losing filename suffixes with language codes.
i18n.writeTranslations()

This node writes all translation files into po directory. A PO file will be generated for each language that the plugin will encounter, so that you don't need to edit LINGUAS and/or create PO files yourself. This node should be called after applying all your template and doing other stuff that calls translation functions so that all strings will be collected.

There's also i18n.setLang(path, lang) currently available as a workaround for missing functionality to set the language and add some extra stuff to pipeline-generated pages (i.e. not generated from content files). This node will most likely be removed in the future.

Usage in templates

Most of the functionality of the plugin for templates can be inspected in the code of the language switcher on this page:

<% if nlangs > 1 then -%>
<div><%= _'Languages' .. ':' -%>
<%  for l, p in iterLangs() do
    if l == lang then -%>
    <b><%= getLangName(l) %></b>
    <% else -%>
    <a href="<%= p %>"><%= getLangName(l) %></a>
    <% end -%>
<%  end -%>
</div>
<% end -%>

nlangs is the count of languages the page is available in. This page in pacticular has nlangs being 2. The field is set automatically, don't overwrite it yourself.

_'Languages' is a translatable string. If you have ever written a code using Gettext, then you may be familiar with _(...), _p(...), _n(...) and _np(...) — these are translation function with slightly different options, but the main thing is the same: a string will be replaced by its translation from a messages catalog for the current language (or the original string is returned if there's no translation). See Lettext demo for detailed usage examples of these functions.

If you will look at messages.pot file in the source code of this website, an entry with the string is there:

msgid "Languages"
msgstr ""

iterLangs() iterates over all languages for the page, returning a language code and a path to the page in another language. The iterator will go over the current page itself, this can be detected by comparing returned language code with the language code of the current page (lang).

getLangName(lang) returns the name of the language for the provided code. Currently it returns the name in English, but this will change in the future. So, now it returns "English" for en and "Russian" for ru no matter what the current page's language is.

Now, one more thing that you can use in templates:

getLangRoot() returns a path to the language root directory for the current page.

Planned features

A function to get date and time in localized format;
An option to create subdirectory for the default language (so you can have a language selection page on index.html and everything else will be in subdirectories, similar to what Wikipedia does, except it does it on subdomains, not subdirectories);
getLangName returning localized language names;
An easy way to create localized indexes and other pipeline-generated pages.

Non-ASCII paths sluggification

2026-09-11T00:00:00.000Z

This page is created from a file called "Не АСКИ файл.md" ("non-ASCII file" in Russian), but as you can see the URL contains "ne-aski-fayl" instead.

Заголовок с эмодзи 🥸

And the heading above also has properly sluggified ID in the generated HTML code:

<h3 id="zagolovok-s-emodzi-disguised_face">...</h3>

These things are possible thanks to the anyslug plugin.

How to use

Use the module and its 2 nodes for your pipeline:

anyslug = require("anyslug")

...

return {
    ...
    anyslug.sluggifyPaths(),
    ...
    anyslug.sluggifyLinks(),
    ...
}

When you require the module it uses a little hack to inject the implementation of sluggify function provided by the module into Luasmith, that's how headings' IDs with non-ASCII characters also get sluggified properly.

sluggifyPaths

This node walks over all items and sluggifies their paths. It should be executed before any other nodes that collects items' paths (like aggregate).

If you use anyslug together with i18n module, then i18n.localize must be used before anyslug.sluggifyPaths, otherwise pages' language suffixes will be malformed.
sluggifyLinks

This node sluggifies all links in items' content. It should be used closer to the end of your pipeline, after applying templates and doing other stuff that changes content.

Pandoc plugin

2026-09-02T00:00:00.000Z

This page was written in LibreOffice Writer and saved in ODT format. 😵‍💫 Sounds like a 1st April joke, but it’s just to demonstrate possibilities of Pandoc plugin for Luasmith!

How to use

Use the module:

pandoc = require("pandoc")

And then add a node to your pipeline:

pandoc.processPandoc(pattern, options, contentSource)

All arguments are optional.

pattern is a filter that defines what files will be processed (default: %.md$);
options is a string with additional arguments that will be passed to Pandoc command-line (you don’t need to specify -t html here, this will be passed anyway);
contentSource is your content directory (if not provided, the plugin will fall back to source global variable or args[3] global variable if available, otherwise it will fall back to "content" directory)

A formatting that will be exported to HTML completely depends on how Pandoc parses your document, so refer to Pandoc documentation (this page in particular has a very limited formatting because I didn’t bother to write custom filters or find another way, if it exists, to enrich ODT export; yet relative links work as expected).

Since it’s possible to add arguments to command-line, you can also use Lua filters for Pandoc (or simply modify luasmith-pandoc-filter.lua that comes along with the plugin and gets passed to Pandoc automatically).

Take a note that calling Pandoc as an external program for each page leads to a SEVERE increase of build time for your site compared to using built-in Markdown parser of Luasmith; it’s not the best idea to pass all your Markdown content to Pandoc if it can be processed using the built-in parser. For example, compiling Jared Krinke’s blog with built-in blog theme takes less than 500ms, but when using modified theme with Pandoc processing — almost 15 seconds!

For documents that can’t have metadata in a front-matter (like .odt files), you can write a separate metadata file and it will be automatically passed to Pandoc. This file must have the same name as your document but with .yaml extension (for example, this page is generated from pandoc.odt and pandoc.yaml with metadata next to it). If metadata file is not found, the plugin will try to read metadata from the document. In both cases metadata will be parsed by built-in Luasmith front-matter parser that has limited YAML support for now. Used metadata files will automatically be removed from Luasmith items list, so they won’t appear in your website.

Markdown syntax guide

2026-08-31T00:00:00.000Z

This article offers a sample of basic Markdown syntax that can be used in Luasmith content files. This sample is based on “Markdown syntax guide” that is often seen on sites demonstrating themes for Hugo, another static site generator, but the content of the page was adapted for Luasmith that uses different Markdown parser.

Headings

The following HTML <h1>—<h6> elements represent six levels of section headings. <h1> is the highest section level while <h6> is the lowest.

H1

H2

H3

H4

H5

H6

Paragraph

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

Blockquotes

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

It's more important to receive, sometimes, that good people that I recognize that like the result, than a lot of people that I have no idea what they are, who they are etc.
— Roberto Ierusalimschy, creator of Lua¹

Tables

Tables aren't part of the core Markdown spec, but Luasmith supports them out-of-the-box.

Italics	Bold	Code
italics	bold	`code`

Code Blocks

Code block with backticks

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block indented with four spaces

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

List Types

Ordered List

First item
Second item
Third item

Unordered List

List item
Another item
And another item

Nested list

Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese

Other Elements — abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL+ALT+Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

The above quote is from Ryan Peterman's interview with Roberto Ierusalimschy, August 3, 2026.↩