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
through the 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.)
$ sitegen
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,
index.md
:
Hello, and welcome to *my homepage!*
Update site.moon
to have that file:
-- site.moon
sitegen = require "sitegen"
sitegen.create =>
add "index.md"
And now tell it to build:
$ sitegen
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
on self
:
sitegen = require "sitegen"
sitegen.create =>
@version = "1.2.3-alpha-gamma"
add "index.md"
Then reference it with $
in your page, here’s index.md
:
# 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 wwww/hello/world.html
, the $root
would be ../
. 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 <head>
and
<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>
The $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
your site.moon
Templates live in the templates/
directory next to site.moon
. If you name a
template 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
visible.
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 site.moon
:
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 templates/jumbo_layout.html
.
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 html
:
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