lsg.pl - Multilingual static site generator
lsg.pl [directory]
directory specifies the directory of the source files for the site and defaults the the current directory.
lsg.pl is a simple static site generator that is meant to simplify creating multilingual sites.
This documentation is very rudimentary at the moment and the whole generator should really be rewritten at some point anyways. Contact me if you need help deciphering the meaning of the words written here.
Do note that the code constituting this piece of software is not something to be proud of.
The configuration for the site, see "CONFIGURATION".
A list of the timestamps of the source files for the site pages, in order to check which ones need to be regenerated (this is automatically generated)
The directory containing the source files for the site pages.
The directory containing the templates for the pages.
The generated html pages.
The directory containing static files such as images.
The configuration file uses the INI format. There are currently only a few options:
Specifies the languages and their display names, e.g. "en=English".
Specifies the directions of the scripts the languages are written in (ltr or rtl). This is currently not used anywhere (I think?) but may come in handy someday.
This is outside the INI sections and just specifies the files that are supposed to be in the navigation menu, separated by colons.
See the example site for more information.
The templates are simply html files with certain extra syntax parsed by the site generator. Note that backslashes need to be escaped.
Inserts the variable "title" set in the metadata of the page.
Starts a block named "block_name" which can be overwritten in child templates. The block named "content" is filled with the actual content from the page after it is converted to HTML.
Executes one of the functions from LSG::UserFuncs with the given arguments. Note that the function is executed separately for every page that is generated and can thus be used, for example, to generate relative links to a CSS file.
At the very top of a template file, optional metadata can be specified:
Used to inherit from a parent template.
Specifies the required metadata that needs to be specified in each page using this template.
See the example site for details. This really isn't very polished, but I'm just trying to document it somewhat reasonably since I probably won't have time to properly rewrite it for a while.
The pages directory contains the directory structure as it will be on the website, except that the pages are named "path/to/page.lang", which is changed to "lang/path/to/page.html" on the final website.
Each page file contains metadata at the top. The minimum required metadata is "template" and "lang", since the template can then specify what metadata is required. "lang" should actually be redundant, but I don't have time to look into why I kept it that way right now...
When a template named "article" is specified, the actual template that is loaded is "templates/article.lang.html", so a template needs to exist for every language.
After the metadata, the rest of the file is the content, written in Markdown. All normal Markdown is supported since this just uses Text::Markdown for the parsing. There are some extra features, though. The special link syntax specified below is meant to provide some convenience and allows the site generator to check if the linked files actually exist on the server. The generated links are relative, so the site can also be browsed locally. Link titles, alt text for images, and reference-style links are not supported by this special format, however.
(note that this was copied out of an old README and not formatted very well for this documentation page)
Links:
[Whatever](@.pdf)-> [Whatever](relative/path/to/static/$name_of_page.pdf)
[Whatever](#bob.pdf) -> [Whatever](relative/path/to/static/bob.pdf)
[Whatever]($page.en) -> [Whatever](relative/path/to/en/page.html)
Images:
-> [Whatever](relative/path/to/static/$name_of_page.png)
 -> [Whatever](relative/path/to/static/bob.png)
Functions:
Functions can be used for more advanced features. They are written using Perl in the file LSG/UserFuncs.pm and can be called from a markdown file as follows:
{name_of_function}(argument1 argument2 argument3)
Note: this format may change in the future if more advanced arguments are needed.
sort_books
Parameters:
- attribute to sort by
- create heading when attribute changes or not
Purpose:
Generate sorted list of all books, first by the given attribute, which can be anything in the metadata, then by the titles. The second attribute can be used to create, for instance, category titles. This does not make sense though when the attribute is just the title which changes every time anyways. If the second argument is left out, it defaults to "false". The attribute to be sorted by (obviously) needs to be defined for each book.
Example:
{sort_books}(category false)
This function was created for a book site, but it could probably be used for articles as well.
Two more functions, gen_nav and gen_lang_selector, are defined, but they are currently only used internally in the templates and probably aren't needed for the actual pages.
Text::Markdown
Written in 2017-2020 by lumidify <nobody[at]lumidify.org>
To the extent possible under law, the author has dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.
You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.