ephemeris

README

• Ephemeris
  • Chronicle History
  • Chronicle Migration
• Installation
• Blog Generation
  • Blog Format
• Demo Blog
• Hacking
• Feedback

Ephemeris

ephemeris is a golang cli-application which will generate a blog from a collection of static text-files, complete with:

• Archive-view.
• Comment support.
  • See COMMENTS.md for more details on the setup required.
• Tag-cloud.
• RSS feed.

In short it is a static-site-generator, with a focus on blogging rather than being more general-purpose.

The project was primarily written to generate my own blog, which was previously generated with the perl-based chronicle blog compiler.

Chronicle History

The chronicle blog compiler started life as a simple project, but grew in complexity over time. Part of the reason the complexity grew was because the project was very flexible:

• It would read a whole bunch flat files, each of which contained a single blog-post.
• Each parsed post would then be inserted into an SQLite database.
• Using this intermediary database a series of plugins would each execute in turn:
  • The plugins would run SQL-queries to extract posts of interest.
    • For example building a tag-cloud.
    • For example building an archive-view.
    • For example outputting the front-page (10 most recent posts) & associated RSS-feed.
• Once complete the SQLite database would be destroyed.

My expectation was that the use of an intermediary SQLite database would allow content to be generated in a very flexible and extensible fashion, however over time it became apparent that I didn't actually need generation to be very flexible! Most blogs look the same, if you have tags, archives, etc, then that's enough.

In short this project was born to replace chronicle, and perform the things I actually need, rather than what I suspected I might want.

Chronicle Migration

There are some brief notes on migration available.

Installation

You can install from source, by cloning the repository and running:

cd ephemeris/cmd/ephemeris
go build .
go install .

Or you can visit the release page to download a binary.

Blog Generation

The application has only a couple of configuration values, which must be setup in the ephemeris.json file:

    {
      "Posts":    "./posts/",
      "Comments": "./comments/",
      "Prefix":   "http://blog.steve.fi/"
    }

Create a suitable file, then run the application with no arguments:

$ ephemeris

The generated output will be placed in the output/ directory. The configuration-keys in the JSON file are:

• Posts
  • This is the path to the directory containing your blog-posts.
  • The input directory will be searched recursively.
• CommentAPI
  • The URL of the CGI script to receive comments, this is used in the add-comment form.
    • See COMMENTS.md for a discussion of comments.
• Comments
  • This is the path to the directory containing your comments.
  • If this is empty then no comments will be read/inserted into your output
  • See COMMENTS.md for a discussion of comments.
• Prefix
  • This is the URL-prefix used to generate all links.

There is a command-line flag which lets you specify an alternative configuration-file, if you do not wish to use the default. Run ephemeris -help to see details.

Blog Format

The input to this program is a directory tree containing a series of blog-posts. Each post will be stored in a single file, with the entry being prefixed by a header containing meta-data.

A sample post would look like this:

Tags: compilers, assembly, golang, brainfuck
Date: 14/06/2020 19:00
Subject: Writing a brainfuck compiler.
Format: markdown

So last night I had the idea..

There are a few things to note here:

• The date MUST be in the specified format.
• If there is no format: markdown header then the body will be assumed to be HTML.
  • All my early posts were written in HTML.
  • Later I switched to markdown.

As noted the input directory will be processed recursively, which allows you to group posts by topic, year, or in any other way you might prefer. I personally file my entries by year:

data/
  ├── 2005
  ├── 2006
  ..
  ├── 2018
  ├── 2019
  └── 2020

Demo Blog

There is a demo-blog contained within this repository; to use it:

cd _demo
ephemeris

This will generate _demo/output/, and you can then serve that via:

cd output/
python -m SimpleHTTPServer 8000

Finally open http://localhost:8000 in your browser

Hacking

Some brief notes on the theme/output generation are available in HACKING.md.

Feedback

This project is not documented to my usual and preferred standard, no doubt it will improve over time.

However there are many blog packages out there, so I expect this project will only be of interest to those wishing to switch from chronicle.

Steve

Documentation

Overview

Package ephemeris holds some minimal code to create a blog.

A blog is largely made up of blog-posts, which are parsed from a series of text-files.

Each post will have a small header to include tags, date, title, and will be transformed into a simple site.

Index

• type BlogComment
  • func NewBlogComment(path string) (BlogComment, error)
• type BlogEntry
  • func NewBlogEntry(path string, site *Ephemeris) (BlogEntry, error)
  • func (b BlogEntry) MonthName() string
  • func (b BlogEntry) MonthNumber() string
  • func (b BlogEntry) Year() string
• type Ephemeris
  • func New(directory string, commentPath string) *Ephemeris
  • func (e *Ephemeris) Entries(prefix string) ([]BlogEntry, error)

Types

type BlogComment

type BlogComment struct {

	// Author holds the name of the comment-submitter.
	Author string

	// Body holds the body of the comment.
	Body string

	// Icon is generated from the email-address of the submitter.
	// This will be a gravitar link.
	Icon string

	// Link holds any user-submitted URL.
	Link string

	// Date is when the comment was created - this is extracted
	// from the filename of the comment file.
	//
	// The filenames of our comments are "${title}.html.${epoch-seconds}"
	Date time.Time
}

BlogComment is the structure to describe a comment associated with a blog post.

func NewBlogComment

func NewBlogComment(path string) (BlogComment, error)

NewBlogComment reads a comment from the named file, and returns that in a structured form.

type BlogEntry

type BlogEntry struct {
	// Title holds the blog-title.
	Title string

	// Path holds the path to the source-file, on-disk.
	Path string

	// Tags contains a list of tags for the given post.
	Tags []string

	// Content contains the post-body.
	Content string

	// The link to the post.
	Link string

	// Date is when the post was created.
	Date time.Time

	// CommentData contains any comments left upon this entry.
	CommentData []BlogComment
}

BlogEntry holds a single blog-post.

A post has a series of attributes associated with it, as you would expect, such as a title a set of tags, and an associated set of comments.

func NewBlogEntry

func NewBlogEntry(path string, site *Ephemeris) (BlogEntry, error)

NewBlogEntry creates a new blog object from the contents of the given file.

If the file is formatted in Markdown it will be expanded to HTML as part of the creation-process.

func (BlogEntry) MonthName

func (b BlogEntry) MonthName() string

MonthName returns the value of a post's month, as a string, for example "January", "March", etc.

func (BlogEntry) MonthNumber

func (b BlogEntry) MonthNumber() string

MonthNumber returns the value of a post's month, as a two-digit string. For example "01", "11", or "12".

Having a string return value is useful for template interpolation.

func (BlogEntry) Year

func (b BlogEntry) Year() string

Year returns the year of a blog-post, as a string.

Having a string return value is useful for template interpolation.

type Ephemeris

type Ephemeris struct {
	// Root is the source of our posts.
	Root string

	// CommentFiles holds the filenames of comments we've found.
	CommentFiles []string

	// Prefix is the absolute URL prefix for the blog
	Prefix string
}

Ephemeris holds our site structure.

There are only a few settings for the blog, which are the obvious ones - a path pointing to the blog-posts, a URL-prefix for use in generation of the output files, and a list of comment files.

func New

func New(directory string, commentPath string) *Ephemeris

New creates a new site object.

func (*Ephemeris) Entries

func (e *Ephemeris) Entries(prefix string) ([]BlogEntry, error)

Entries returns the blog-entries contained within a site. Note that the input directory is searched recursively for files matching the pattern "*.txt" - this allows you to create entries in sub-directories if you wish.

The entries are returned in a random-order, and contain a complete copy of all the text in the entries. This means that there is a reasonable amount of memory overhead here.