commit f7226a7a6056d9351b8f68afd552671ec63cc6a6 parent dd72bfc439147c379355cef947aa3aab9e13eb8f Author: lumidify <nobody@lumidify.org> Date: Thu, 26 Mar 2020 19:38:53 +0100 Add documentation and sample site Diffstat:
| M | README | | | 46 | ++-------------------------------------------- |
| M | lsg.pl | | | 229 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | sample/config.ini | | | 9 | +++++++++ |
| A | sample/modified_dates | | | 11 | +++++++++++ |
| A | sample/pages/about.de | | | 7 | +++++++ |
| A | sample/pages/about.en | | | 7 | +++++++ |
| A | sample/pages/contact.de | | | 7 | +++++++ |
| A | sample/pages/contact.en | | | 7 | +++++++ |
| A | sample/pages/index.de | | | 8 | ++++++++ |
| A | sample/pages/index.en | | | 8 | ++++++++ |
| A | sample/site/de/about.html | | | 33 | +++++++++++++++++++++++++++++++++ |
| A | sample/site/de/contact.html | | | 33 | +++++++++++++++++++++++++++++++++ |
| A | sample/site/de/index.html | | | 35 | +++++++++++++++++++++++++++++++++++ |
| A | sample/site/en/about.html | | | 33 | +++++++++++++++++++++++++++++++++ |
| A | sample/site/en/contact.html | | | 33 | +++++++++++++++++++++++++++++++++ |
| A | sample/site/en/index.html | | | 35 | +++++++++++++++++++++++++++++++++++ |
| A | sample/site/static/logo.png | | | 0 | |
| A | sample/site/static/main.css | | | 65 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | sample/templates/article.de.html | | | 4 | ++++ |
| A | sample/templates/article.en.html | | | 4 | ++++ |
| A | sample/templates/base.de.html | | | 4 | ++++ |
| A | sample/templates/base.en.html | | | 4 | ++++ |
| A | sample/templates/base.html | | | 26 | ++++++++++++++++++++++++++ |
23 files changed, 604 insertions(+), 44 deletions(-)
diff --git a/README b/README @@ -1,45 +1,3 @@ -Almost all standard markdown features (https://daringfireball.net/projects/markdown/syntax) -should be supported since the markdown is just passed to the standard markdown parser after -being preprocessed to make things easier to write. +See the perldoc in lsg.pl for documentation (run perldoc -F lsg.pl). -Notable changes: -- Link titles and alt text for images is not supported in links that need to be preprocessed, - e.g. [Hi](@example.com "Title") -- Reference-style links are not parsed by the preprocessor - -Special simplifications handled by the preprocessor: - -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. - -Currently implemented functions: - -`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) - -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. +Requirements: Text::Markdown diff --git a/lsg.pl b/lsg.pl @@ -26,3 +26,232 @@ use LSG; my $path = $#ARGV >= 0 ? $ARGV[0] : "."; LSG::init($path); LSG::generate_site(); + +__END__ + +=head1 NAME + +lsg.pl - Multilingual static site generator + +=head1 SYNOPSIS + +B<lsg.pl> [directory] + +=head1 OPTIONS + +B<directory> specifies the directory of the source files for the site and +defaults the the current directory. + +=head1 DESCRIPTION + +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. + +=head1 FILES + +=over 8 + +=item B<config.ini> + +The configuration for the site, see L</"CONFIGURATION">. + +=item B<modified_dates> + +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) + +=item B<pages> + +The directory containing the source files for the site pages. + +=item B<templates> + +The directory containing the templates for the pages. + +=item B<site> + +The generated html pages. + +=item B<site/static> + +The directory containing static files such as images. + +=back + +=head1 CONFIGURATION + +The configuration file uses the INI format. There are currently only a few +options: + +=over 8 + +=item B<langs> + +Specifies the languages and their display names, e.g. "en=English". + +=item B<lang_dirs> + +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. + +=item B<nav> + +This is outside the INI sections and just specifies the files that +are supposed to be in the navigation menu, separated by colons. + +=back + +See the example site for more information. + +=head1 TEMPLATES + +The templates are simply html files with certain extra syntax +parsed by the site generator. Note that backslashes need to be +escaped. + +=over 8 + +=item B<{var title}> + +Inserts the variable "title" set in the metadata of the page. + +=item B<{block block_name}> + +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. + +=item B<{func func_name}> + +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. + +=back + +At the very top of a template file, optional metadata can be +specified: + +=over 8 + +=item B<extends> + +Used to inherit from a parent template. + +=item B<metadata> + +Specifies the required metadata that needs to be specified in +each page using this template. + +=back + +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. + +=head1 PAGES + +The C<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) + +B<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) + +B<Images:> + +-> [Whatever](relative/path/to/static/$name_of_page.png) + + -> [Whatever](relative/path/to/static/bob.png) + +B<Functions:> + +Functions can be used for more advanced features. They are written using Perl in the file +C<LSG/UserFuncs.pm> and can be called from a markdown file as follows: + +C<{name_of_function}(argument1 argument2 argument3)> + +Note: this format may change in the future if more advanced arguments are needed. + +B<sort_books> + +B<Parameters:> + +- attribute to sort by + +- create heading when attribute changes or not + +B<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. + +B<Example:> + +C<{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, C<gen_nav> and C<gen_lang_selector>, are defined, but they are +currently only used internally in the templates and probably aren't needed for the +actual pages. + +=head1 SEE ALSO + +Text::Markdown + +=head1 LICENSE + +Written in 2018-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/>. + +=cut diff --git a/sample/config.ini b/sample/config.ini @@ -0,0 +1,9 @@ +[langs] +en=English +de=Deutsch + +[lang_dirs] +en=ltr +de=ltr + +nav=index:about:contact diff --git a/sample/modified_dates b/sample/modified_dates @@ -0,0 +1,11 @@ +1585245652 pages/about.en +1585245772 pages/about.de +1585247247 pages/contact.en +1585247237 pages/contact.de +1585247176 pages/index.en +1585247181 pages/index.de +1585245402 templates/article.de.html +1585245382 templates/base.en.html +1585245382 templates/article.en.html +1585245386 templates/base.de.html +1585244985 templates/base.html diff --git a/sample/pages/about.de b/sample/pages/about.de @@ -0,0 +1,7 @@ +title:Über +template:article +lang:de + +### Diese Webseite + +Dies ist eine tolle Webseite. diff --git a/sample/pages/about.en b/sample/pages/about.en @@ -0,0 +1,7 @@ +title:About +template:article +lang:en + +### This Website + +This is a great website. diff --git a/sample/pages/contact.de b/sample/pages/contact.de @@ -0,0 +1,7 @@ +title:Kontakt +template:base +lang:de + +### Kontakt + +Email: [nobody@example.org](mailto:nobody@example.org) diff --git a/sample/pages/contact.en b/sample/pages/contact.en @@ -0,0 +1,7 @@ +title:Contact +template:base +lang:en + +### Contact + +Email: [nobody@example.org](mailto:nobody@example.org) diff --git a/sample/pages/index.de b/sample/pages/index.de @@ -0,0 +1,8 @@ +title:Home +template:base +lang:de + +# Tolle Webseite + + +Siehe [Über]($about.de) für mehr Information. diff --git a/sample/pages/index.en b/sample/pages/index.en @@ -0,0 +1,8 @@ +title:Home +template:base +lang:en + +# Great Website + + +See [About]($about.en) for more information. diff --git a/sample/site/de/about.html b/sample/site/de/about.html @@ -0,0 +1,33 @@ +<html> +<head> +<title>Über | Meine Seite</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> +<style>#content p {max-width: 350pt;}</style> +</head> +<body> +<div id="header"> +<h1 id="title">Meine Seite</h1> +<div id="lang"> +<ul> +<li><a href="../en/about.html">English</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">Über</a></li> +<li><a href="contact.html">Kontakt</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h3>Diese Webseite</h3> + +<p>Dies ist eine tolle Webseite.</p> + +</div> +</body> +</html> diff --git a/sample/site/de/contact.html b/sample/site/de/contact.html @@ -0,0 +1,33 @@ +<html> +<head> +<title>Kontakt | Meine Seite</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> + +</head> +<body> +<div id="header"> +<h1 id="title">Meine Seite</h1> +<div id="lang"> +<ul> +<li><a href="../en/contact.html">English</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">Über</a></li> +<li><a href="contact.html">Kontakt</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h3>Kontakt</h3> + +<p>Email: <a href="mailto:nobody@example.org">nobody@example.org</a></p> + +</div> +</body> +</html> diff --git a/sample/site/de/index.html b/sample/site/de/index.html @@ -0,0 +1,35 @@ +<html> +<head> +<title>Home | Meine Seite</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> + +</head> +<body> +<div id="header"> +<h1 id="title">Meine Seite</h1> +<div id="lang"> +<ul> +<li><a href="../en/index.html">English</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">Über</a></li> +<li><a href="contact.html">Kontakt</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h1>Tolle Webseite</h1> + +<p><img src="../static/logo.png" alt="Bestes logo je" /></p> + +<p>Siehe <a href="about.html">Über</a> für mehr Information.</p> + +</div> +</body> +</html> diff --git a/sample/site/en/about.html b/sample/site/en/about.html @@ -0,0 +1,33 @@ +<html> +<head> +<title>About | My Site</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> +<style>#content p {max-width: 350pt;}</style> +</head> +<body> +<div id="header"> +<h1 id="title">My Site</h1> +<div id="lang"> +<ul> +<li><a href="../de/about.html">Deutsch</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">About</a></li> +<li><a href="contact.html">Contact</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h3>This Website</h3> + +<p>This is a great website.</p> + +</div> +</body> +</html> diff --git a/sample/site/en/contact.html b/sample/site/en/contact.html @@ -0,0 +1,33 @@ +<html> +<head> +<title>Contact | My Site</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> + +</head> +<body> +<div id="header"> +<h1 id="title">My Site</h1> +<div id="lang"> +<ul> +<li><a href="../de/contact.html">Deutsch</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">About</a></li> +<li><a href="contact.html">Contact</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h3>Contact</h3> + +<p>Email: <a href="mailto:nobody@example.org">nobody@example.org</a></p> + +</div> +</body> +</html> diff --git a/sample/site/en/index.html b/sample/site/en/index.html @@ -0,0 +1,35 @@ +<html> +<head> +<title>Home | My Site</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="../static/main.css"> + +</head> +<body> +<div id="header"> +<h1 id="title">My Site</h1> +<div id="lang"> +<ul> +<li><a href="../de/index.html">Deutsch</a></li> +</ul> +</div> +<div id="nav"> +<ul> +<li><a href="index.html">Home</a></li> +<li><a href="about.html">About</a></li> +<li><a href="contact.html">Contact</a></li> + +</ul> +</div> +</div> +<div id="content"> +<h1>Great Website</h1> + +<p><img src="../static/logo.png" alt="Best logo ever" /></p> + +<p>See <a href="about.html">About</a> for more information.</p> + +</div> +</body> +</html> diff --git a/sample/site/static/logo.png b/sample/site/static/logo.png Binary files differ. diff --git a/sample/site/static/main.css b/sample/site/static/main.css @@ -0,0 +1,65 @@ +body { + font-family: verdana, sans; + margin: 0; +} + +#header { + background: #4177bd; + color: #474747; + text-align: center; +} + +#header #title { + padding: 5pt; + margin-top: 0; + margin-bottom: 0; + font-size: 3em; +} + +#header a { + color: #ffffff; + text-decoration: none; +} + +#header ul { + display: inline; + list-style: none; + padding: 0; +} + +#header ul li { + display: inline-block; + padding: 10pt; +} + +#header #nav { + background: #474747; +} + +#header #nav a:hover { + color: #4177bd; +} + +#header #lang { + text-align: left; +} + +#header #lang a:hover { + color: #000000; +} + +#content { + padding-left: 5%; + padding-right: 5%; + padding-top: 10px; + padding-bottom: 50px; +} + +#content .column { + max-width: 400pt; +} + +#page_list { + list-style: none; + padding: 0; +} diff --git a/sample/templates/article.de.html b/sample/templates/article.de.html @@ -0,0 +1,4 @@ +extends:base.de.html +metadata:title + +{block extra_css}<style>#content p \{max-width: 350pt;}</style>{endblock} diff --git a/sample/templates/article.en.html b/sample/templates/article.en.html @@ -0,0 +1,4 @@ +extends:base.en.html +metadata:title + +{block extra_css}<style>#content p \{max-width: 350pt;}</style>{endblock} diff --git a/sample/templates/base.de.html b/sample/templates/base.de.html @@ -0,0 +1,4 @@ +extends:base.html +metadata:title + +{block site_name}Meine Seite{endblock} diff --git a/sample/templates/base.en.html b/sample/templates/base.en.html @@ -0,0 +1,4 @@ +extends:base.html +metadata:title + +{block site_name}My Site{endblock} diff --git a/sample/templates/base.html b/sample/templates/base.html @@ -0,0 +1,26 @@ +<!DOCTYPE html> +<html> +<head> +<title>{var title} | {block site_name}{endblock}</title> +<meta charset="UTF-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<link rel="stylesheet" href="{func gen_relative_link static/main.css}"> +{block extra_css}{endblock} +</head> +<body> +<div id="header"> +<h1 id="title">{block site_name}{endblock}</h1> +<div id="lang"> +{func gen_lang_selector} +</div> +<div id="nav"> +<ul> +{block site_nav}{func gen_nav}{endblock} +</ul> +</div> +</div> +<div id="content"> +{block content}{content}{endblock} +</div> +</body> +</html>
