HTTPS SSH

Genmaicha

What is it?

Genmaicha is a static site generator: it creates static (i.e., not dynamically processed) websites from source files.

Source files consist of static unprocessed files (JavaScript, CSS, etc.), templates (using Razor HTML), and content files (using Markdown).

Reasoning

Static websites are inherently more secure than dynamic ones: there is no potentially flawed website code to exploit. They are also (generally) much faster because no time is spent connecting to databases, processing information, and finally outputting dynamic content.

The downside, of course, is that a lot of dynamic website functionality is simply not possible with static websites. For this reason, it usually doesn't make sense to have static sites that rely heavily on user-generated content.

Static sites are, however, a good match for personal blogs, brochure sites, and other websites that don't require dynamic content generation.

There are quite a few different static site generators out there. Genmaicha's purpose is to be a powerful, developer-focused, yet relatively easy to use generator.

Current status

Genmaicha has no stable releases. It is currently under development, and a lot can still change. If you would like to use it, please be aware that directory structure, APIs, and general usage are all still in flux and may change. It is advised to wait for a beta release at the earliest to use Genmaicha in production environments. Having said that, it's already being used successfully on Arktronic.com.

How do I use it?

Download the latest release package from the Downloads section, and run Genmaicha.exe in a commandline (terminal) window. It will output its basic usage syntax.

There is a minimal prescribed folder structure. You are free to create whatever directories you wish in your site. Any directory can have processed content files by creating these files in the _c subdirectory under the desired directory - including the root directory of the website. Additionally, any directory can have metapages by creating metapage files in the _m subdirectory under the desired directory.

Metapages are pages created by a custom processing script after all of the normal file copying and content file processing operations have completed. They are especially useful as content listings. At least two files are needed to create a metapage - the processing script that has a .meta extension, and a content file (usually configured to use the Razor preprocessor) that gets processed with the data generated by the processing script. The script has the ability to create more than one output file, so things like pagination are possible.

Preferences and other settings are handled via configuration files named genmaicha.conf. This file is required in the root directory of the website. Any other directory may have additional configuration files that override the defaults from their parent directories. Configurations are processed hierarchically from the root directory on down.

For more information and examples, see the more comprehensive usage guide.

Other helpful info

Available options in genmaicha.conf

Technical details

Important note for Mono

In order to run Genmaicha under Mono, you need to be using a version of Mono at or after this commit from 2014-08-14. Older versions are not able to process time zones correctly.

Running on Linux web hosts

If you want to run Genmaicha on a Linux web host that does not have Mono installed, you can still do so using the Genmaicha Minimal Runtime Environment for Linux, or GMREL. As its name implies, GMREL is a minimal Mono environment that has just enough to be able to run Genmaicha.

To use GMREL, download the x86 or x64 version (as needed) from the Downloads section, and extract it inside the Genmaicha directory. That should create a gmrel/ directory with the mono executable and other files necessary to run Genmaicha. Then, in the Genmaicha directory, execute g.sh and Genmaicha should run.