- a static site: easy to deploy, less security problems,
- handling of blog posts, with dates, topics, keywords and associated RSS feeds,
- dynamic comments for blog posts (⇒ using Disqus),
- no new syntax,
- using custom tags (e.g. section) to provide semantics in code,
- avoid code duplication,
- ability to use all HTML5 or any XML,
- check internal references,
- displaying evaluated OCaml code,
- support for multiple languages (fr, en, ..),
- ability to add specific features with plugins.
Three steps:
- Read configuration file .stog/config and directory tree:
- Handle "elements",
- Copy other files, i.e. files not ignored and not elements.
Example: file doc.html from Stog's web site:
Example: file posts/release-0.7.0.html from Stog's web site:
Templates are regular XML documents, with some XML nodes which will be rewritten.
Templates are in the .stog/templates/ directory.
A template can be used in three ways:
- according to an element type, this type being the root node tag of the element:
...
...
page will result in using the .stog/template/page.tmpl file has template
for the element (and post.tmpl for post element).
- referenced in the file attribute of a ]]> node,
- used by other rewrite rules.
The template file .stog/templates/page.tmpl:
The template file .stog/templates/elt-in-list.tmpl:
An environment is a map associating tag names to rules. We note \Gamma(t) = f
to say that a function f is associated to the tag t in the environment \Gamma.
If no function is associated to t, then \Gamma(t) = \bot.
A rule is a function $f$ taking in parameters: an environment $\Gamma$, a list
of XML node attributes $l_a$, a list of XML (sub)nodes $l_{xml}$.
A rule, when applied, returns a list of XML nodes.
Let \mathcal{R}(\Gamma, n) be the function applying an environment \Gamma
to an XML node n = (t, l_a, l_{xml}). \mathcal{R}_l(\Gamma, l) applies \mathcal{R}(\Gamma, x)
on each element x of the list l.
The algorithm of \mathcal{R} is the following:
- Apply \mathcal{R} on each attribute value, parsed as valid XML, to get a new list
of rewritten attributes l_a',
-
If \Gamma(t) = \bot, then return [(t, l_a', \mathcal{R}_l(Gamma, l_{xml}))].
Else, with \Gamma(t) = f, return f(\Gamma, l_a', l_{xml}).
\mathcal{R} is called until a fixpoint is reached.
This rewrite engine is implemented in the Xtmpl library.
When we define an element, we're defining an environment \Gamma.
Example: consider the following element:
This is the body of my page
Here we defined an environment \Gamma with the following rules:
- \Gamma("elt-title") = f_1 with f_1(\_,\_,\_) = [ "Example page" ]
- \Gamma("author") = f_2 with f_2(\_,\_,\_) = [ "Maxence Guesdon" ]
- \Gamma("elt-body") = f_3 with f_3(\_,\_,\_) = [ "This is the body of the page" ]
To compute the element's final XML, we apply this environment to the template
associated to the page type.
Remarks:
- Of source, the initial environment is not empty. So defining an element adds rules to this initial
environment.
-
Predefined rules and user-defined rules can be more complex.
One of the element must be marked has "main", with a main="true" attribute.
This is usually the top index.html file but this is not mandatory.
The main element is the place to define rules for the initial environment. These rules are defined using
the stog: prefix (like an XML namespace). Defining stog:foo="bar" will
make this rule appear in the initial environment with the name "foo".
....
]]>