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:

  1. 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
    
  2. 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
    
  3. 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
    
  4. 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
    
  5. 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
    
  6. 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
    
  7. 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:

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.
  • 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.
  • 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, and NOT operators.
  • Wildcard: Filter files using path wildcards (*, ?, etc.)
Other
  • DevServer: Simple framework for building, updating, and viewing your site.
  • Harness: Unit test harness for verifying Goldsmith plugins and filters.
Expand ▾ Collapse ▴

Documentation

Overview

    Package goldsmith generates static websites.

    Index

    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

      func (*Context) CreateFileFromAsset(sourcePath, dataPath string) (*File, error)

        CreateFileFromAsset creates a new file instance from the provided file path.

        func (*Context) CreateFileFromData

        func (*Context) CreateFileFromData(sourcePath string, data []byte) *File

          CreateFileFrom data creates a new file instance from the provided data buffer.

          func (*Context) DispatchAndCacheFile

          func (context *Context) DispatchAndCacheFile(outputFile *File, inputFiles ...*File)

            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

            func (context *Context) DispatchFile(file *File)

              DispatchFile causes the file to get passed to the next link in the chain.

              func (*Context) Filter

              func (context *Context) Filter(filters ...Filter) *Context

                Specify internal filter(s) that exclude files from being processed.

                func (*Context) RetrieveCachedFile

                func (context *Context) RetrieveCachedFile(outputPath string, inputFiles ...*File) *File

                  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 {
                  	Meta map[string]interface{}
                  	// contains filtered or unexported fields
                  }

                    File represents in-memory or on-disk files in a chain.

                    func (*File) Dir

                    func (file *File) Dir() string

                      Dir returns the containing directory of the file.

                      func (*File) Ext

                      func (file *File) Ext() string

                        Ext returns the extension of the file.

                        func (*File) GoString

                        func (file *File) GoString() string

                          Returns value for string formatting.

                          func (*File) ModTime

                          func (file *File) ModTime() time.Time

                            ModTime returns the time of the file's last modification.

                            func (*File) Name

                            func (file *File) Name() string

                              Name returns the base name of the file.

                              func (*File) Path

                              func (file *File) Path() string

                                Path returns the file path relative to the source directory.

                                func (*File) Read

                                func (file *File) Read(data []byte) (int, error)

                                  Read reads file data into the provided buffer.

                                  func (*File) Rename

                                  func (file *File) Rename(path string)

                                    Rename modifies the file path relative to the source directory.

                                    func (*File) Seek

                                    func (file *File) Seek(offset int64, whence int) (int64, error)

                                      Seek updates the file pointer to the desired position.

                                      func (*File) Size

                                      func (file *File) Size() int64

                                        Size returns the file length in bytes.

                                        func (*File) WriteTo

                                        func (file *File) WriteTo(writer io.Writer) (int64, error)

                                          Write writes file data into the provided writer.

                                          type Filter

                                          type Filter interface {
                                          	Name() string
                                          	Accept(file *File) bool
                                          }

                                            Filter is used to determine which files should continue in the chain.

                                            type Finalizer

                                            type Finalizer interface {
                                            	Finalize(context *Context) error
                                            }

                                              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 Begin

                                                func Begin(sourceDir string) *Goldsmith

                                                  Begin starts a chain, reading the files located in the source directory as input.

                                                  func (*Goldsmith) Cache

                                                  func (goldsmith *Goldsmith) Cache(cacheDir string) *Goldsmith

                                                    Cache enables caching in cacheDir for the remainder of the chain.

                                                    func (*Goldsmith) Chain

                                                    func (goldsmith *Goldsmith) Chain(plugin Plugin) *Goldsmith

                                                      Chain links a plugin instance into the chain.

                                                      func (*Goldsmith) Clean

                                                      func (goldsmith *Goldsmith) Clean(clean bool) *Goldsmith

                                                        Clean enables or disables removal of leftover files in the target directory.

                                                        func (*Goldsmith) End

                                                        func (goldsmith *Goldsmith) End(targetDir string) []error

                                                          End stops a chain, writing all recieved files to targetDir as output.

                                                          func (*Goldsmith) FilterPop

                                                          func (goldsmith *Goldsmith) FilterPop() *Goldsmith

                                                            FilterPop pops a filter instance from the chain's filter stack.

                                                            func (*Goldsmith) FilterPush

                                                            func (goldsmith *Goldsmith) FilterPush(filter Filter) *Goldsmith

                                                              FilterPush pushes a filter instance on the chain's filter stack.

                                                              type Initializer

                                                              type Initializer interface {
                                                              	Initialize(context *Context) error
                                                              }

                                                                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.

                                                                  type Processor

                                                                  type Processor interface {
                                                                  	Process(context *Context, file *File) error
                                                                  }

                                                                    Processor allows for optional processing of files passing through a plugin.