static

static

This is a go library written to provide static generation of html from markdown with a template.

The intended function is to make it easy to convert large folders of documentation in bulk to explorable web content or a single-page document for printing as a PDF and redistributing.

The original goal of the project was to learn more about the programming language and tooling.

design

The design focuses on three key outcomes:

• absolute paths for a website
• relative paths for local content
• single-file with a table of contents

It depends on:

• markdown
• a template

An example template has been provided.

It automates two convenience outputs:

• automatically generated index navigation
• asset versions for cache busting

template

A user-defined template affords you flexibility and control.

A limited subset of variables are provided for your use:

• Depth
• Version
• Nav
• Content

The .Depth property is used when generating paths to global resources such as javascript, style sheets, and images.

The .Version property allows you to address cached resources such as javascript, style sheets, and resources javascript may ask for. It is highly efficient as the cache will immediately rebuild using the new version.

The .Nav is the table-of-contents produced in single-page or "book" mode, and is empty otherwise.

The .Content is the file contents converted to html, and will have a table of contents automatically prepended to any index.html file deeper than the root of the output folder.

Any assets hosted on a CDN can be given full paths, and it is recommended to host binary resources (such as images) and any javascript and style sheets there as well.

usage

To import the library:

import "github.com/cdelorme/staticmd"

To install the cli utility:

go get -u github.com/cdelorme/staticmd/...

The ellipses will install all packages below the main path.

future

In the future I would like to address the following:

• move page generation into a separate function
  • consider offloading logic into page struct to cleanly separate code
  • separation grants support concurrent execution of multi-page
• move create-dir-if-not-exists logic into a separate function and call that from page generation
• remove back-to-top from code
  • the back-to-top feature can be generated on-load via javascript
• streamline logic surrounding how absolute and relative paths are handled
• standardize optimal navigation logic
  • fix title acquisition to check for title: or first header
  • each nav struct can have an embedded []nav
    • function exposed for template access to render recursively
  • every page should use the same navigation output in the same way
• switch to bytes.Buffer and buffered write for creating output file(s)
• embed default template using the go-bindata utility with a fallback for a supplied template
• add simple queue with rwmutex to safely process multi-file pages concurrently

references

• blackfriday
• function call from template
• buffer blackfriday output