batsman

README

batsman

batsman is a static site generator. It aims to have zero configuration and make minimum assumptions about the structure of your source directory.

Install

go get -u github.com/nishanths/batsman

Quick start

$ batsman init mysite     # initialize example site into mysite/
$ cd mysite               
$ batsman build           # generates content into build/
$ batsman -watch serve    # serve and watch for changes

HTML, CSS, JavaScript, and SVGs in build/ will be minified, and optional HTML tags omitted.

Run batsman -help for available commands and flags.

Directory Structure

The site source is in src and the generated site in build. Running batsman build maps files from src to build by these 4 rules:

src/**/*.html          -->  build/**/*.html          (copied and executed as template)
src/**/*.{md,markdown} -->  build/**/*/index.html    (executed on layout.tmpl file in the same directory)
src/**/layout.tmpl     -->  -                        (ignored)
src/**/any_other_file  -->  build/**/any_other_file  (simply copied)

The only assumption batsman makes about the structure of src/ is the existence of a layout.tmpl file in each directory that contains a markdown file. Besides that, you can structure src/as you like.

Markdown files are mapped this way so that they are available at /x/y/z instead of /x/y/z.html.

Front matter

Front matter can optionally be present in markdown files between the +++ delimiters. If present, front matter should start at the first line of the file.

title is the title of the page.time is the time that the page was published. draft indicates whether to include the corresponding file in build/. These are typically useful for blogging.

Example markdown file with front matter:

+++
time = "2006-01-02 15:04:05 -07:00"
title = "Hello, world"
draft = true
+++

Normal *markdown* content goes _here_.

All 3 fields are optional.

• If title is absent, the filename without extension is used.
• If time is absent, the last modified time on the file is used.
  Additionally, hh:mm:ss and time zone are optional; if absent 10 AM UTC is used.
• If draft is absent, it is assumed to be false.

Generate markdown files with front matter

To quickly generate markdown files with front matter, use batsman new and redirect the output to a desired file:

batsman -title "New Post" -draft new > src/blog/my-new-post.md

Templates

Files that are executed as templates include:

• *.html
• layout.tmpl files for the markdown files in the same directory

They can use the full range of features in the Go text/template and html/template packages.

Each template has the following struct available as the dot (.):

type TemplateArgs struct {
	Current Page              // Current markdown file.
	Dir     []Page            // Markdown files in the same directory.
	All     map[string][]Page // All markdown files in the tree.
}

where Page is:

type Page struct {
	Content template.HTML // HTML content generated from markdown.
	Title   string        // Title from front matter.
	Time    time.Time     // Timestamp from front matter or file's last modified time.
	Path    string        // HTTP path at which the page lives.
}

The Current field is only available in layout.tmpl. The pages in Dir and All are sorted in reverse chronological order based on the Time field.

For more usage examples, see the src/ directory in the site generated by running batsman init.

License

MIT