static markdown compiler

Casey DeLorme f7b8f425ee update line count for accuracy 8 years ago
cmd f7b8f425ee update line count for accuracy 8 years ago
.gitignore bcea6a904d update ignorefile list 8 years ago
generator.go ece5269de0 remove comments as redundancy upon code 8 years ago
generator_test.go ece5269de0 remove comments as redundancy upon code 8 years ago
license b02a8ca927 added license to repo 10 years ago
navigation.go 835b8d706f address public page and navigation structs 8 years ago
page.go 835b8d706f address public page and navigation structs 8 years ago
readme.md b7d334c754 compress and simplify library readme 8 years ago
staticmd.go ece5269de0 remove comments as redundancy upon code 8 years ago
staticmd_test.go ece5269de0 remove comments as redundancy upon code 8 years ago

readme.md

staticmd

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.

This project was used as a means of self-education for learning the go 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.