Blackjack Docs
Blackjack is a simple, fast, and extremely extensible static site generator written in Lua.
It's goals are to be as simple as possible, while maintaining a high level of usability and
scalability.
Who should use Blackjack?
If you're tired of bloated software and want a simple static site generator that puts you in
control, blackjack is for you.
Who shouldn't use Blackjack?
If you're looking for a lot of advanced features and don't want to write any code yourself,
blackjack probably isn't for you. If you want to make a static blog you should probably use
Jekyll.
Getting Started
Installation
Install Lua and LuaRocks from your distribution's package manager or from lua's website.
Then install blackjack with
sudo luarocks install blackjack
Configuration
Blackjack is a Lua module, not a standalone program. This means that to build your site, you
will need to write a very simple lua program. Don't worry if you don't know Lua, it's a very
simple language and you won't need to touch anything complicated to write configuration files.
Here is the simplest blackjack config:
require "blackjack"
Site:build()
Site is an object that has some configuration data that influence how your site is build. When
you run Site:build(), blackjack uses that information to build your static site.
By default, Site looks like this:
Site = {
-- Template source directory
templates = "templates",
-- Content source directory
content = "content",
-- Output directory
output = "site",
-- Static file directory
static = nil,
-- File processor objects
processors = {
html = {
process = htmlProcessor,
extension = 'html'
},
md = {
process = mdProcessor,
extension = 'html'
}
}
}
The first four fields are pretty self explanatory, they just set what directories blackjack
will look for files in.
The processors table is a little more interesting. Processors are functions that blackjack
uses to transform input content into output content—usually html.
The built-in processors htmlProcessors and mdProcessors transform HTML templates and Markdown
into HTML. These are included with blackjack because of how common they are.
It is trivial to define your own processors, you don't even have to use Lua!
For example, here's how you would define a processor that takes sass files as input and
generates css:
Site.processors.sass = {
process = cmdProcessor("sass -"),
extension = "css"
}
The cmdProcessor function is a helper for defining processors that invoke other commands.
This has some disadvantages: mainly that such processors won't have access to the defined
variables, and won't be able to take advantage of templates. Commands invoked through such
processors are given the content of the input file through standard input and are expected
to provide generated output through standard output.
This very same sass processor is used to build this website. That's how easy it is to add
functionality to blackjack!