README
¶
Goldsmith
Goldsmith is a fast and easily extensible static website generator written in Go. In contrast to many other generators, Goldsmith does not force any design paradigms or file organization rules on the user, making it possible to generate anything from blogs to image galleries using the same tool.
Tutorial
Goldsmith does not use any configuration files, and all behavior customization happens in code. Goldsmith uses the builder pattern to establish a chain, which modifies files as they pass through it. Although the Goldsmith is short and (hopefully) easy to understand, it is often best to learn by example:
-
Start by copying files from a source directory to a destination directory (the simplest possible use case):
goldsmith. Begin(srcDir). // read files from srcDir End(dstDir) // write files to dstDir -
Now let's convert any Markdown files to HTML fragments (while still copying the rest), using the Markdown plugin:
goldsmith. Begin(srcDir). // read files from srcDir Chain(markdown.New()). // convert *.md files to *.html files End(dstDir) // write files to dstDir -
If we have any front matter in our Markdown files, we need to extract it using the, FrontMatter plugin:
goldsmith. Begin(srcDir). // read files from srcDir Chain(frontmatter.New()). // extract frontmatter and store it as metadata Chain(markdown.New()). // convert *.md files to *.html files End(dstDir) // write files to dstDir -
Next, we should run our barebones HTML through a template to add elements like a header, footer, or a menu; for this we can use the Layout plugin:
goldsmith. Begin(srcDir). // read files from srcDir Chain(frontmatter.New()). // extract frontmatter and store it as metadata Chain(markdown.New()). // convert *.md files to *.html files Chain(layout.New()). // apply *.gohtml templates to *.html files End(dstDir) // write files to dstDir -
Now, let's minify our files to reduce data transfer and load times for our site's visitors using the Minify plugin:
goldsmith. Begin(srcDir). // read files from srcDir Chain(frontmatter.New()). // extract frontmatter and store it as metadata Chain(markdown.New()). // convert *.md files to *.html files Chain(layout.New()). // apply *.gohtml templates to *.html files Chain(minify.New()). // minify *.html, *.css, *.js, etc. files End(dstDir) // write files to dstDir -
Debugging problems in minified code can be tricky, so let's use the Condition filter to make minification occur only when we are ready for distribution.
goldsmith. Begin(srcDir). // read files from srcDir Chain(frontmatter.New()). // extract frontmatter and store it as metadata Chain(markdown.New()). // convert *.md files to *.html files Chain(layout.New()). // apply *.gohtml templates to *.html files FilterPush(condition.New(dist)). // push a dist-only conditional filter onto the stack Chain(minify.New()). // minify *.html, *.css, *.js, etc. files FilterPop(). // pop off the last filter pushed onto the stack End(dstDir) // write files to dstDir -
Now that we have all of our plugins chained up, let's look at a complete example which uses DevServer to bootstrap a complete development sever which automatically rebuilds the site whenever source files are updated.
package main import ( "flag" "log" "github.com/FooSoft/goldsmith" "github.com/FooSoft/goldsmith-components/devserver" "github.com/FooSoft/goldsmith-components/filters/condition" "github.com/FooSoft/goldsmith-components/plugins/frontmatter" "github.com/FooSoft/goldsmith-components/plugins/layout" "github.com/FooSoft/goldsmith-components/plugins/markdown" "github.com/FooSoft/goldsmith-components/plugins/minify" ) type builder struct { dist bool } func (b *builder) Build(srcDir, dstDir, cacheDir string) { errs := goldsmith. Begin(srcDir). // read files from srcDir Chain(frontmatter.New()). // extract frontmatter and store it as metadata Chain(markdown.New()). // convert *.md files to *.html files Chain(layout.New()). // apply *.gohtml templates to *.html files FilterPush(condition.New(b.dist)). // push a dist-only conditional filter onto the stack Chain(minify.New()). // minify *.html, *.css, *.js, etc. files FilterPop(). // pop off the last filter pushed onto the stack End(dstDir) // write files to dstDir for _, err := range errs { log.Print(err) } } func main() { port := flag.Int("port", 8080, "server port") dist := flag.Bool("dist", false, "final dist mode") flag.Parse() devserver.DevServe(&builder{*dist}, *port, "content", "build", "cache") }
Samples
Below are some examples of Goldsmith usage which can used to base your site on:
- Basic Sample: a great starting point, this is the sample site from the tutorial.
- Bootstrap Sample: a slightly more advanced sample using Bootstrap.
- FooSoft.net: I've been "dogfooding" Goldsmith by using it to build my homepage for years.
Components
A growing set of plugins, filters, and other tools are provided to make it easier to get started with Goldsmith.
Plugins
- Absolute: Convert relative HTML file references to absolute paths.
- Breadcrumbs: Generate metadata required to build breadcrumb navigation.
- Collection: Group related pages into named collections.
- Document: Enable simple DOM modification via an API similar to jQuery.
- Forward: Create simple redirections for pages that have moved to a new URL.
- FrontMatter: Extract the JSON, YAML, or TOML metadata stored in your files.
- Index: Create metadata for directory file listings and generate directory index pages.
- Layout: Transform your HTML files with Go templates.
- LiveJs: Inject JavaScript code to automatically reload pages when modified.
- Markdown: Render Markdown documents as HTML fragments.
- Minify: Remove superfluous data from a variety of web formats.
- Pager: Split arrays of metadata into standalone pages.
- Summary: Extract summary and title metadata from HTML files.
- Syndicate: Generate RSS, Atom, and JSON feeds from existing metadata.
- Syntax: Enable syntax highlighting for pre-formatted code blocks.
- Tags: Generate tag clouds and indices from file metadata.
- Thumbnail: Build thumbnails for a variety of common image formats.
Filters
- Condition: Filter files based on a single condition.
- Operator: Join filters using
logical
AND,OR, andNOToperators. - Wildcard: Filter files using path
wildcards (
*,?, etc.)
Other
Documentation
¶
Overview ¶
Package goldsmith generates static websites.
Index ¶
- type Context
- func (self *Context) CreateFileFromAsset(sourcePath, dataPath string) (*File, error)
- func (self *Context) CreateFileFromReader(sourcePath string, reader io.Reader) (*File, error)
- func (self *Context) DispatchAndCacheFile(outputFile *File, inputFiles ...*File)
- func (self *Context) DispatchFile(file *File)
- func (self *Context) Filter(filters ...Filter) *Context
- func (self *Context) RetrieveCachedFile(outputPath string, inputFiles ...*File) *File
- func (self *Context) Threads(threads int) *Context
- type File
- func (self *File) CopyProps(file *File)
- func (self *File) Dir() string
- func (self *File) Ext() string
- func (self *File) GoString() string
- func (self *File) ModTime() time.Time
- func (self *File) Name() string
- func (self *File) Path() string
- func (self *File) Prop(name string) (Prop, bool)
- func (self *File) PropOrDefault(name string, valueDef Prop) Prop
- func (self *File) Props() PropMap
- func (self *File) Read(data []byte) (int, error)
- func (self *File) Rename(path string)
- func (self *File) Rewrite(reader io.Reader) error
- func (self *File) Seek(offset int64, whence int) (int64, error)
- func (self *File) SetProp(name string, value Prop)
- func (self *File) Size() int64
- func (self *File) WriteTo(writer io.Writer) (int64, error)
- type Filter
- type Finalizer
- type Goldsmith
- func (self *Goldsmith) Cache(cacheDir string) *Goldsmith
- func (self *Goldsmith) Chain(plugin Plugin) *Goldsmith
- func (self *Goldsmith) Clean(clean bool) *Goldsmith
- func (self *Goldsmith) End(targetDir string) []error
- func (self *Goldsmith) FilterPop() *Goldsmith
- func (self *Goldsmith) FilterPush(filter Filter) *Goldsmith
- type Initializer
- type Plugin
- type Processor
- type Prop
- type PropMap
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context corresponds to the current link in the chain and provides methods that enable plugins to inject new files into the chain.
func (*Context) CreateFileFromAsset ¶
CreateFileFromAsset creates a new file instance from the provided file path.
func (*Context) CreateFileFromReader ¶
CreateFileFrom data creates a new file instance from the provided data buffer.
func (*Context) DispatchAndCacheFile ¶
DispatchAndCacheFile caches the file data (excluding the metadata), taking dependencies on any input files that are needed to generate it, and then passes it to the next link in the chain.
func (*Context) DispatchFile ¶
DispatchFile causes the file to get passed to the next link in the chain.
func (*Context) RetrieveCachedFile ¶
RetrieveCachedFile looks up file data (excluding the metadata), given an output path and any input files that are needed to generate it. The function will return nil if the desired file is not found in the cache.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File represents in-memory or on-disk files in a chain.
type Finalizer ¶
Finalizer allows for optional finalization of a plugin after all files queued in the chain have passed through it.
type Goldsmith ¶
type Goldsmith struct {
// contains filtered or unexported fields
}
Goldsmith chainable context.
func (*Goldsmith) Clean ¶
Clean enables or disables removal of leftover files in the target directory.
func (*Goldsmith) FilterPush ¶
FilterPush pushes a filter instance on the chain's filter stack.
type Initializer ¶
Initializer is used to optionally initialize a plugin and to specify a filter to be used for determining which files will be processed.
type Plugin ¶
type Plugin interface {
Name() string
}
Plugin contains the minimum set of methods required on plugins. Plugins can also optionally implement Initializer, Processor, and Finalizer interfaces.
Source Files