Sitegen assembles static webpages through a pipeline consisting of templates and pages. If you're looking for something dynamic try out Lapis.
Pages and templates can be written in html or markdown. The site is defined
site.moon file, which is written in MoonScript. It describes
all pages that need to be brought in, it can also specify configuration
variables accessible within pages and templates.
Pages can be assigned any number of types, which lets your aggregate pages into groups. Enabling you to create blogs, among other things.
Sitegen has a plugin system that lets you transform the page as it travels through the pipeline. Letting you do things like syntax highlighting and automatically generated headers.
Sitegen uses the cosmo templating language to inject variables, run functions, and trigger actions in the body of the page as it is being created.
$ luarocks install sitegen
To create a new site we just need to create a
site.moon file in a directory
of our choosing. We'll call the
create function on the
sitegen module to
initialize the site.
create takes one argument, a function that will be used
to initialize the site. An empty function,
=>, is perfectly valid.
-- site.moon sitegen = require "sitegen" sitegen.create =>
We can tell our site to build by using the
sitegen command, run it from the
same directory as
site.moon. (You can also run it in any child directories,
but we don’t have any yet.)
Since our site file is empty it won’t do anything except create a cache file.
Sitegen works great with markdown, lets create a new page in markdown,
Hello, and welcome to *my homepage!*
site.moon to have that file:
-- site.moon sitegen = require "sitegen" sitegen.create => add "index.md"
And now tell it to build:
Every time you edit the markdown file you'll have to tell Sitegen to rebuild. That can be annoying. Start watch mode to have it listen for file changes and automatically rebuild:
$ sitegen watch
Whenever you edit an input file, the corresponding output file will be built.
If you edit
site.moon you'll have to restart watch mode, sorry!
Sometimes you want to share a piece of data across many pages, say a
version_number for a open source project’s homepage. Just assign the variable
sitegen = require "sitegen" sitegen.create => @version = "1.2.3-alpha-gamma" add "index.md"
Then reference it with
$ in your page, here’s
# Welcome The current version is $version
There are a couple variables that are always available, here they are:
$root— a relative path prefix that points back to the top level directory of your site. For example, if the current page is
../. This make it easy to built URLs to other pages without being concerned about where your page is being rendered to.
$generate_date— a timestamp of when the page is being generated. Good for displaying on your page, and also adding to URLs of assets as a cache buster.
Plugins may also introduce variables, in addition to functions, that can be accessed from a page.
If you looked at the compiled output of any of the examples above you may have
noticed that each page got wrapped in an
<html> tag along with a
<body>. The template defines what wraps each page’s contents, there’s a
default one that adds those tags. The default one doesn’t add much, so you'll
want to create your own.
Here’s what the default template looks like:
<!DOCTYPE HTML> <html lang="en"> <head> <meta charset="UTF-8"> <title>$title</title> </head> <body> $body </body> </html>
$body variable gets the contents of the page, the
$title variable lets
you set the title of the page. It’s
nil by default, but you can set it in
Templates live in the
templates/ directory next to
site.moon. If you name a
index then it will take place of the default one provided by
Sitegen. Here’s a custom default template:
<!-- templates/index.html --> <html> <body> <h1>GREETINGS</h1> $body </body> </html>
Make sure to include
$body, otherwise the contents of your page will not be
You can pass individual pages custom options to control how they are rendered,
like where they are written to and what template they use. You can pass these
options to the
add function in
sitegen = require "sitegen" sitegen.create => add "home.md", template: "jumbo_layout", target: "index.html"
This will cause the page to be written to
www/index.html, and it will use the
template located in
In all the previous examples we've used Markdown files for our pages. You can also use HTML files.
All pages are passed through a preprocessor that fills in the variables and runs any functions, so HTML pages can access the same things as Markdown pages.
To create an HTML page we just give it the extension
sitegen = require "sitegen" sitegen.create => add "about.html"
<!-- about.html --> <p>This page was generated on $generate_date, <a href="$root">Go home</a></p>
Now that you know how Sitegen works, you'll want to look over the plugins to learn about the additional functionality. All plugins and enabled by default so no extra steps are required to use them.
MIT License, Copyright © 2015 by Leaf Corcoran