bock 🍺

A small personal Markdown and git-powered wiki I wrote to teach myself Go. You can see it in action here.

I have old Node and Python versions of this as well for giggles.

Usage

See the releases page for a few pre-built binaries.

Here's how you can run from source:

# Clone repo
git clone https://github.com/afreeorange/bock.git

# Now point it at a git repository full of Markdown files
# and tell it where to generate the output. You need to use
# absolute paths for now.
go run --tags "fts5" . --in=/path/to/repo --out=/path/to/output --without-revisions

# If your article repository is managed by git, you can omit
# that last flag to generate ✨article revisions✨
go run --tags "fts5" . --in=/path/to/repo --out=/path/to/output

Add a --help flag to see some more options.

Terminology and Setup

An Entity is either

• An Article, a Markdown file ending in .md somewhere in your article repository, or
• A Folder, which is exactly what you think it is. You can organize your articles into folders at any depth.
• A Revision, which is a git commit that modifies an Article.

Other stuff:

• The name of the Markdown file is the title of the article and will be served at a simplified URI with underscores. For example,
  • /Notes on Deleuze.md will be served at /Notes_on_Deleuze
  • /Tech Stuff/OpenBSD/pf Notes.md will be served at /Tech_Stuff/OpenBSD/pf_Notes
• The root of the generated wiki will always redirect to /Home (for now) so you will need a Home.md.
  • You'll be warned if you don't have one.
  • It will be generated if you don't have one.
• The paths raw, revisions, random, and archive are reserved. So, for example, don't create a raw.md anywhere. It will be overwritten.
• You can place static assets in __assets in your article repository. You can reference all assets in there in your Markdown files prefixed with /assets (e.g. __assets/some-file.jpg → /assets/some-file.jpg). Here's an example.
• Any dotfiles or dotfolders are ignored when generating the entity-tree.
  • This includes node_modules. See this file for other things. It's a small list.

That's really about it.

What It Does

The first command in the "Usage" section will generate the following (using this article as an example):

• Every Markdown article in your repository rendered as HTML, Raw Markdown, and JSON
• A listing of all revisions for each article, if applicable. Some articles can be untracked and they will be annotated as such.
• Each article's revision rendered as HTML and Raw Markdown (Unless you set -R=false. Things will go much faster too!)
• Each folder's structure in HTML and JSON
• An archive page that lets you search your articles thanks to SQLite and SQL.js
• A Homepage (if it doesn't exist as Home.md) at /Home
• A page that redirects to some random article at /random
• An index page that redirects to /Home
• A 404 Page at /404.html

A giant work in progress but works pretty well for me so far. Uses a baby implementation of Go's WaitGroups so will be slow on older machines or those with less memory.

Upcoming Features

• Recently added articles
• Recently updated articles
• Articles that have not been checked in! "Warning you have x untracked articles...."
• Revision Search in DB
• Categories/Tags
• Frontmatter support
• Local development server with live-reloading
• Customizable Templates with config JSON/YAML
• Option to disable revision histories
• Better/finer concurrency control
• Table of Contents
• Treeviews in CSS
• MathJAX Support
  • Self-hosted MathJAX
• Password-protected articles?
• SQLite Driver without CGO? Appears to be slower but I don't care.

---

Other Notes

	go func() {
		for {
			log.Printf("Number of goroutines: %d", runtime.NumGoroutine())
			time.Sleep(1 * time.Second)
		}
	}()

• GoReleaser and Image for CircleCI
• Stricter formatting
• Lovely stuff for CLIs
• You Don't Need a Library for File Walking in Go
• gojekyll
• gostatic
• A Guide to Build awesome CLIs