Balloon — Static Website Generator
Because balloons generate static...
Balloon is a very simple static site generator. Built for deploying to S3. It works for my needs,
but it's pretty simple.
View the source code of my website.
Overview of Balloon
- uses Swig template language
- auto convert Markdown to HTML if file ends in
.md
- supports Github-flavored Markdown features
- auto syntax-highlights code blocks
- built-in webserver that auto-restarts on changed files
- S3 deploy functionality

Installation
npm install -g balloon-generator
Usage
balloon
balloon --output ./another/destination/
balloon --serve
balloon --serve 3000
balloon --help
Usage: balloon [options]
Options:
-h, --help output usage information
-V, --version output the version number
-s, --serve [port] watch and serve files
-b, --build <path> override build path
Folder Structure
Here's what a base project looks like:
MyBalloonProject/
├── balloon.json
├── content/
├── layouts/
└── static/
Here is something a bit more complicated:
MyBalloonProject/
├── balloon.json
├── content/
│ ├── index.html
│ ├── rss.xml
│ ├── blog/
│ │ ├── index.html
│ │ └── 2014/
│ │ └── 12/
│ │ ├── 04/
│ │ │ ├── My First Post.md
│ │ └── 08/
│ │ └── My Second Post.md
├── layouts/
│ ├── rss.xml
│ └── base.html
└── static/
├── favicon.ico
├── styles/
│ └── main.css
└── scripts/
└── main.js
A few notes on what you see above:
- URL slugs are automatically generated from file names
- file paths will be equal to the URL path
- Example
mysite.com/blog/2014/12/04/my-first-post.html
Configuration
Balloon looks for a balloon.json
file in the directory that it is run from. Here is an example
of a config:
{
"source": "./",
"build": "build/",
"domain": "website.com",
"defaults": {
".*": {
"_layout": "default.html",
"siteName": "My Website",
"page_type": "basic"
},
"^/blog/.+": {
"_layout": "blog.html",
"page_type": "blog"
}
}
}
Template Context
Balloon lets you define context variables in balloon.json
(see below), but it also provides some
default ones that should be useful. All Balloon-generated variables start with underscores.
_title
name of the file, without the extension_slug
full URL path of the current page_created
an extracted date if the URL path contains the pattern /YYYY/MM/DD/
- this is an object containing the properties
timestamp
, year
, month
, day
_pages
a list of all the pages that were rendered, along with the context for each one
- only files named
index.html
and rss.xml
have access to _pages
- Example: useful for a
/blog/index.html
page to list all blog posts
Other Notes
Right now I'm the only person I know of using Balloon in production. You can check out
my site (also view the source). I'm
always open to chat as well. You can find my contact info on my website.