tAdd documentation and sample site - lsg - Lumidify Site Generator
HTML git clone git://lumidify.org/git/lsg.git
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
DIR commit f7226a7a6056d9351b8f68afd552671ec63cc6a6
DIR parent dd72bfc439147c379355cef947aa3aab9e13eb8f
HTML 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(-)
---
DIR diff --git a/README b/README
t@@ -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
DIR diff --git a/lsg.pl b/lsg.pl
t@@ -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
DIR diff --git a/sample/config.ini b/sample/config.ini
t@@ -0,0 +1,9 @@
+[langs]
+en=English
+de=Deutsch
+
+[lang_dirs]
+en=ltr
+de=ltr
+
+nav=index:about:contact
DIR diff --git a/sample/modified_dates b/sample/modified_dates
t@@ -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
DIR diff --git a/sample/pages/about.de b/sample/pages/about.de
t@@ -0,0 +1,7 @@
+title:Über
+template:article
+lang:de
+
+### Diese Webseite
+
+Dies ist eine tolle Webseite.
DIR diff --git a/sample/pages/about.en b/sample/pages/about.en
t@@ -0,0 +1,7 @@
+title:About
+template:article
+lang:en
+
+### This Website
+
+This is a great website.
DIR diff --git a/sample/pages/contact.de b/sample/pages/contact.de
t@@ -0,0 +1,7 @@
+title:Kontakt
+template:base
+lang:de
+
+### Kontakt
+
+Email: [nobody@example.org](mailto:nobody@example.org)
DIR diff --git a/sample/pages/contact.en b/sample/pages/contact.en
t@@ -0,0 +1,7 @@
+title:Contact
+template:base
+lang:en
+
+### Contact
+
+Email: [nobody@example.org](mailto:nobody@example.org)
DIR diff --git a/sample/pages/index.de b/sample/pages/index.de
t@@ -0,0 +1,8 @@
+title:Home
+template:base
+lang:de
+
+# Tolle Webseite
+
+
+Siehe [Über]($about.de) für mehr Information.
DIR diff --git a/sample/pages/index.en b/sample/pages/index.en
t@@ -0,0 +1,8 @@
+title:Home
+template:base
+lang:en
+
+# Great Website
+
+
+See [About]($about.en) for more information.
DIR diff --git a/sample/site/de/about.html b/sample/site/de/about.html
t@@ -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>
DIR diff --git a/sample/site/de/contact.html b/sample/site/de/contact.html
t@@ -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>
DIR diff --git a/sample/site/de/index.html b/sample/site/de/index.html
t@@ -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>
DIR diff --git a/sample/site/en/about.html b/sample/site/en/about.html
t@@ -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>
DIR diff --git a/sample/site/en/contact.html b/sample/site/en/contact.html
t@@ -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>
DIR diff --git a/sample/site/en/index.html b/sample/site/en/index.html
t@@ -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>
DIR diff --git a/sample/site/static/logo.png b/sample/site/static/logo.png
Binary files differ.
DIR diff --git a/sample/site/static/main.css b/sample/site/static/main.css
t@@ -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;
+}
DIR diff --git a/sample/templates/article.de.html b/sample/templates/article.de.html
t@@ -0,0 +1,4 @@
+extends:base.de.html
+metadata:title
+
+{block extra_css}<style>#content p \{max-width: 350pt;}</style>{endblock}
DIR diff --git a/sample/templates/article.en.html b/sample/templates/article.en.html
t@@ -0,0 +1,4 @@
+extends:base.en.html
+metadata:title
+
+{block extra_css}<style>#content p \{max-width: 350pt;}</style>{endblock}
DIR diff --git a/sample/templates/base.de.html b/sample/templates/base.de.html
t@@ -0,0 +1,4 @@
+extends:base.html
+metadata:title
+
+{block site_name}Meine Seite{endblock}
DIR diff --git a/sample/templates/base.en.html b/sample/templates/base.en.html
t@@ -0,0 +1,4 @@
+extends:base.html
+metadata:title
+
+{block site_name}My Site{endblock}
DIR diff --git a/sample/templates/base.html b/sample/templates/base.html
t@@ -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>