oddmu

command module
v1.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: AGPL-3.0 Imports: 53 Imported by: 0

README

Oddμ: A minimal wiki

Oddμ (or Oddmu) helps you run a minimal wiki, blog, digital garden, memex or Zettelkasten.

Oddμ can be run as a static site generator, processing a directory with Markdown files, turning them into HTML files. HTML templates allow the customisation of headers, footers and styling. There are no plugins.

Oddμ is well suited as a self-hosted, single-user web application. Edit the pages from your phone or laptop, while you're on the move.

If the site is public, use a regular web server as a reverse proxy to make people log in before making changes. As there is no version history, it is not easy to undo vandalism and spam. Only grant write-access to people you trust.

If the site is private, running on a local machine and unreachable from the Internet, no such precautions are necessary.

When Oddμ runs as a web server, it serves all the Markdown files (ending in .md) as web pages. These pages can be edited via the web.

Oddμ adds the following extensions to Markdown: local links [[like this]], hashtags #Like_This and fediverse account links like @alex@alexschroeder.ch.

If your pages don't provide their own title (# title), the file name (without .md) is used as the title. Subdirectories are created as necessary.

Other files can be uploaded and images (ending in .jpg, .jpeg, .png or .webp) can be resized when they are uploaded.

Documentation

This project uses man pages. They are generated from text files using scdoc. These are the files available:

oddmu(1): This man page has a short introduction to Oddmu, its configuration via templates and environment variables, plus pointers to the other man pages.

oddmu(5): This man page talks about Markdown and includes some examples for the non-standard features such as table markup. It also talks about the Oddmu extensions to Markdown: wiki links, hashtags and fediverse account links. Local links must use percent encoding for page names so there is a section about percent encoding. The man page also explains how feeds are generated.

oddmu-releases(7): This man page lists all the Oddmu versions and their user-visible changes.

oddmu-version(1): This man page documents the "version" subcommand which you can use to get the installed Oddmu version.

oddmu-man(1): Oddmu comes with a "man" subcommand to print the manual pages. This man page documents the subcommand, but I guess if you can read the man page, you don't need the "man" subcommand.

Working locally:

oddmu-index(1): This man page documents the "index" subcommand to update the index. This is important for a number of other commands.

oddmu-index(7): This man page documents the database schema used by the index. It is probably only of interested if you want to work with the data yourself, using sqlite3(1).

oddmu-convert(1): This man page documents the "convert" subcommand which you can use to rename, convert and resize images.

oddmu-links(1): This man page documents the "links" subcommand which you can use to get the outgoing links for a page.

oddmu-list(1): This man page documents the "list" subcommand which you can use to get page names and page titles.

oddmu-replace(1): This man page documents the "replace" subcommand to make mass changes to the files much like find(1), grep(1) and sed(1) or perl(1).

oddmu-search(1): This man page documents the "search" subcommand which you can use to build indexes – lists of page links. These are important for feeds.

oddmu-search(7): This man page documents how search and scoring work.

oddmu-toc(1): This man page documents the "toc" subcommand which you can use to generate a table of contents linking to all the headings on the page.

oddmu-tree(1): This man page documents the "tree" subcommand to show the directories and page names in a hierarchy.

Reporting:

oddmu-missing(1): This man page documents the "missing" subcommand to list local links that don't point to any existing pages or files.

oddmu-hashtags(1): This man page documents the "hashtags" subcommand to count the hashtags used from the command line.

Static site generator:

oddmu-html(1): This man page documents the "html" subcommand to generate HTML from Markdown pages from the command line.

oddmu-feed(1): This man page documents the "feed" subcommand to generate a feed from Markdown pages from the command line.

oddmu-sitemap(1): This man page documents the "sitemap" subcommand to generate the static sitemap from the command line.

oddmu-static(1): This man page documents the "static" subcommand to generate an entire static website from the command line, avoiding the need to run Oddmu as a server. Also great for archiving.

oddmu-notify(1): This man page documents the "notify" subcommand to add links to hashtag pages, index and changes for a given page. This is useful when you edit the Markdown files locally.

oddmu-watch(1): This man page documents the "watch" subcommand which watches for changes to the pages and generates HTML files if they change. This useful for previews.

Configuration:

oddmu-templates(5): This man page documents how the templates can be changed (how they must be changed) and lists the attributes available for the various templates.

oddmu-syntax-highlight(7): This man page documents what to add to the "view.html" template in order to support syntax highlighting. This is useful for source code snippets.

System administration:

oddmu-apache(5): This man page documents how to set up the Apache web server as a reverse proxy such that visitors must log in before they can make any changes.

oddmu-caddy(5): This man page documents how to set up the Caddy web server as a reverse proxy such that visitors must log in before they can make any changes.

oddmu-filter(7): This man page documents how to exclude subdirectories from search and archiving.

oddmu-nginx(5): This man page documents how to set up the freenginx web server as a reverse proxy such that visitors must log in before they can make any changes.

oddmu.service(5): This man page documents how to setup a systemd unit and have it manage Oddmu. “Great configurability brings great burdens.”

oddmu.rc(5): This man page documents how to setup on OpenBSD using rcctl and relayd.

oddmu-webdav(5): This man page documents how to set up the Apache web server so that the wiki can be accessed via Web-DAV.

Leaving:

oddmu-export(1): This man page documents how to export all the pages as one RSS feed so that you can import them all into a new platform that doesn't use Markdown files.

Quickstart

You can install the binary directly:

go install src.alexschroeder.ch/oddmu@latest

Change into an empty directory and start it. It creates the database ("index.db") and a few templates (some HTML files).

The program serves the local directory as a wiki on port 8080. Point your browser to http://localhost:8080/ to use it.

The manual pages are built-in, so you can start reading directly:

oddmu man oddmu.1

Getting the sources

If you followed the quick-start instructions above, you already have a copy of the sources in some directory that looks like this: ~/go/pkg/mod/src.alexschroeder.ch/oddmu@* – or you need to clone it from its repository:

git clone https://src.alexschroeder.ch/oddmu.git

Building from source

To build the binary from source:

go build

The man pages are already built. If you want to rebuild them, you need to have scdoc installed.

make docs

The Makefile in the man directory has targets to create Markdown and HTML files.

Running

The working directory is where pages are saved and where templates are loaded from. You can run it in the source directory, right after you have built it:

./oddmu

To read the main man page without installing Oddmu and its man pages:

man -l man/oddmu.1

If you don't have access to the documentation files, you can always read the original text files using the "man" subcommand:

./oddmu man oddmu.1

Installing

This installs oddmu into $HOME/.local/bin and the manual pages into $HOME/.local/share/man/.

make install

This installs oddmu into /usr/local/bin and the manual pages into /usr/local/share/man:

sudo make install PREFIX=/usr/local

Here's an example using GNU Stow to install it into /usr/local/stow in a way that allows you to uninstall it later:

sudo mkdir /usr/local/stow/oddmu
sudo make install PREFIX=/usr/local/stow/oddmu/
cd /usr/local/stow
sudo stow oddmu

Hacking

If you're interested in making changes to the code, here's a high-level introduction to the various source files.

  • *_test.go are the test files; a few library functions are defined in wiki_test.go.
  • *_cmd.go are the files implementing the various subcommands with matching names
  • accounts.go implements the webfinger code to fetch fediverse account link destinations with the URI provided by webfinger
  • add_append.go implements the /add and /append handlers
  • archive.go implements the /archive handler
  • changes.go implements the "notifications": the automatic addition of links to index, changes and hashtag files when pages are edited
  • diff.go implements the /diff handler
  • edit_save.go implements the /edit and /save handlers
  • feed.go implements the feed for a page based on the links it lists
  • index.go implements the index of all the hashtags
  • languages.go implements the language detection
  • links.go implements link parsing, backlinks and related functions for templates
  • page.go implements the page loading and saving
  • parser.go implements the Markdown parsing
  • preview.go implements the /preview handler
  • migrate.go implements database setup and migration
  • search.go implements the /search handler
  • sitemap.go implements the /sitemap handler
  • templates.go implements template loading and reloading
  • tokenizer.go implements tokenising of the query string
  • tree.go implements the tree collection and related functions for templates
  • upload_drop.go implements the /upload and /drop handlers
  • view.go implements the /view handler
  • walk.go implements the various file system traversals
  • watch.go implements the filesystem notification watch
  • wiki.go implements the main function

The code of this package is licensed to you under the AGPL-3.0-or-later license. If you do make changes and your site is public, be aware of section 13:

… if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software.

Templates

The themes folder has some ideas of how to tweak the HTML templates.

Adding new methods to use for template actions

In a template, actions are delimited by {{ and }}. Adding new methods to act on the structures used by the templates is recommended way of extending Oddmu.

The following method can be used for in templates for pages by writing {{.Today}}.

func (p *Page) Today() string {
	return time.Now().Format(time.DateOnly)
}

Any function for *Page returning a thing can be used in templates. For more examples, see page.go, links.go and tree.go.

Changing the markup rules

If you want to change the markup rules, your starting point should be parser.go. Make sure you read the documentation of Go Markdown and note that it offers MathJax support (needs a change to the view.html template so that the MathJax JavaScript gets loaded) and MMark support, and it shows how extensions can be added.

Filenames and URL path

There are some simplifications made. The code doesn't consider the various encodings (UTF-8 NFC on the web vs UTF-8 NFD for HFS+, for example; it also doesn't check for characters in page names that are illegal filenames on the filesystem used).

If you need to access the page name in code that is used from a template, you have to decode the path. See the code in diff.go for an example.

HTTP handlers

The URL paths all have the form /action/directory/pagename (with directory being optional and pagename sometimes being optional). If you need to limit access in Apache or nginx or some other web server acting as a reverse proxy, you can do that. See man oddmu-apache and man oddmu-nginx for some configuration examples.

This is how you can prevent some actions by simply not passing them on to Oddmu, or you can require authentication for certain actions. Furthermore, you can do the same for directories, allowing you to use subdirectories as separate sites, each with their own editors.

Wiki object, database handle

The wiki object contains the database handle.

When running as a server, the database is opened and migrated at startup and the index is updated. New and updated pages are added to the index but deleted pages don't disappear from the index at startup. If you want to be sure, delete the index files (index.db*) before startup. Almost every handler receives this database handle.

When running commands, the database is opened (but not migrated) and closed by the Execute function and passed to the *Cli function (the Cli suffix stands for "command line interface"). This is important for test.

All tests that save data use the setup function to create a directory in testdata for files, including the index. It returns the wiki object to use for the test, including a database handle pointing to that index. Tests for commands pass the object including the database handle to the *Cli function. The setup function also sets up the cleanup code: the database is handled and the directory deleted when the test ends.

Permissions

If you need accounts but you don't want to run a web server as a reverse proxy, use oddauth.

Dependencies

This section lists the non-standard libraries Oddmu uses and their respective licenses (based on the tag in GitHub) and their AI policies ("Looks like No AI" means that Claude did not contribute to the project and there's no dedicated text file for AI code generators).

These are the references from the go.mod file.

github.com/SeriousBug/webp-go-pure is used to encode and decode WebP files. MIT. Looks like No AI.

github.com/abadojack/whatlanggo detects languages in order to set the language tag in templates. This in turn can be used by browsers to get hyphenation right. MIT. Looks like No AI.

github.com/disintegration/imaging is used to resize images. MIT. Looks like No AI.

github.com/edwvee/exiffix is used to rotate images before resizing them if the EXIF data says the image wasn't taken with the default orientation of the camera. This is necessary because after resizing, the EXIF data is gone. MIT. Looks like No AI.

github.com/fsnotify/fsnotify is used to watch the filesystem for changes. BSD-3-Clause. Looks like No AI.

github.com/gabriel-vasile/mimetype is used to sniff the MIME type of files with unknown filename extensions. MIT. Looks like No AI.

github.com/gomarkdown/markdown is used to generate the web pages from Markdown. BSD-2-Clause. Looks like No AI.

github.com/google/subcommands is used for the parsing and documenting of subcommands. Apache-2.0. Looks like No AI.

github.com/hexops/gotextdiff is used to show a compact unified diff on the command line before doing any replacements. BSD-3-Clause. Looks like No AI.

github.com/mb0/diff is used to show the page diffs on the web. BSD-2-Clause. Looks like No AI.

github.com/muesli/reflow is used to wrap the search subcommand output. MIT. Looks like No AI.

modernc.org/sqlite is used for the SQLite database. BSD-3-Clause. AI tainted. 🤖

Indirect dependencies:

github.com/clipperhouse/uax29/v2 is tokeniser based Unicode text segmentation. MIT. AI tainted. 🤖

github.com/dustin/go-humanize humanizes times and sizes. MIT. Looks like No AI.

github.com/google/uuid generates and inspects UUIDs. BSD 3-Clause. Looks like No AI.

github.com/mattn/go-isatty implements isatty. MIT. Looks like No AI.

github.com/mattn/go-runewidth ipmlements wcwidth. MIT. Looks like No AI.

github.com/ncruces/go-strftime implements strftime/strptime. MIT. Looks like No AI.

github.com/remyoudompheng/bigfft is a Big integer multiplication library. BSD 3-Clause. Looks like No AI.

github.com/rwcarlsen/goexif decodes embedded EXIF meta data from image files. BSD 2-Clause. Looks like No AI.

golang.org/x/image contains supplementary image packages. BSD-3-Clause. Looks like No AI.

golang.org/x/sys contains supplemental Go packages for low-level interactions with the operating system. BSD-3-Clause. Looks like No AI.

modernc.org/libc is a partial reimplementation of C libc. BSD-3-Clause. AI tainted. 🤖

modernc.org/mathutil contains supplemental math packages. BSD-3-Clause. Looks like No AI.

modernc.org/memory implements a memory allocator. BSD-3-Clause. AI tainted. 🤖

Bugs

If you spot any, contact me.

References

Writing Web Applications provided the initial code for this wiki.

The repository has a oddmu-1 branch to the first version that had Markdown support.

Documentation

Overview

Oddmu is a wiki web server and a static site generator.

The types exported are the ones needed to write the templates.

Source Files

  • accounts.go
  • add_append.go
  • archive.go
  • changes.go
  • convert_cmd.go
  • diff.go
  • edit_save.go
  • export_cmd.go
  • feed.go
  • feed_cmd.go
  • hashtags_cmd.go
  • html_cmd.go
  • index.go
  • index_cmd.go
  • languages.go
  • links.go
  • links_cmd.go
  • list_cmd.go
  • man_cmd.go
  • migrate.go
  • missing_cmd.go
  • notify_cmd.go
  • page.go
  • parser.go
  • preview.go
  • replace_cmd.go
  • search.go
  • search_cmd.go
  • sitemap.go
  • sitemap_cmd.go
  • static_cmd.go
  • templates.go
  • toc_cmd.go
  • tokenizer.go
  • tree.go
  • tree_cmd.go
  • upload_drop.go
  • version_cmd.go
  • view.go
  • walk.go
  • watch.go
  • watch_cmd.go
  • wiki.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址