Stone - the static website generator that rocks !

Specifications

Project structure

If you look into the directory generated by stone by default, you'll have:

├── config.stone
├── data
│   ├── style.css
│   └── template.html
└── pages
    └── index.md

• The config.stone file describes the configuration of your project. It defines its name, the pages you want to have in the title bar, and other things.
• The data directory contains the static content used to generate the pages:
  • template.html: the default template.
  • org-template.html: a template for org-mode pages exported by mlorg.
  • style.css: The stylesheet. The default one is made by Theotix (Thanks!).
• The pages directory is where you write the pages with your content. They are processed by the exporters, then inserted into a template.

After running stone, the static pages are generated in a new directory :

└── site
    ├── index.html
    └── static
        └── style.css

The site directory contains the generated content: what you want to send online to be served by your web server.

Exporters

Pages content is processed by exporters, to obtain from some syntax the html code to insert in a template.

By default, a built-in markdown exporter is provided, which handle files with extensions .md and .markdown. Consequently, you can write pages in markdown out of the box. If you don't know the markdown syntax yet, you can have a look at its specification or at a recap.

You can also specify custom exporters, that may override the built-in one(s), using the Exporters variable of the config.stone file. An exporter is stored as a couple of the extension of the files to handle, and an external command to convert pages to html. There are more details in the default config.stone.

If, for a given file in the pages directory, no exporter is found, it is copied as is.

Templates

After being processed by an exporter, the content of a page is inserted into a template. The default template is template.html, as indicated by the DefaultTemplate variable of the config.stone.

You can also specify custom templates: the PagesTemplates variable (in config.stone) specify a list of custom templates, composed by a couple of a regexp that matches the files that must use the template, and the filename of the template itself. There are more details in the default config.stone.

Writing custom templates

Stone templates are just plain html pages, with some magic variables that will be replaced during the pages generation.

The variables you can use are the following:

• PAGE_TITLE: will be replaced by the title's page, if specified in the Pages variables in the config.stone file. Otherwise, is replaced by the page's filename prefix (filename without extension).
• SITE_TITLE: replaced by the website's title, specified in the Title variable in config.stone
• CSS: inserts a html snippet which includes the css stylesheet present in the data/ directory (looks like <link href="static//style.css" type="text/css" rel="stylesheet"/>)
• BAR: replaced by the list of the pages listed in Pages in the config.stone. Each item is a link to the page, named by it's title.
• CONTENT: the content of the page itself, generated from the markdown of the page (in the pages/ directory).

When inserting a variable in your template, you must surrond it by '$'s: if the var is VAR, the string $VAR$ must be inserted in the template.

Generated pages properties

• When you create a heading (with some '#'s), an anchor is created. Its name can be determined by removing the blanks from the text of the heading. A title with text "My Title" will have an anchor named "MyTitle".
• The li item in the bar list corresponding to the current page has the css class current. So in the bar of the specs page (for example), there is <li class="current"><a href="specs.html">...</li>.