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.goare the test files; a few library functions are defined inwiki_test.go.*_cmd.goare the files implementing the various subcommands with matching namesaccounts.goimplements the webfinger code to fetch fediverse account link destinations with the URI provided by webfingeradd_append.goimplements the/addand/appendhandlersarchive.goimplements the/archivehandlerchanges.goimplements the "notifications": the automatic addition of links to index, changes and hashtag files when pages are editeddiff.goimplements the/diffhandleredit_save.goimplements the/editand/savehandlersfeed.goimplements the feed for a page based on the links it listsindex.goimplements the index of all the hashtagslanguages.goimplements the language detectionlinks.goimplements link parsing, backlinks and related functions for templatespage.goimplements the page loading and savingparser.goimplements the Markdown parsingpreview.goimplements the/previewhandlermigrate.goimplements database setup and migrationsearch.goimplements the/searchhandlersitemap.goimplements the/sitemaphandlertemplates.goimplements template loading and reloadingtokenizer.goimplements tokenising of the query stringtree.goimplements the tree collection and related functions for templatesupload_drop.goimplements the/uploadand/drophandlersview.goimplements the/viewhandlerwalk.goimplements the various file system traversalswatch.goimplements the filesystem notification watchwiki.goimplements 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