static

README

static

An abstraction ontop of blackfriday for the purpose of accepting a folder of files and generating html in lexical order with built-in templates.

The primary objective of this project was originally self-education. The result is a sub-par utility with minimal features. The only benefits it offers are a significantly smaller code base, and no meta-data dependencies.

usage

To import the library:

import "github.com/cdelorme/static"

notes

Relative path support has been removed because raw markdown is intended to be readable.

Automatic navigation has been removed from the web solution, since the requirements vary by website and are entirely different when generating a book. Use the template override feature to create your own.

The code makes no assumptions about what index name is used, since that is entirely controlled by the web server.

The library is not concurrently safe, because there are zero benefits to running it concurrently. Everything is bottlenecked at the hard drive, and that cannot be addressed without proper buffered solutions to both markdown and template parsing.

It uses go-bindata to embed default templates, which have been committed to the project since go generate is not possible to do from go get.

No efforts have been made to optimize re-execution around existing files, but it would be possible to compare the markdown file modified time against the modified time of existing html files to reduce overhead in the future.

If two files with alternative markdown extensions but identical base names exist, the first match is the only one that will be parsed into an html file.

The book mode provides automatically generated navigation using javascript.

Any absolute links in book mode will not function as desired.

All tests have been (re) written using a black-box approach, where only publicly exposed functions and properties are modified.

references

• blackfriday
• function call from template
• buffer blackfriday output
• github markdown file extensions
• javascript queryselector
• chaining writers in go

Documentation

Overview

This package provides a utility to parse markdown files in lexical order as a single document or individual pages, with no additional requirements.

It includes default templates that are embedded, but can be directed to a separate file granting better control for more complex use-cases.

Template parameters are simple, and include Title, Content, and Version; both the Version and Title can be changed. If in web mode, an additional property called Name will be set to the basename of the file.

Index

• func Asset(name string) ([]byte, error)
• func AssetDir(name string) ([]string, error)
• func AssetInfo(name string) (os.FileInfo, error)
• func AssetNames() []string
• func MustAsset(name string) []byte
• func RestoreAsset(dir, name string) error
• func RestoreAssets(dir, name string) error
• type Markdown
  • func (m *Markdown) Run(o operation) error

Functions

func Asset

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy:

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames

func AssetNames() []string

AssetNames returns the names of the assets.

func MustAsset

func MustAsset(name string) []byte

MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.

func RestoreAsset

func RestoreAsset(dir, name string) error

RestoreAsset restores an asset under the given directory

func RestoreAssets

func RestoreAssets(dir, name string) error

RestoreAssets restores an asset under the given directory recursively

Types

type Markdown

type Markdown struct {
	Title    string `json:"title,omitempty"`
	Input    string `json:"input,omitempty"`
	Output   string `json:"output,omitempty"`
	Web      bool   `json:"web,omitempty"`
	Template string `json:"template,omitempty"`
	Version  string `json:"version,omitempty"`
	L        logger `json:"-"`
	// contains filtered or unexported fields
}

This is the compiler that collects the list markdown files, a title, the input and output paths, and whether to produce multiple files (web mode) or to produce a single file (default, book mode).

All public properties are not thread safe, so concurrent execution may yield errors if those properties are being modified or accessed in parallel.

func (*Markdown) Run

func (m *Markdown) Run(o operation) error

The primary function, which accepts the operation used to convert markdown into html. Unfortunately there are currently no markdown parsers that operate on a stream, but in the future I would like to switch to an io.Reader interface.

The operation begins by capturing the input path so that we can translate the output path when creating files from the input path, including matching directories.

If no title has been supplied it will default to the parent directories name, but this might be better placed in package main.

The default output for web is `public/`, otherwise when in book mode the default is the title.

We walk the input path, which assembles the list of markdown files and then we gather any errors returned.

Finally we process the files according to the desired output mode.