• Ronan Kerviche
• Gallery >
• Posts >
• Publications >

Clone me from GitHub!

Grimoire is a minuscule static site generator written in Python. It focuses on generating content from simple data to be integrated in layouts. The root directory of a site should contain a site.json descriptor file and a layouts/ directory containing all of the layouts to be used. Layouts can be any type of text files, including but not limited to HTML, CSS or SVG. The site descriptor file gives global variable and site categories to be loaded. It ressemble the following example :

{
	"site": "My Blog",
	"rootDirectory": "blog/",
	"categories":[
	{
		"category": "Posts",
		"reader": "postReader",
		"files": "true",
		"directories": "false"
	},
	{
		"category": "Gallery",
		"reader": "imageReader",
		"files": "true",
		"directories": "true"
	}],
	"description": "My Blog, built by Grimoire",
	"title": "My Blog",
	"githubUsername": "myUsername",
	"someOtherVariable": "someValue"
}

• site : Code name of the site.
• rootDirectory : Root directory of the site.
• description : Description of the site.
• title : Title of the site.
• categories : List of the categories in the site (an array).
• category : Category name and directory name from which the resource will be loaded.
• reader : Name of the function to be used to read each resource file. Directories will not be read.
• files : List the files in the category (true or false). The listing is recursive.
• directories : List the directories in the category (true or false). The listing is recursive.

Grimoire will start by listing all the files in layouts/ and then, all the files and directories (if enabled) in the categories (here Posts/ and Gallery/). For each file found it will attempt to read it with the specified eader functions. Readers are located in the Modules/ directory. Each contains a python function def apply(filename): which returns a tupple made of two elements, the first is a dictionnary of the data (key and value pairs) the other is the content of the resource. Both can be left empty if needed.

Each layout file can either be a raw text file or a text file with JSON header to declare variables separated from the text by a delimitation : -----. To generate HTML pages the header must contain one of the two following variable : "generate" : "path/filename.html" or "foreach" : "var in site.variableList". The first will generate a single page and the second will generate one page per resource, each page will be saved to the same path as the resource with a standard HTML extension.

{
	"generate": "index.html",
	"someVariable": "someValue"
}
-----
<!-- Some header -->
This is the index page.
<!-- Some footer -->

And for each of the posts :

{
	"foreach": "post in site.categories.Posts.data",
	"someVariable": "someValue"
}
-----
<!-- Some header -->
<h1>{{post.title}}</h1>
{{post.content}}
<!-- Some footer -->

Variables are surrounded by {{ and }}. They are given as a standard object to member notation, with dots as separator : {{ rootObject.obj1.obj2.value }} and can support spaces with double quotes : {{ rootObject."another object".value }}. The following variables are set by default :

For each resource we also have the following additional variables (resource is an arbitrary name here) :

It is also possible to process information from the layouts with three constructs :

{% if object.variable %%
This text will be present in the final page if object.variable exists.
%}
{% ifnot object.variable %%
This text will be present in the final page if object.variable does not exist.
%}
Elements list :
{% foreach element in object.list %%
	Here is another value : {{element.someValue}}
%}
Calling a function from the Modules/ folder :
{% call myFunction arg1 arg2 %%
	Some relevant body.
%}

Finally, we can generate the site from the resources with the command : python /path/to/grimoire.py from within the site directory. You can also start a local server with : python /path/to/grimoire.py --serve --port 8000