Over a million developers have joined DZone.

StaGen: Static Site Generator in Java 8

DZone's Guide to

StaGen: Static Site Generator in Java 8

· Java Zone ·
Free Resource

Download Microservices for Java Developers: A hands-on introduction to frameworks and containers. Brought to you in partnership with Red Hat.

Before StaGen was born, I was using RapidWeaver for maintaining my site WizTools.org. I was really frustrated by the text formatting mess created by RapidWeaver. I was spending time on unnecessary work introduced by the software. StaGen was born out of this frustration. The first functional version was written overnight. The next day, my site WizTools.org was migrated to StaGen. There was one design goal for development of StaGen: to develop and maintain simple websites having few pages with minimal effort. This goal resulted in selection of Markdown for content, StringTemplate for templating, and JSON for storing configuration.

Folder structure

A StaGen managed website project needs to follow folder-structure similar to:

`-- content
|   |-- index.md
|   |-- other.md
`-- config
|   |-- other.json
|-- master.json
`-- static
|   |-- my.css
`-- template
|   |-- index.st
|   |-- other.st

Detail of the folder structure:

  • content: This folder has content in Markdown format. The generated site will have corresponding HTMLs generated for each content. Sub-folders within content folder will not be considered by the StaGen engine.
  • config: Each page can have specific (optional) configuration stored here. Configuration is in JSON format. The name of the file must match the content file name.
  • master.json: This is a mandatory configuration. This holds site-wide configuration data.
  • static: All static content like .js, .css and images required by site are stored here.
  • template: The StringTemplate 4 (ST4) templates are placed in this directory.

How StaGen works?

The order of processing of StaGen engine:

  1. Load the master configuration master.json.
  2. Copy static resources to destination folder (a folder named target is created as part of site-generation).
  3. For each Markdown file in the content folder, do:
    1. Load corresponding configuration (read next section on Loading Configuration).
    2. Apply the configuration on the corresponding template and write the resulting HTML file to destination folder.

Loading Configuration

Configuration is of type JSON map:

  "title": "My Site Title",
  "activities": ["Dance", "Jump", "Shout"]

Note that the key has always to be a string, the value can be any type.

As discussed earlier, the site-wide configuration is master.json. This is loaded by the StaGen engine at the beginning. When processing each content, say, index.md, StaGen tries to load the corresponding configuration from config/index.json. The specific config is overlayed above the master config for this instance. Meaning, if you have defined title in master.json and config/index.json, when rendering index.md, the title from config/index.json will be used. If config/index.json is not available, StaGen does not complain—it just falls back to the data in master.json.

Rendering Template

StaGen uses StringTemplate. A simple template that uses the JSON configuration listed above:

$activities: {activity|

$_content$ is the Markdown content rendered as HTML that is available for inclusion.

The template rendering applies this logic:

  1. Try loading template for the content name. Eg. for content other.md, StaGen engine will try to load other.st.
  2. If the specific template is not available, use the default index.st template. So make sure every one of your project has index.st defined.

Template within Template

You can include a template within a .st file. Eg., you have ga.st (ga->Google Analytics) to be included in the main template index.st. In index.st you have to:


This will include the rendered contents of ga.st inside index.st. Note that all variables that are available to index.st are also available to included templates.

The StaGen tool

StaGen is distributed as a executable Jar. To get help on the tool:

$ java -jar ~/stagen-VER-full.jar -h

To generate the site from project:

$ java -jar ~/stagen-VER-full.jar gen

The above command will create the static site in the folder target.

To delete the target folder:

$ java -jar ~/stagen-VER-full.jar clean

And if you are starting new, and want the new project structure to be created:

$ java -jar ~/stagen-VER-full.jar init


StaGen is deliberatly designed simple. I personally wouldn't use it to maintain too complex sites. It does not support blogging or themes as few other static site generators do. And, I believe, StaGen derives it strength and beauty in the features that it does not support.

Download Building Reactive Microservices in Java: Asynchronous and Event-Based Application Design. Brought to you in partnership with Red Hat


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}