Skip to content

A small Markdown-based personal wiki in Go 🍺

Notifications You must be signed in to change notification settings

afreeorange/bock

Repository files navigation

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)
		}
	}()