oogway

README

Oogway

Oogway is a simple web server and framework with dynamic content generation using the Go template syntax. It's somewhere in between a static site generator and building a website manually. Templates are automatically updated and JavaScript/TypeScript and Sass can be compiled on the fly, allowing for a quick local dev experience. Oogway can also be used as a library in your Go application to add template functions and custom behaviour.

Installation and Setup

Download the latest release for your platform from the release section on GitHub. Move the binary to a directory in your $PATH (like /usr/local/bin). After that, you can call Oogway from the command line using the oogway command.

• oogway run <path> will start Oogway in the given directory
• oogway init <path> will initialize a new project in the given directory

Or through Docker:

version: "3"

services:
  oogway:
    image: emvicom/oogway
    container_name: oogway
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./demo:/app/data

Configuration

Oogway is configured using a single config.toml file in the project directory.

[server]
host = "localhost" # leave empty for production
port = 8080
shutdown_time = 30 # time before the server is forcefully shut down (optional)
write_timeout = 5 # request write timeout
read_timeout = 5 # request read timeout

[content]
not_found = "/not-found" # specifies the redirect path when a page is not found

# optional configuration to compile sass
[sass]
dir = "assets" # asset directory path
entrypoint = "style.scss" # main sass file
out = "assets/style.css" # compiled output css file path
out_source_map = "assets/style.css.map" # css map file (optional)
watch = true # re-compile files when changed
compiler = "dart" # optional configuration to set the sass compiler filename (if in $PATH) or path (if not in $PATH)

# optional configuration to compile js/ts (see sass configuration for reference)
[js]
dir = "assets"
entrypoint = "entrypoint.js"
out = "assets/bundle.js"
out_source_map = "assets/bundle.js.map"
watch = true

# optional configuration for pirsch.io
[pirsch]
client_id = "..." # optional when using a single access token (no oAuth)
client_secret = "..." # required

After you have configured your project, you can start the server by running the oogway command inside the project directory, or by passing the directory path as the first parameter (like oogway projects/website).

Structuring Your Website

There are three directories that need to be created next to the config.toml.

• assets for static files, like CSS, JavaScript, or images
• content for the page content and routes
• partials for template files that are used on multiple pages

The structure in content is used to create routes. Each page lives inside an index.html. The home page is specified directly in the content directory. Child directories can be reached by their directory name. content/about/index.html for example will be available on /about. You can place other files next to the page to use them to build your content. Like a markdown file which will be rendered on the page, for example.

A meta.toml file can be created besides each index.html for additional configuration.

# sets the priority in the sitemap.xml. Default is 1
sitemap_priority = 0.95

For a demo, check out the demo directory on the GitHub repository.

Template Functions

Oogway comes with a bunch of template functions that can be used to build pages.

Function	Description	Example
config	Exposes the Oogway configuration.	{{config.Server.Host}}
content	Renders a template for given data. Use the route for the template name	{{content "/about" .}}
partial	Renders a partial template for given data. Use the filename without the file extension.	{{partial "head" .}}
markdown	Renders given markdown file as HTML using Go text templates. Use the full path for the template name.	{{markdown "content/blog/article.md" .}}
markdownBlock	Renders a block from given markdown file as HTML using Go text templates. Use the full path for the template name.	{{markdownBlock "content/blog/article.md" "blockName" .}}

For more functions, check out the Sprig documentation.

Using Oogway as a Library

Oogway is designed to be used as a standalone server but also as a library. You can add your own template functions for more advanced functionality and use-cases and embed them into your application. Simply go get it and call it anywhere in your application to boot up a web server.

import (
	"github.com/emvi/oogway"
	
	// other imports...
)

// Define a custom FuncMap to load and render blog articles from an external source.
var customFuncMap = template.FuncMap{
    "blogArticle": loadAndRenderBlogArticle,
}

func main() {
    // Start Oogway from the content/dir directory and pass your own template.FuncMap.
    // The FuncMap will be merged with the default FuncMap of Oogway.
	if err := oogway.Start("content/dir", customFuncMap); err != nil {
		log.Printf("Error starting Oogway: %s", err)
	}
}

Building a release

GOOS=linux GOARCH=amd64 go build -a -installsuffix cgo -ldflags "-s -w" -o oogway cmd/main.go
GOOS=windows GOARCH=amd64 go build -a -installsuffix cgo -ldflags "-s -w" -o oogway.exe cmd/main.go

License

MIT

Documentation

Index

• func Init(path string) error
• func Start(dir string, funcMap template.FuncMap) error
• type Config
• type ContentConfig
• type JSConfig
• type PirschConfig
• type SassConfig
• type ServerConfig

Functions

func Init

func Init(path string) error

Init initializes Oogway inside the specified directory.

func Start

func Start(dir string, funcMap template.FuncMap) error

Start starts the Oogway server for given directory. The second argument is an optional template.FuncMap that will be merged into Oogway's funcmap.

Types

type Config

type Config struct {
	Server  ServerConfig  `toml:"server"`
	Content ContentConfig `toml:"content"`
	Sass    SassConfig    `toml:"sass"`
	JS      JSConfig      `toml:"js"`
	Pirsch  PirschConfig  `toml:"pirsch"`
}

Config is the Oogway application config.

type ContentConfig

type ContentConfig struct {
	NotFound string `toml:"not_found"`
}

ContentConfig is the content configuration.

type JSConfig

type JSConfig struct {
	Entrypoint string `toml:"entrypoint"`
	Dir        string `toml:"dir"`
	Watch      bool   `toml:"watch"`
	Out        string `toml:"out"`
	SourceMap  bool   `toml:"source_map"`
}

JSConfig is the JavaScript compiler configuration.

type PirschConfig

type PirschConfig struct {
	ClientID     string   `toml:"client_id"`
	ClientSecret string   `toml:"client_secret"`
	Subnets      []string `toml:"subnets"`
	Header       []string `toml:"header"`
}

PirschConfig is the configuration for pirsch.io.

type SassConfig

type SassConfig struct {
	Entrypoint   string `toml:"entrypoint"`
	Dir          string `toml:"dir"`
	Watch        bool   `toml:"watch"`
	Out          string `toml:"out"`
	OutSourceMap string `toml:"out_source_map"`
	Compiler     string `toml:"compiler"`
}

SassConfig is the sass compiler configuration.

type ServerConfig

type ServerConfig struct {
	Host            string `toml:"host"`
	Port            int    `toml:"port"`
	ShutdownTimeout int    `toml:"shutdown_time"`
	WriteTimeout    int    `toml:"write_timeout"`
	ReadTimeout     int    `toml:"read_timeout"`
	TLSCertFile     string `toml:"tls_cert_file"`
	TLSKeyFile      string `toml:"tls_key_file"`
}

ServerConfig is the HTTP server configuration.