bongo

README

bongo

An elegant static site generator.

Features

• Fast. (yes, speed as a feature)
• Flexible. You can assemble your own static generator.
• Simple to use.
• Themes support.
• Minimalistic.

Status

The project is in alpha state.

Documentation

For Installation and Usage see documentation

Contributing

Just fork, and submit a pull request.

Author

Geofrey Ernest geofreyernest@live.com

Licence

This project is released under MIT licence see LICENCE for more details.

Documentation

Overview

Package bongo is an elegant static website generator. It is designed to be simple minimal and easy to use.

Bongo comes in two flavors. The commandline applicaion and the library.

Commandline

The commandline application can be found in cmd/bongo directory

and you can install it via go get like this

go get github.com/gernest/bongo/cmd/bongo

Or just download the latest binary here https://github.com/gernest/bongo/releases/latest

To build your project foo.

* You can specify the path to foo

bongo build --source path/to/foo

* You can run at the root of foo

cd path/to/foo

bongo build

To serve your project locally. This will run a local server at port http://localhost:8000. The project will be rebuilt if any markdown file changes.

* You can specify the path to foo

bongo serve --source path/to/foo

* You can run at the root of foo

cd path/to/foo

bongo serve

The generated website will be in the directory _site at the root of your foo project.

The Website Project Structure

There is no restriction on how you arrange your project. If you have a project foo. It will be somewhare in a directory named foo. You can see the example in testdata/sample directory.

Bongo only process markdown files found in your project root.Supported file extensions for the markdown files are

.md , .MD , .mdown, and .markdown

This means you can put your markdown files in any nested directories inside your project and bongo will process them without any problem. Bongo support github flavored markdown

Optionaly, you can add sitewide configuration file `_bongo.yml` at the root of your project. The configuration is in yaml format. And there are a few settings you can change.

static
  This is a list of static directories(relative from the project root). If defined
  the directories will be copied to the output directory as is.

title
  The string representing the title of the project.

subtitle
  The string representing subtitle of the project

theme
  The name of the theme to use. Note that, bongo comes with a default theme called gh.
  Only if you have a theme installed in the _themes directory at the root of your project
  will you neeed to specify this.

Themes

There is loose restrictions in the how to create your own theme. What matters is that you have the following templates.

index.html
	- used to render index pages for sections

home.html
	- used to render home page

page.html
	- used to render arbitrary pages

post.html
	- used to render the posts

These templates can be used in project, by setting the view value of frontmatter. For instance if I set view to post, then post.html will be used on that particular file.

IMPORTANT: All static contents should be placed in a diretory named static at the root of the theme. They will be copied to the output directory unchanged.

All themes custom themes should live under the _theme directory at the project root. Please see testdata/sample/_themes for an example.

Frontmatter

Bongo support frontmatter. And it is recomended every post(your markdown file) should have a frontmatter. For convenience, only YAML frontmatter is supported by default. And you can add it at the beginning of your file like this.

---
title: chapter one
section: blog
---

Your post contents goes here.

Important frontmatter settings,

title
	-The title of the post

section
	- this acts as a category of sort. You can specify any section that the
	post will reside.

	Sections are in the form of relative directory paths. for instance the following
	are valid sections blog, blog/funny, blog/happy, blog/stuffs.

	If you specify section as blog/golang. bongo will put the generated html files in the
	folder named blog/golang. And you can referance your post by blog/golang/mypost.html.
	where mypost is the name of your markdown file.

	The default section is home.

view
	- specifies the template to render the content.Defaults to post.

The Library

Bongo is modular, and uses interfaces to define its components.The most important interface is the Generator interface.

So, you can implement your own Generator interface, and pass it to the bongo library to have your own static website generator with your own rules.

I challenge you, to try implementing different Generators. Or, implement different components of the generator interface. I have default implementations shipped with bongo.

Index

• Constants
• Variables
• func GetAllSections(p PageList) map[string]PageList
• func HasExt(file string, exts ...string) bool
• func JSONHandler(front string) (map[string]interface{}, error)
• func Rollback(root string)
• func YAMLHandler(front string) (map[string]interface{}, error)
• type App
  • func New() *App
  • func NewApp(g Generator) *App
  • func (g *App) Run(root string) error
• type DefaultLoader
  • func NewLoader() *DefaultLoader
  • func (d DefaultLoader) Load(base string) ([]string, error)
• type DefaultRenderer
  • func NewDefaultRenderer() *DefaultRenderer
  • func (d *DefaultRenderer) After(root string) error
  • func (d *DefaultRenderer) Before(root string) error
  • func (d *DefaultRenderer) Render(root string, pages PageList, opts ...interface{}) error
• type FileLoader
• type FrontMatter
• type Generator
• type HandlerFunc
• type Matter
  • func NewJSON(opts ...string) *Matter
  • func NewYAML(opts ...string) *Matter
  • func (m *Matter) Handle(delim string, fn HandlerFunc)
  • func (m *Matter) Parse(input io.Reader) (front map[string]interface{}, body io.Reader, err error)
• type Page
  • func (p *Page) HTML() template.HTML
• type PageList
  • func (p PageList) Len() int
  • func (p PageList) Less(i, j int) bool
  • func (p PageList) Swap(i, j int)
• type Renderer

Constants

const (

	//DefaultView is the default template view
	// for pages
	DefaultView = "post"

	//OutputDir is the name of the directory where generated files are saved
	OutputDir = "_site"

	//DefaultExt is the default extensinon name for output files
	DefaultExt = ".html"

	//DefaultPerm is the default permissinon for generated files
	DefaultPerm = 0600

	//DefaultPageKey is the key used to store current page in template
	// context data.
	DefaultPageKey = "Page"

	//CurrentSectionKey is the key used to store the current section value in the
	// template context
	CurrentSectionKey = "CurrentSection"

	//AllSectionsKey is the key used to store all sections in the template context data
	AllSectionsKey = "Sections"

	//DefaultConfigFile is the default configuraton file for abongo based project
	DefaultConfigFile = "_bongo.yml"

	//SiteConfigKey is the key used to store site wide configuration
	SiteConfigKey = "Site"

	//ThemeKey is the key used to store the name of the theme to be used
	ThemeKey = "theme"

	//ThemeDir is the directory where themes are installed
	ThemeDir = "_themes"

	//DefaultTheme the name of the default theme
	DefaultTheme = "gh"

	//StaticDir directory for static assets
	StaticDir = "static"
)

Variables

var (
	//ErrIsEmpty is an error indicating no front matter was found
	ErrIsEmpty = errors.New("an empty file")

	//ErrUnknownDelim is returned when the delimiters are not known by the
	//FrontMatter implementation.
	ErrUnknownDelim = errors.New("unknown delim")
)

var DefaultTpl = struct {
	Home, Index, Page, Post string
}{
	"home.html",
	"index.html",
	"page.html",
	"post.html",
}

DefaultTpl is the defaut templates

Functions

func GetAllSections

func GetAllSections(p PageList) map[string]PageList

GetAllSections filter the pagelist for any section informations it returns a map of all the sections with the pages matching the section attached as a pagelist.

func HasExt

func HasExt(file string, exts ...string) bool

HasExt hecks if the file has any mathing extension

func JSONHandler

func JSONHandler(front string) (map[string]interface{}, error)

JSONHandler implements HandlerFunc interface. It extracts front matter data from the given string argument by interpreting it as a json string.

func Rollback

func Rollback(root string)

Rollback delets the build directory

func YAMLHandler

func YAMLHandler(front string) (map[string]interface{}, error)

YAMLHandler decodes ymal string into a go map[string]interface{}

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is the main bongo application

func New

func New() *App

New creates a new App which uses default Generator implementation

func NewApp

func NewApp(g Generator) *App

NewApp creates a new app, that uses g as the generator

func (*App) Run

func (g *App) Run(root string) error

Run runs the app

type DefaultLoader

type DefaultLoader struct{}

DefaultLoader is the default FileLoader implementation

func NewLoader

func NewLoader() *DefaultLoader

NewLoader returns default FileLoader implementation.

func (DefaultLoader) Load

func (d DefaultLoader) Load(base string) ([]string, error)

Load loads files found in the base path for processing.

type DefaultRenderer

type DefaultRenderer struct {
	// contains filtered or unexported fields
}

DefaultRenderer is the default REnderer implementation

func NewDefaultRenderer

func NewDefaultRenderer() *DefaultRenderer

NewDefaultRenderer returns default Renderer implementation

func (*DefaultRenderer) After

func (d *DefaultRenderer) After(root string) error

After copies relevant static files to the generated site

func (*DefaultRenderer) Before

func (d *DefaultRenderer) Before(root string) error

Before loads configurations and prepare rendering stuffs

func (*DefaultRenderer) Render

func (d *DefaultRenderer) Render(root string, pages PageList, opts ...interface{}) error

Render builds a static site

type FileLoader

type FileLoader interface {
	Load(string) ([]string, error)
}

FileLoader loads files needed for processing. the filepaths can be relative or absolute.

type FrontMatter

type FrontMatter interface {
	Parse(io.Reader) (front map[string]interface{}, body io.Reader, err error)
}

FrontMatter extracts frontmatter from a text file

type Generator

type Generator interface {
	FileLoader
	FrontMatter
	Renderer
}

Generator is a static site generator

type HandlerFunc

type HandlerFunc func(string) (map[string]interface{}, error)

HandlerFunc is an interface for a function that process front matter text.

type Matter

type Matter struct {
	// contains filtered or unexported fields
}

Matter is all what matters here.

func NewJSON

func NewJSON(opts ...string) *Matter

NewJSON returns a new FrontMatter implementation with support for json frontmatter. default delimiters is ---

func NewYAML

func NewYAML(opts ...string) *Matter

NewYAML returns a new FrontMatter implementation with support for yaml frontmatter. default delimiters is ---

func (*Matter) Handle

func (m *Matter) Handle(delim string, fn HandlerFunc)

Handle registers a handler for the given frontmatter delimiter

func (*Matter) Parse

func (m *Matter) Parse(input io.Reader) (front map[string]interface{}, body io.Reader, err error)

Parse parses the input and extract the frontmatter

type Page

type Page struct {
	Path    string
	Body    io.Reader
	ModTime time.Time
	Data    interface{}
}

Page is a represantation of text document

func (*Page) HTML

func (p *Page) HTML() template.HTML

HTML returns body text as html.

type PageList

type PageList []*Page

PageList is a collection of pages

func (PageList) Len

func (p PageList) Len() int

func (PageList) Less

func (p PageList) Less(i, j int) bool

func (PageList) Swap

func (p PageList) Swap(i, j int)

type Renderer

type Renderer interface {
	Before(root string) error
	Render(root string, pages PageList, opts ...interface{}) error
	After(root string) error
}

Renderer generates static pages