# staticmd

This is a golang project for a command that generates static html output from markdown documents and a template.  It's purpose is to make it easy to convert large folders in bulk, as well as single-page support.  It works for simple static content websites, as well as documentation.


## alternatives

I was lazy this time and haven't checked, but there exist a few tools in other languages like [node; harp.js](http://harpjs.com/).


## sales pitch

The aim of this tool is to provide a simple command with sensible flags that will generate:

- a full website
- a relative-path local readme
- a single file with an automated table of contents

It depends on:

- a user-supplied template
- a bunch of markdown files

It supplies the template with convenient output, such as:

- top level navigation
- asset versioning

Its options include:

- template path
- input path
- output path
- single-page output
- relative links
- debug mode
- cpu profiling


**Behavior:**

The template path is the only required parameter, and an example will be included with the project source.

It assumes the input path is the execution directory.

It assumes an output path of `public/` relative to the execution path.

Single page output will combine all files in the input path into a single output; something akin to a "book".  When this flag is selected the full table of contents is listed first; depth is applied based on the folder layout, and in the order which it was parsed.

By default the application assumes absolute path starting at the parent directory.  The relative links option is for multi-page output (it is ignored when run in single-page mode) and will provide relative links to files and folders, including full paths (ex. it will not assume `/` points to `/index.html` and will fully generate the appropriate path).

If run within a repository it will attempt to grab the short-hash from git as a version, otherwise it will use a unix timestamp.

In a github fashion it assumes `readme.html` as the primary index; it will automatically prepend a table of contents to the `readme.md` or `index.md` files if either exists, otherwise it will create an `index.html` with just the relative files.

For multiple page generation it utilizies concurrency.  _When run in single-page mode it cannot build concurrently._


**It does not come with:**

- abstractions
- interfaces
- unit tests


## usage

Install the command:

    go get github.com/cdelorme/staticmd

In this example we can generate a single-page document for easier printing and sharing:

    staticmd -t template.tmpl -s -c src/

**The above command will generate a single file from the template using files inside `src/`.**

_For further details on command line operation, use the `--help` flag._


### template file

A single template file can be used to generate all pages; even in single-page mode.

The following variables are provided to the template file:

- depth
- version
- navigation
- content

The `depth` property is for links you supply, such as to css and js assets.

The `version` tag allows you to prevent caching of changed assets, such as css and js, but can also be supplied.

The `navigation` is a set of top-level links.  In single-page mode the navigation is omitted.

The `content` is the file contents converted to html, and may include prepended table of contents if the page is a `readme`, `index`, or from single-page mode output.

_Any binary assets such as images should be hosted on a CDN and have full paths.  If you need to supply a full offline version then use the single-page mode with this tool and print to pdf._