The overall principle is simple.
wlt read informations in specific folders, transform it in css, js and html to create a static web site.
convention over configuration
Here is the conventions for the folders:
Will contain all generated content. This is the folder to copy to your web server.
Contains all blog posts. These are markdown files which name has the following structure:
yyyy: year of publication
mm: month of publication
dd: day of publication
title-of-the-blog-post: generally the title of the post, without any special character
The html file will be:
You can define some static files which are not blog post. These files are in
_pages folder and are markdown files. The name of the markdown file will be the name of the html. By example
index.md will become
Some a little more special files may be present, see the specific part.
All sass files to be compiled in css. Root files are specified in the configuration file. The name of the css file will be the name of the root sass file. By example
application.sass will become
You can use all functionalities of sass, by example
@import to split your css in multiple files.
If you want to use css-only files, please refer to the public part.
application.coffee will become
For now there's no way to concat many coffeescript files in one. That's simply not the principal goal. A system like sprockets can be adding in the future.
All haml template files, either root, partials or intermediary.
Contents (pages, posts) declare in a header the template to use. A template can call a parent template. This allows to have a template to include markdown and a template for the page. To go further, see examples.
config.yaml contains all necessary parameters to generate the site. Some are system parameters (like the root url), some are simply informations to factorize like accounts, twitter informations, etc.
This is an example of config file :
# URL of generated web site (to have absolute links) site_url: http://log.winsos.net # Deployement url (via rsync) deploy_to: ...@www.....lan:/var/www/log/ # Page title title: CrEv's log # Twitter cards, opengraph, etc # Author name: Plop Plop # Twitter site / creator -> twitter cards twitter_site: _crev_ twitter_creator: _crev_ # Default description if no excerpt default_description: My personal weblog # Some accounts, to be displayes in an about page in default templates accounts: twitter: https://twitter.com/_crev_ gplus: https://plus.google.com/112813954986166280487 github: http://github.com/eunomie coderwall: https://coderwall.com/crev linkedin: http://fr.linkedin.com/in/yvesbrissaud # Assets, description of css/js to generate (name of files without extension) assets: css: [application, cv] js: [application]
Except for the first which is really recommended, others are optional and depend of your templates. This is only an example, you can add all parameters you want. They will always be accessible in ruby objets.
Every markdown and haml files can start with an header to add some meta data. All parameters are not mandatory and can vary depending on the case (pages, blog post, template). This is an example for a blog post.
First, the header must starts, at the first line of the file, with
--- and ends by a line containing only
All inside this lines is yaml.
layout: name of the haml file which will contain the markdown output
tags: Array containing tags
title: Title of the article
author: Name of the author
false, allow to not generate output for this content
By example :
--- layout: post tags: [web_log_today] title: Web Log Today first release author: Yves email: plopplop@....com twitter: _crev_ published: false ---
Two special files can be present inside
_pages folder, and on in
The first is
atom.xml.haml. It allows to generate an
atom.xml file containing all blog posts.
Second is a
sitemap.xml.haml. It allows to generate a
sitemap.xml referencing all files.
Finally, the file
tags.haml can be present in
_layouts to generate files referencing all posts with a common tag. Contrary to all other files, this one can have multiples output, one file per tag in