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
- type DefaultLoader
- type DefaultRenderer
- type FileLoader
- type FrontMatter
- type Generator
- type HandlerFunc
- type Matter
- type Page
- type PageList
- 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 ¶
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 JSONHandler ¶
JSONHandler implements HandlerFunc interface. It extracts front matter data from the given string argument by interpreting it as a json string.
func YAMLHandler ¶
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
type DefaultLoader ¶
type DefaultLoader struct{}
DefaultLoader is the default FileLoader implementation
func NewLoader ¶
func NewLoader() *DefaultLoader
NewLoader returns default FileLoader implementation.
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
type FileLoader ¶
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 ¶
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 ¶
NewJSON returns a new FrontMatter implementation with support for json frontmatter. default delimiters is ---
func NewYAML ¶
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