Tutorial
You should model your site project similar to this:
.
`-- content
| |-- index.md
| |-- other.md
`-- config
| |-- other.json
| |-- _master.json
`-- static
| |-- my.css
`-- template
| |-- _default.st
| |-- other.st
The content folder has all page content in Markdown format, config folder has configuration in JSON format, there is a _master.json in the config folder having the master configuration. static folder has all the static content like CSS, JS and images. template folder the StringTemplate files. There is a default template named _default.st.
The order of processing of StaGen engine:
- Load the master configuration
config/_master.json. - Copy static resources to destination folder (a folder named
targetis created). - For each Markdown file in the
contentfolder (content in sub-folders are ignored), do:- Load corresponding configuration (read next section on Loading Configuration).
- Apply the configuration on the corresponding template and write the resulting HTML file to destination folder.
Configuration is of type JSON map:
{
"title": "My Site Title",
"activities": ["Dance", "Jump", "Shout"]
}
Note that the key has always to be a string, the value can be any type.
The master configuration is named config/_master.json. This is loaded by the StaGen engine at the beginning. When processing each content, say, index.md, StaGen tries to load the corresponding configuration from config/index.json folder. The specific config is overlayed above the master config for this instance. Meaning, if you have defined title in config/_master.json and config/index.json, when rendering index.md, the title from config/index.json will be used. If config/index.json is not available, StaGen does not complain.
StaGen uses StringTemplate. A simple template that uses the JSON configuration listed above:
<html>
...
<title>$title$</title>
...
<ol>
$activities: {activity|
<li>$activity$</li>
}$
</ol>
...
$_content$
...
</html>
$_content$ is the Markdown content rendered as HTML that is available for inclusion.
The template rendering applies this logic:
- Try loading template for the content name. Eg. for content
other.md, StaGen engine will try to loadother.st. - If the specific template is not available, use the default
_default.sttemplate. So make sure every one of your project has_default.stdefined.
You can include a template within a .st file. Eg., you have ga.st (ga->Google Analytics) to be included in the template index.st. In index.st you have to:
$ga()$
This will include the rendered contents of ga.st inside index.st. Note that all variables that are available to index.st are also available to included templates.