Koto (Japanese for "thing", but not a physical thing, more like an idea or concept) is a simple static site generator. I was looking for something to make a set of notes pages with, that didn't have massive external dependencies, and which wasn't designed for blogs.

Koto uses a simple HTML template, with substitution variables. Source files are written in Markdown, with support for extended syntax and code highlighting. For code highlighting, Highlight is used. Highlight is the only external dependency, and is optional.

Koto was inspired by simple Japanese homepages, that use only basic HTML and concentrate on delivering information clearly and efficiently.

Create a directory for your site with the following hierarchy:

site_root
	⤷ .koto
		⤷ config.txt
		⤷ template.html
	⤷ index.md

You can add markdown files to the site_root directory, or create sub-directories for them. Each sub-directory is a logical group of related files, which will be grouped in the auto-generated list of files that can be inserted into your template.

Run Koto by supplying the address of the root directory:

Windows: koto d:\path\to\site_root
Linux:   koto /path/to/site_root

Koto will create a .output directory in site_root. Any .md files will be converted to HTML using the template.html file in the .koto directory. Any other files and directories that do not start with a period (.) will also be copied to the .output directory, so you can add things like .css and image files as needed.

Markdown files names end with .md. Extended syntax is supported via Markdig, see its page for a list of extensions that are enabled by default.

In addition to Markdown code, all .md files must have a variables section at the top. It can be empty, but at a minimum the delimiting --- must be there.

# comment
var1 = value1
var2 = value2
---
Markdown code here

Variables are defined using a very simple pattern.

variable_name = value

While it is possible to have spaces in the variable name, it's not recommended.

The value is everything up to the end of the line, and can include spaces. It will be inserted as-is, including things like quotation marks.

TODO: Multi line value support.

There are two types of variable: global and local. Global variables are set in config.txt (see below) or by Koto internally. Local variables are set in the header of each source Markdown file.

Local variables take priority over global ones, so for example you can redefine page_title in each source file if you don't want to use the file name as the title.

Koto has some built in global variables:

The template file is used to convert Markdown to HTML. It is a normal HTML file that supports simple substitution variables. Variables are inserted by surrounding them by $$, e.g. $$markdown$$ will insert the source Markdown code converted to HTML.

The config file uses a simple format, the same as the variables section at the top of Markdown files, except there is no need for the delimiting ---. Config file variables are global.

variable_name = value

Install Highlight wherever you like. Use the following variables to control highlighting. It is recommended that you place them in config.txt.

TODO: Add support for GNU Source-highlight.

• Proper exception handling
• More useful error messages