README

static

Linux/OSX Build Status Windows Build Status Codecov Go Report Card Go docs

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

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    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
        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
          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.