Goldsmith

Goldsmith is a fast and easily extensible static website generator written in Go. In contrast to other generators, Goldsmith does not force any design paradigms or file organizational schemes on the user, making it possible to create anything from blogs to image galleries using the same tool.

Tutorial

Goldsmith does not use any configuration files, and all generation behavior is described through 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, I find it is best to learn by example:

• Start by copying files from a source directory to a destination directory (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 (while 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 frontmatter in our Markdown files, we should 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 want to run our barebones HTML through a template to add a header, footer, and 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 annoying, so let's use the Condition filter to make it happen only when we are ready for final 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: the source for my homepage, using most plugins and filters.

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 enable breadcrumb navigation.
• Collection: Group related pages into named collections.
• Document: Enable simple DOM modification via an API similar to jQuery.
• FrontMatter: Extract the metadata stored in your files.
• Index: Create metadata for file listings and generate directory index pages.
• Layout: Transform your HTML with Go templates.
• LiveJs: Inject code to automatically reload pages when they are modified.
• Markdown: Render Markdown documents to HTML fragments.
• Minify: Remove superfluous data from a variety of web formats.
• Pager: Split arrays of metadata into standalone pages.
• Summary: Generate summary and title metadata for HTML files.
• Syntax: Generate syntax highlighting for preformatted code blocks.
• Tags: Build tag clouds from file metadata.
• Thumbnail: Generate 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 generating and viewing your site.
• Harness: Unit test harness for Goldsmith plugins and filters.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.