blog

README

Blog

This is a web blog and personal homepage engine written in Go. It includes a full-featured web blog (with tags, archive views, etc.) and can serve static web assets, Go HTML templates and Markdown pages.

Features

Zero Configuration

Blog is designed to be extremely easy to run: just give it a path to your website's document root. It doesn't have to exist: it can be created as needed!

blog $HOME/www

See blog -h for command line arguments, for example to make it listen on a different port number.

The blog database is kept on disk as JSON files under the document root.

Dual Template System

Whenever a web request is handled by the Blog program, it checks your user-defined Document Root to serve the file before falling back on its built-in store of "Core Files."

This way, you can copy and override files from the Core Root by creating files with the same names in your Document Root. If you override .layout.gohtml, you can customize the overall web design of your site. You can also override individual templates to customize the look of built-in pages, such as how blog entries are formatted.

The Blog has a built-in page editor that makes it easy to copy and override the core template files.

Render Go HTML and Markdown Files

You can write pages in the Go html/template format (.gohtml) or in GitHub Flavored Markdown (.md). Markdown pages will be rendered to HTML and inserted into your web design layout like normal pages.

Built-in Page Editor

A built-in editor lists all of the pages in your Document Root and the Core Root. You can click on a page to edit it, with the ACE Code Editor offering a rich code editing experience, with syntax highlighting for HTML, Markdown, JavaScript and CSS.

Editing a Core Page and saving it will save an override version in your Document Root.

In the default Blog theme, every page includes a link to edit the page in the Page Editor for logged-in users. The 404 Error handler also provides shortcuts to create a new page at that path.

Setup

# If you're new to Go, set your GOPATH.
export GOPATH="${HOME}/go"

# Clone this repository to your go src folder.
git clone https://github.com/kirsle/blog ~/go/src/github.com/kirsle/blog
cd ~/go/src/github.com/kirsle/blog

# Run the server
make run

# Or to run it manually with go-reload to provide custom options:
./go-reload cmd/blog/main.go [options] [/path/to/document/root]

Docker

This app includes a Dockerfile. Type make docker.build to build the Docker image.

The Docker container uses the user document root at /data/www

docker build -t blog .
docker run --rm --name blog_debug -p 8000:80 -v $(CURDIR)/user-root:/data/www blog

Quick Start

make docker.build
make docker.run

Docker Image

• Exposes port 80 for the web server
• User document root is mounted at /data/www

So to run the Docker image and have it listen on localhost:8000 on the host and bind the user document root to /home/user/www:

docker run -p 8000:80 -v /home/user/www:/data/www blog

You may also run make docker.run to run the Docker image on port 8000 using the ./user-root directory

Recommendation: Redis

It is recommended to use the Redis caching server in conjunction with Blog. Redis helps boost the performance in two main areas:

The JSON database system will cache the JSON documents in Redis, speeding up access time because the filesystem doesn't need to be read each time. If you manually modify a JSON file on disk, it will notice and re-read it next time it's requested.

If you make use of source code blocks in GitHub Flavored Markdown, the Python pygmentize command can render syntax-highlighted HTML from it. Calling this program takes ~0.6s, and a page with many source blocks would take a long time to load. I alleviate this by MD5-hashing and Redis-caching the rendered HTML code to minimize calls to pygmentize.

After you initialize the site, go to the admin settings to enable Redis.

Syntax Highlighting with Pygments

To enable syntax highlighting within Markdown files (like with GitHub Flavored Markdown), install pygments on your system. For example:

# Fedora/RHEL
sudo dnf install python3-pygments python3-pygments-markdown-lexer

# Debian
sudo apt install python3-pygments

Blog will automatically use the pygmentize command if it's available on its $PATH.

License

MIT.

Documentation

Overview

Package blog is a personal website and blogging app.

Index

• type Blog
  • func New(documentRoot, userRoot string) *Blog
  • func (b *Blog) Configure()
  • func (b *Blog) ListenAndServe(address string)
  • func (b *Blog) MustLogin(w http.ResponseWriter, r *http.Request)
  • func (b *Blog) PageHandler(w http.ResponseWriter, r *http.Request)
  • func (b *Blog) Run(address string)
  • func (b *Blog) SetupHTTP()

Types

type Blog

type Blog struct {
	Debug bool

	// DocumentRoot is the core static files root; UserRoot masks over it.
	DocumentRoot string
	UserRoot     string

	Cache caches.Cacher
	// contains filtered or unexported fields
}

Blog is the root application object that maintains the app configuration and helper objects.

func New

func New(documentRoot, userRoot string) *Blog

New initializes the Blog application.

func (*Blog) Configure

func (b *Blog) Configure()

Configure initializes (or reloads) the blog's configuration, and binds the settings in sub-packages.

func (*Blog) ListenAndServe

func (b *Blog) ListenAndServe(address string)

ListenAndServe begins listening on the given bind address.

func (*Blog) MustLogin

func (b *Blog) MustLogin(w http.ResponseWriter, r *http.Request)

MustLogin handles errors from the LoginRequired middleware by redirecting the user to the login page.

func (*Blog) PageHandler

func (b *Blog) PageHandler(w http.ResponseWriter, r *http.Request)

PageHandler is the catch-all route handler, for serving static web pages.

func (*Blog) Run

func (b *Blog) Run(address string)

Run quickly configures and starts the HTTP server.

func (*Blog) SetupHTTP

func (b *Blog) SetupHTTP()

SetupHTTP initializes the Negroni middleware engine and registers routes.