static markdown compiler

Casey DeLorme 7c1d3bdb6b compressed configuration using json tags for cli flag assignment 8 anos atrás
cmd 7c1d3bdb6b compressed configuration using json tags for cli flag assignment 8 anos atrás
.gitignore bcea6a904d update ignorefile list 8 anos atrás
generator.go 7c1d3bdb6b compressed configuration using json tags for cli flag assignment 8 anos atrás
generator_test.go ece5269de0 remove comments as redundancy upon code 8 anos atrás
license b02a8ca927 added license to repo 10 anos atrás
navigation.go 835b8d706f address public page and navigation structs 8 anos atrás
page.go 835b8d706f address public page and navigation structs 8 anos atrás
readme.md 1ea3b246f4 update list of future expectations 8 anos atrás
staticmd.go ece5269de0 remove comments as redundancy upon code 8 anos atrás
staticmd_test.go ece5269de0 remove comments as redundancy upon code 8 anos atrás

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.

future

In the future I would like to address the following:

  • make page content generation a repeatable modular function
    • perhaps offload to page struct
  • make navigation a repeatable modular function
  • standardize navigation in a flexible way
    • using .Nav in the template per page instead of index-only with hard-coded structure
      • major issue is how to support depth with one template definition
    • supporting back-to-top functionality should not be hard-coded into the generator either
  • streamline how relative vs absolute paths are handled
  • repeatable directory creation behavior
  • simplified reusable modular mkdirall logic