static

README

static

Static is a package for generating static websites from any Go web app that uses net/http.

Why

Building static websites with existing frameworks like middleman is easy, but large websites can be slow. hugo is a popular option if you need to convert content using templates, but not if you have a go web app that you want to make static.

static helps you use build static websites that are dynamically generated from sources like RSS feeds, databases, APIs, etc by calling each handler registered and saving the output as files.

Go docs

Get the go docs at: godoc.org/4d63.com/static

Install

go get 4d63.com/static

import "4d63.com/static"

Usage

Call Build with a http.Handler, a []string of paths to build to static files, and a callback for printing progress and errors which are communicated via events. The event handler can be nil but it's the only way you'll find out if there's an error building a path.

options := static.DefaultOptions
static.Build(options, handler, paths, func (e static.Event) {
  log.Println(e)
})

Options

Instead of using the default Options you can define your own.

options := static.Options{
  OutputDir:   "build",
  Concurrency: 50,
  DirFilename: "index.html",
}
static.Build(options, handler, paths, func (e static.Event) {
  log.Println(e)
})

Simple Example

Fire up the sample below. Running the Hello World web server is as you'd expect go run *.go, and then building the static version is as simple as go run *.go -build.

package main

import (
  "net/http"
  "4d63.com/static"
)

var build bool

func init() {
  flag.BoolVar(&build, "build", false, "Build the website to static files rather than run the web server.")
  flag.Parse()
}

func main() {
  handler := http.NewServeMux()
  paths := []string{}

  paths = append(paths, "/")
  handler.HandleFunc("/", func(w http.ResponseWriter, r *http.Requests) {
    fmt.Fprintf(w, "Hello %s!", r.URL.Path)
  })

  if build {
    options := static.DefaultOptions
    static.Build(options, handler, paths, func (e static.Event) {
      log.Println(e)
    })
  } else {
    s := &http.Server{Addr: ":8080", Handler: handler}
    log.Fatal(s.ListenAndServe())
  }
}

Typical Example

See github.com/leighmcculloch/readprayrepeat.com.

Documentation

Overview

Package static generates websites from any Go web app that uses `net/http`.

Index

• Variables
• func Build(o Options, h http.Handler, paths []string, eh EventHandler)
• func BuildSingle(o Options, h http.Handler, path string) (statusCode int, outputPath string, err error)
• type Action
• type Event
  • func (e Event) String() string
• type EventHandler
• type Options

Examples

• Build
• BuildSingle

Variables

var DefaultOptions = Options{
	OutputDir:   "build",
	Concurrency: 50,
	DirFilename: "index.html",
}

DefaultOptions contain the default recommended Options.

Functions

func Build

func Build(o Options, h http.Handler, paths []string, eh EventHandler)

Build the paths. Uses the http.Handler to get the response for each path, and writes that response to a file with it's respective path in the OutputDir specified in the Options. Does so concurrently as defined in the Options, and calls the EventHandler for every path with an Event that states that the path was built and if an error occurred. EventHandler may be nil.

Example

package main

import (
	"fmt"
	"net/http"
	"path"

	"4d63.com/static"
)

func main() {
	handler := http.NewServeMux()
	paths := []string{}

	handler.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello %s!", path.Base(r.URL.Path))
	})

	paths = append(paths, "/world")

	static.Build(static.DefaultOptions, handler, paths, func(e static.Event) {
		fmt.Println(e)
	})

}

Output:

Action: build, Path: /world, StatusCode: 200, OutputPath: build/world

func BuildSingle

func BuildSingle(o Options, h http.Handler, path string) (statusCode int, outputPath string, err error)

BuildSingle builds a single path. It uses the http.Handler to get the response for each path, and writes that response to a file with it's respective path in the OutputDir specified in the Options. Returns the HTTP status code returned by the handler, the output path written to and an error if one occurs.

Example

package main

import (
	"fmt"
	"net/http"
	"path"

	"4d63.com/static"
)

func main() {
	handler := http.NewServeMux()

	handler.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello %s!", path.Base(r.URL.Path))
	})

	statusCode, outputPath, err := static.BuildSingle(static.DefaultOptions, handler, "/world")
	fmt.Printf("Built: /world, StatusCode: %d, OutputPath: %v, Error: %v", statusCode, outputPath, err)

}

Output:

Built: /world, StatusCode: 200, OutputPath: build/world, Error: <nil>

Types

type Action

type Action string

Action is something taken place, captured in an Event.

const (
	// BUILD is the building of a path.
	BUILD Action = "build"
)

type Event

type Event struct {
	// The action taken place on the path.
	Action Action
	// The path the action has taken place on.
	Path string
	// The HTTP status code returned when the path was built.
	StatusCode int
	// The output path where the output of the action was written to.
	OutputPath string
	// An error if an error occurred while performing the action, otherwise nil.
	Error error
}

Event represents action has taken place for a path in the build process, and includes an error if an error occurred while the action took place.

func (Event) String

func (e Event) String() string

A simple string representation of an Event in the format:

Action: build, Path: <path>, StatusCode: 200|404|etc, OutputPath: <output-path>

And when the Event has an error:

Action: build, Path: <path>, StatusCode: 200|404|etc, OutputPath: <output-path>, Error: <error>

type EventHandler

type EventHandler func(event Event)

EventHandler is a function that will handle Event's generated by the Build process.

type Options

type Options struct {
	// The directory where files will be written when building.
	OutputDir string
	// The number of files that will be built concurrently.
	Concurrency int
	// The filename to use when saving directory paths. e.g. index.html
	DirFilename string
}

Options for configuring the behavior of the Build functions. Get the default options with DefaultOptions.