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.
VERY IMPORTANT: There always needs to be a blank line between the metadata and the rest of the template, even when there is no metadata. A template with no metadata needs a blank line at the top. I could probably change that, but I don't feel like it at the moment. Fight me!
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)
If a link starts with "=", the HTML5 "download" attribute is added to the link so the file is downloaded directly in browsers that support it. This is a hack.
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:
- directory to take books from
- mode
- attribute(s) to sort by
Purpose:
Generate sorted list of all pages in the given directory, first by the given attribute(s), which can be anything in the metadata, then by the titles. The mode argument can be used to either just list all books ("list"), list all books with subheadings for the different sorting attributes ("combined"), or generate different pages for the different values of the sorting attributes. Note that the display names for the attributes need to be defined in the configuration file config.ini. For instance, if a page contains metadata "category:stuff", config.ini must contain a section "[category:$lang]" for each language that contains a line "stuff=Display Name".
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.
The modified_dates behavior is buggy - pages should have proper dependency resolution so that pages which call other functions are still updated if the pages they require are modified but the page itself isn't. For instance, if one page has a list of books that is automatically generated, it won't be updated if the books change because the generator doesn't know that this page actually depends on all other pages. As a small workaround, there is now the always_update metadata, so if always_update:true is specified in the metadata, that page will always be updated.
Text::Markdown
Written in 2017-2023 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/>.