Remove link to list from upload.html

It now tries to keep the links sorted.

.gitignore

@@ -1,3 +1,7 @@
-/oddmu
 test.md
 /testdata/
+/oddmu-darwin-*
+/oddmu-linux-*
+/oddmu-windows-*
+/oddmu.exe
+/oddmu

LICENSE

@@ -1,4 +1,4 @@
-This software is Copyright (c) 2015–2023 by Alex Schroeder.
+This software is Copyright (c) 2015–2024 by Alex Schroeder.
 
 This is free software, licensed under:
 

Makefile

@@ -1,28 +1,80 @@
 SHELL=/bin/bash
+PREFIX=${HOME}/.local
+
+.PHONY: help build test run upload docs install priv
 
 help:
 	@echo Help for Oddmu
-	@echo =====================
-	@echo
+	@echo ==============
 	@echo make run
 	@echo "    runs program, offline"
-	@echo
 	@echo make test
-	@echo "    runs the tests"
-	@echo
+	@echo "    runs the tests without log output"
+	@echo make docs
+	@echo "    create man pages from text files"
+	@echo make build
+	@echo "    just build it"
+	@echo make install
+	@echo "    install the files to ~/.local"
+	@echo sudo make install PREFIX=/usr/local
+	@echo "    install the files to /usr/local"
 	@echo make upload
 	@echo "    this is how I upgrade my server"
-	@echo
-	@echo go build
-	@echo "    just build it"
+	@echo make dist
+	@echo "    cross compile for other systems"
+	@echo make clean
+	@echo "    remove built files"
+
+build: oddmu
+
+oddmu: *.go
+	go build
+
+test:
+	rm -rf testdata/*
+	go test -shuffle on .
 
 run:
 	go run .
 
-test:
-	go test
+upload: build
+	rsync --itemize-changes --archive oddmu sibirocobombus.root:/home/oddmu/
+	ssh sibirocobombus.root "systemctl restart oddmu; systemctl restart alex; systemctl restart claudia; systemctl restart campaignwiki; systemctl restart community"
+	@echo Changes to the template files need careful consideration
 
-upload:
-	go build
-	rsync --itemize-changes --archive oddmu oddmu.service *.html README.md sibirocobombus.root:/home/oddmu/
-	ssh sibirocobombus.root "systemctl restart oddmu"
+docs:
+	cd man; make man
+
+install:
+	for n in 1 5 7; do install -D -t ${PREFIX}/share/man/man$$n man/*.$$n; done
+	install -D -t ${PREFIX}/bin oddmu
+
+clean:
+	rm --force oddmu oddmu.exe oddmu-{linux,darwin,windows}-{amd64,arm64}{,.tar.gz}
+	cd man && make clean
+
+dist: oddmu-linux-amd64.tar.gz oddmu-linux-arm64.tar.gz oddmu-darwin-amd64.tar.gz oddmu-windows-amd64.tar.gz
+
+oddmu-linux-amd64: *.go
+	GOOS=linux GOARCH=amd64 go build -o $@
+
+oddmu-linux-arm64: *.go
+	env GOOS=linux GOARCH=arm64 GOARM=5 go build -o $@
+
+oddmu-darwin-amd64: *.go
+	GOOS=darwin GOARCH=arm64 go build -o $@
+
+oddmu.exe: *.go
+	GOOS=windows GOARCH=amd64 go build -o $@
+
+oddmu-windows-amd64.tar.gz: oddmu.exe
+	cd man && make html
+	tar --create --file $@ --transform='s/^/oddmu\//' --exclude='*~' \
+	  $< *.md man/*.[157].{html,md} themes/
+
+%.tar.gz: %
+	tar --create --file $@ --transform='s/^$</oddmu/' --transform='s/^/oddmu\//' --exclude='*~' \
+	  $< *.html Makefile *.socket *.service *.md man/Makefile man/*.1 man/*.5 man/*.7 themes/
+
+priv:
+	sudo setcap 'cap_net_bind_service=+ep' oddmu

README.md

@@ -1,439 +1,386 @@
-# Oddµ: A minimal wiki
+# Oddμ: A minimal wiki
 
-This program runs a wiki. It serves all the Markdown files (ending in
-`.md`) into web pages and allows you to edit them. If your files don't
-provide their own title (`# title`), the file name (without `.md`) is
-used for the title. Subdirectories are created as necessary.
+Oddμ (or Oddmu) helps you run a minimal wiki, blog, digital garden,
+memex or Zettelkasten.
 
-This is a minimal wiki. There is no version history. It's well suited
-as a *secondary* medium: collaboration and conversation happens
-elsewhere, in chat, on social media. The wiki serves as the text
-repository that results from these discussions.
+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.
 
-The wiki lists no recent changes. The expectation is that the people
-that care were involved in the discussions beforehand.
+Oddμ is well suited as a self-hosted, single-user web application,
+when there is no need for collaboration on the site itself. Links and
+email connect you to the rest of the net. The wiki can be public or
+private.
 
-The wiki also produces no feed. The assumption is that announcements
-are made on social media: blogs, news aggregators, discussion forums,
-the fediverse, but humans. There is no need for bots.
+If the site is public, use a regular web server as a proxy to make
+people log in before making changes. As there is no version history,
+it is not possible to undo vandalism and spam. Only grant write-access
+to people you trust.
 
-As you'll see below, the idea is that the webserver handles as many
-tasks as possible. It logs requests, does rate limiting, handles
-encryption, gets the certificates, and so on. The web server acts as a
-reverse proxy and the wiki ends up being a content management system
-with almost no structure – or endless malleability, depending on your
-point of view.
+If the site is private, running on a local machine and unreachable
+from the Internet, no such precautions are necessary.
 
-And last but not least: µ is the letter mu, so Oddµ is usually written
-Oddmu. 🙃
+Oddμ is well suited as a secondary medium for a close-knit group:
+collaboration and conversation happens elsewhere, in chat, on social
+media. The wiki serves as the text repository that results from these
+discussions.
 
-## Markdown
+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.
 
-This wiki uses Markdown. There is no additional wiki markup, most
-importantly double square brackets are not a link. If you're used to
-that, it'll be strange as you need to repeat the name: `[like
-this](like this)`. The Markdown processor comes with a few extensions,
-some of which are enable by default:
+Oddμ adds the following extensions to Markdown: local links `[[like
+this]]`, hashtags `#Like_This` and fediverse account links like
+`@alex@alexschroeder.ch`.
 
-* emphasis markers inside words are ignored
-* tables are supported
-* fenced code blocks are supported
-* autolinking of "naked" URLs are supported
-* strikethrough using two tildes is supported (`~~like this~~`)
-* it is strict about prefix heading rules
-* you can specify an id for headings (`{#id}`)
-* trailing backslashes turn into line breaks
-* definition lists are supported
-* MathJax is supported (but needs a separte setup)
+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.
 
-See the section on
-[extensions](https://github.com/gomarkdown/markdown#extensions) in the
-Markdown library for information on the various extensions.
+Other files can be uploaded and images (ending in `.jpg`, `.jpeg`,
+`.png`, `.heic` or `.webp`) can be resized when they are uploaded
+(resulting in `.jpg`, `.png` or `.webp` files).
 
-A table with footers and a columnspan:
+## Documentation
 
-```text
-Name    | Age
---------|------
-Bob     ||
-Alice   | 23
-========|======
-Total   | 23
-```
+This project uses man(1) pages. They are generated from text files
+using [scdoc](https://git.sr.ht/~sircmpwn/scdoc). These are the files
+available:
 
-A definition list:
+[oddmu(1)](https://alexschroeder.ch/view/oddmu/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.
 
-```text
-Cat
-: Fluffy animal everyone likes
+[oddmu(5)](https://alexschroeder.ch/view/oddmu/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.
 
-Internet
-: Vector of transmission for pictures of cats
-```
+[oddmu-releases(7)](https://alexschroeder.ch/view/oddmu/oddmu-releases.7):
+This man page lists all the Oddmu versions and their user-visible
+changes.
 
-## Templates
+[oddmu-version(1)](https://alexschroeder.ch/view/oddmu/oddmu-version.1):
+This man page documents the "version" subcommand which you can use to
+get the installed Oddmu version.
 
-Feel free to change the templates `view.html` and `edit.html` and
-restart the server. Modifying the styles in the templates would be a
-good start to get a feel for it.
+Working locally:
 
-The first change you should make is to replace the email address in
-`view.html`. 😄
+[oddmu-links(1)](https://alexschroeder.ch/view/oddmu/oddmu-links.1):
+This man page documents the "links" subcommand which you can use to
+get the outgoing links for a page.
 
-The templates can refer to the following properties of a page:
+[oddmu-list(1)](https://alexschroeder.ch/view/oddmu/oddmu-list.1):
+This man page documents the "list" subcommand which you can use to get
+page names and page titles.
 
-`{{.Title}}` is the page title. If the page doesn't provide its own
-title, the page name is used.
+[oddmu-replace(1)](https://alexschroeder.ch/view/oddmu/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).
 
-`{{.Name}}` is the page name. The page name doesn't include the `.md`
-extension.
+[oddmu-search(1)](https://alexschroeder.ch/view/oddmu/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.
 
-`{{.Html}}` is the rendered Markdown, as HTML.
+[oddmu-search(7)](https://alexschroeder.ch/view/oddmu/oddmu-search.7):
+This man page documents how search and scoring work.
 
-`{{printf "%s" .Body}}` is the Markdown, as a string (the data itself
-is a byte array and that's why we need to call `printf`).
+[oddmu-toc(1)](https://alexschroeder.ch/view/oddmu/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.
 
-When calling the `save` action, the page name is take from the URL and
-the page content is taken from the `body` form parameter. To
-illustrate, here's how to edit a page using `curl`:
+Reporting:
 
-```sh
-curl --form body="Did you bring a towel?" \
-  http://localhost:8080/save/welcome
-```
+[oddmu-missing(1)](https://alexschroeder.ch/view/oddmu/oddmu-missing.1):
+This man page documents the "missing" subcommand to list local links
+that don't point to any existing pages or files.
 
-## Non-English hyphenation
+[oddmu-hashtags(1)](https://alexschroeder.ch/view/oddmu/oddmu-hashtags.1):
+This man page documents the "hashtags" subcommand to count the
+hashtags used from the command line.
 
-Automatic hyphenation by the browser requires two things: The style
-sheet must indicate `hyphen: auto` for an HTML element such as `body`,
-and that element must have a `lang` set (usually a two letter language
-code such as `de` for German). This happens in the template files,
-such as `view.html` and `search.html`.
+Static site generator:
 
-If have pages in different languages, the problem is that they all use
-the same template and that's not good. In such cases, it might be
-better to not specificy the `lang` attribute in the template. This
-also disables hyphenation by the browser, unfortunately. It might
-still be better than using English hyphenation patterns for
-non-English languages.
+[oddmu-html(1)](https://alexschroeder.ch/view/oddmu/oddmu-html.1):
+This man page documents the "html" subcommand to generate HTML from
+Markdown pages from the command line.
+
+[oddmu-static(1)](https://alexschroeder.ch/view/oddmu/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)](https://alexschroeder.ch/view/oddmu/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.
+
+Configuration:
+
+[oddmu-templates(5)](https://alexschroeder.ch/view/oddmu/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.
+
+System administration:
+
+[oddmu-apache(5)](https://alexschroeder.ch/view/oddmu/oddmu-apache.5):
+This man page documents how to set up the Apache web server for
+various common tasks such as using logins to limit what visitors can
+edit.
+
+[oddmu-filter(7)](https://alexschroeder.ch/view/oddmu/oddmu-filter.7):
+This man page documents how to exclude subdirectories from search and
+archiving.
+
+[oddmu-nginx(5)](https://alexschroeder.ch/view/oddmu/oddmu-nginx.5):
+This man page documents how to set up the freenginx web server for
+various common tasks such as using logins to limit what visitors can
+edit.
+
+[oddmu.service(5)](https://alexschroeder.ch/view/oddmu/oddmu.service.5):
+This man page documents how to setup a systemd unit and have it manage
+Oddmu. “Great configurability brings great burdens.”
+
+[oddmu-webdav(5)](https://alexschroeder.ch/view/oddmu/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)](https://alexschroeder.ch/view/oddmu/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.
 
 ## Building
 
+To build the binary:
+
 ```sh
 go build
 ```
 
-## Test
+The man pages are already built. If you want to rebuild them, you need
+to have [scdoc](https://git.sr.ht/~sircmpwn/scdoc) installed.
+
+```sh
+make docs
+```
+
+The `Makefile` in the `man` directory has targets to create Markdown
+and HTML files.
+
+As the repository changed URLs a few times (from GitHub, to
+self-hosted using `cgit` to self-hosted using `legit`), there is no
+way to install it using `go install`. You need to `git clone` the
+repository and build it locally.
+
+## Running
 
 The working directory is where pages are saved and where templates are
 loaded from. You need a copy of the template files in this directory.
-Here's how to start it in the source directory:
+
+Here's how to build and run straight from the source directory:
 
 ```sh
 go run .
 ```
 
 The program serves the local directory as a wiki on port 8080. Point
-your browser to http://localhost:8080/ to get started. This is
-equivalent to http://localhost:8080/view/index – the first page
-you'll create, most likely.
+your browser to http://localhost:8080/ to use it.
 
-If you ran it in the source directory, try
-http://localhost:8080/view/README – this serves the README file you're
-currently reading.
-
-## Deploying it using systemd
-
-As root, on your server:
+Once the `oddmu` binary is built, you can run it instead:
 
 ```sh
-adduser --system --home /home/oddmu oddmu
+./oddmu
 ```
 
-Copy all the files into `/home/oddmu` to your server: `oddmu`,
-`oddmu.service`, `view.html` and `edit.html`.
-
-Edit the `oddmu.service` file. These are the three lines you most
-likely have to take care of:
-
-```
-ExecStart=/home/oddmu/oddmu
-WorkingDirectory=/home/oddmu
-Environment="ODDMU_PORT=8080"
-```
-
-Install the service file and enable it:
+To read the main man page witihout installing Oddmu:
 
 ```sh
-ln -s /home/oddmu/oddmu.service /etc/systemd/system/
-systemctl enable --now oddmu
+man -l man/oddmu.1
 ```
 
-Check the log:
+## Installing
+
+This installs `oddmu` into `$HOME/.local/bin` and the manual pages
+into `$HOME/.local/share/man/`.
 
 ```sh
-journalctl --unit oddmu
+make install
 ```
 
-Follow the log:
+Here's an example using [GNU Stow](https://www.gnu.org/software/stow/)
+to install it into `/usr/local/stow` in a way that allows you to
+uninstall it later:
 
 ```sh
-journalctl --follow --unit oddmu
+sudo mkdir /usr/local/stow/oddmu
+sudo make install PREFIX=/usr/local/stow/oddmu/
+cd /usr/local/stow
+sudo stow oddmu
 ```
 
-Edit the first page using `lynx`:
+## Hacking
 
-```sh
-lynx http://localhost:8080/view/index
-```
+If you're interested in making changes to the code, here's a
+high-level introduction to the various source files.
 
-## Web server setup
+- `*_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
+- `highlight.go` implements the bold tags for matches when showing
+  search results
+- `index.go` implements the index of all the hashtags
+- `languages.go` implements the language detection
+- `list.go` implements the file list page
+- `page.go` implements the page loading and saving
+- `parser.go` implements the Markdown parsing
+- `preview.go` implements the `/preview` handler
+- `score.go` implements the page scoring when showing search results
+- `search.go` implements the `/search` handler
+- `snippets.go` implements the page summaries for search results
+- `templates.go` implements template loading and reloading
+- `tokenizer.go` implements the various tokenizers used
+- `upload_drop.go` implements the `/upload` and `/drop` handlers
+- `view.go` implements the `/view` handler
+- `watch.go` implements the filesystem notification watch
+- `wiki.go` implements the main function
 
-HTTPS is not part of the wiki. You probably want to configure this in
-your webserver. I guess you could use stunnel, too. If you're using
-Apache, you might have set up a site like I did, below. In my case,
-that'd be `/etc/apache2/sites-enabled/500-transjovian.conf`:
+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:
 
-```apache
-MDomain transjovian.org
-MDCertificateAgreement accepted
+> … 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.
 
-<VirtualHost *:80>
-    ServerName transjovian.org
-    RewriteEngine on
-    RewriteRule ^/(.*) https://%{HTTP_HOST}/$1 [redirect]
-</VirtualHost>
-<VirtualHost *:443>
-    ServerAdmin alex@alexschroeder.ch
-    ServerName transjovian.org
-    SSLEngine on
+### Changing the markup rules
 
-    RewriteEngine on
-    RewriteRule ^/$ http://%{HTTP_HOST}:8080/view/index [redirect]
-    RewriteRule ^/(view|edit|save|search)/(.*) http://%{HTTP_HOST}:8080/$1/$2 [proxy]
-</VirtualHost>
-```
+If you want to change the markup rules, your starting point should be
+`parser.go`. Make sure you read the documentation of [Go
+Markdown](https://github.com/gomarkdown/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](https://mmark.miek.nl/post/syntax/) support, and it shows how
+extensions can be added.
 
-First, it manages the domain, getting the necessary certificates. It
-redirects regular HTTP traffic from port 80 to port 443. It turns on
-the SSL engine for port 443. It redirects `/` to `/view/index` and any
-path that starts with `/view/`, `/edit/`, `/save/`, `/add/`,
-`/append/` or `/search/` is proxied to port 8080 where the Oddmu
-program can handle it.
+### Filenames and URL path
 
-Thus, this is what happens:
+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).
 
-* The user tells the browser to visit `http://transjovian.org` (on port 80)
-* Apache redirects this to `http://transjovian.org/` by default (still on port 80)
-* Our first virtual host redirects this to `https://transjovian.org/` (encrypted, on port 443)
-* Our second virtual host redirects this to `https://transjovian.org/wiki/view/index` (still on port 443)
-* This is proxied to `http://transjovian.org:8080/view/index` (no on port 8080, without encryption)
-* The wiki converts `index.md` to HTML, adds it to the template, and serves it.
+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.
 
-Restart the server, gracefully:
+### HTTP handlers
 
-```
-apachectl graceful
-```
+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](https://en.wikipedia.org/wiki/Reverse_proxy), you can do that.
+See `man oddmu-apache` and `man oddmu-nginx` for some configuration
+examples.
 
-## Access
+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.
 
-Access control is not part of the wiki. By default, the wiki is
-editable by all. This is most likely not what you want unless you're
-running it stand-alone, unconnected to the Internet.
+### Templates
 
-You probably want to configure this in your webserver. If you're using
-Apache, you might have set up a site like the following.
+The `themes` folder has some ideas of how to tweak the HTML templates.
 
-Create a new password file called `.htpasswd` and add the user "alex":
+### Permissions
 
-```sh
-cd /home/oddmu
-htpasswd -c .htpasswd alex
-```
+An unexplored idea would be to parse a config file that has usernames
+and passwords, groups usernames into roles, and assigns access to the
+various actions based on these roles. This would obviate the need for
+a web server acting as a reverse proxy.
 
-To add more users, don't use the `-c` option or you will overwrite it!
+Then again, not having to care about roles and permissions has been a
+relief.
 
-To add another user:
+## Dependencies
 
-```sh
-htpasswd .htpasswd berta
-```
+This section lists the non-standard libraries Oddmu uses and their
+respective licenses.
 
-To delete remove a user:
+[github.com/gomarkdown/markdown](https://github.com/gomarkdown/markdown)
+is used to generate the web pages from Markdown. BSD-2-Clause.
 
-```sh
-htpasswd -D .htpasswd berta
-```
+[github.com/microcosm-cc/bluemonday](https://github.com/microcosm-cc/bluemonday)
+is used to strip rendered search results of all HTML except for the
+bold tag. Regular HTML generated from pages is *not* sanitized. Don't
+give people you don't trust access to your wiki. BSD-3-Clause.
 
-Modify your site configuration and protect the `/edit/`, `/save/`,
-`/add/` and `/append/` URLs with a password by adding the following to
-your `<VirtualHost *:443>` section:
+[github.com/pemistahl/lingua-go](https://github.com/pemistahl/lingua-go)
+detects languages in order to set the language tag in templates. This
+in turn can be used by browsers to get hyphenation right. Apache-2.0.
 
-```apache
-<LocationMatch "^/(edit|save|add|append)/">
-  AuthType Basic
-  AuthName "Password Required"
-  AuthUserFile /home/oddmu/.htpasswd
-  Require valid-user
-</LocationMatch>
-```
+[github.com/gabriel-vasile/mimetype](https://github.com/gabriel-vasile/mimetype)
+is used to sniff the MIME type of files with unknown filename
+extensions. MIT.
 
-## Serve static files
+[github.com/gen2brain/heic](https://github.com/gen2brain/heic) is used
+to decode HEIC files (the new default file format for photos on
+iPhones). MIT.
 
-If you want to serve static files as well, add a document root to your
-webserver configuration. Using Apache, for example:
+[github.com/gen2brain/webp](https://github.com/gen2brain/webp) is used
+to encode and decode WebP files. MIT.
 
-```apache
-DocumentRoot /home/oddmu/static
-<Directory /home/oddmu/static>
-    Require all granted
-</Directory>
-```
+[github.com/disintegration/imaging](https://github.com/disintegration/imaging)
+is used to resize images. MIT.
 
-Create this directory, making sure to give it a permission that your
-webserver can read (world readable file, world readable and executable
-directory). Populate it with files.
+[github.com/edwvee/exiffix](https://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.
 
-Make sure that none of the static files look like the wiki paths
-`/view/`, `/edit/`, `/save/`, `/add/`, `/append/` or `/search/`. For
-example, create a file called `robots.txt` containing the following,
-tellin all robots that they're not welcome.
+[github.com/google/subcommands](https://github.com/google/subcommands)
+is used for the parsing and documenting of subcommands. Apache-2.0.
 
-```text
-User-agent: *
-Disallow: /
-```
+[github.com/muesli/reflow/wordwrap](https://github.com/muesli/reflow/wordwrap)
+is used to wrap the search subcommand output. MIT.
 
-You site now serves `/robots.txt` without interfering with the wiki,
-and without needing a wiki page.
+[github.com/hexops/gotextdiff](https://github.com/hexops/gotextdiff)
+is used to show a compact unified diff on the command line before
+doing any replacements. BSD-3-Clause.
 
-[Wikipedia](https://en.wikipedia.org/wiki/Robot_exclusion_standard)
-has more information.
+[github.com/sergi/go-diff/diffmatchpatch](https://github.com/sergi/go-diff/diffmatchpatch)
+is used to show the page diffs on the web. MIT.
 
-## Different logins for different access rights
+[github.com/fsnotify/fsnotify](https://github.com/fsnotify/fsnotify)
+is used to watch the filesystem for changes. BSD-3-Clause.
 
-What if you have a site with various subdirectories and each
-subdirectory is for a different group of friends? You can set this up
-using your webserver. One way to do this is to require specific
-usernames (which must have a password in the password file mentioned
-above.
+[golang.org/x/exp/constraints](https://golang.org/x/exp/constraints)
+for the computation of the intersection between two sets of pages.
+BSD-3-Clause.
 
-This requires a valid login by the user "alex" or "berta":
-
-```apache
-<LocationMatch "^/(edit|save)/intetebi/">
-  Require user alex berta
-</LocationMatch>
-```
-
-## Private wikis
-
-Based on the above, you can prevent people from reading the wiki, too.
-The `LocationMatch` must cover the `/view/` URLs. In order to protect
-*everything*, use a [Location directive](https://httpd.apache.org/docs/current/mod/core.html#location)
-that matches everything:
-
-```apache
-<Location />
-  AuthType Basic
-  AuthName "Password Required"
-  AuthUserFile /home/oddmu/.htpasswd
-  Require valid-user
-</Location>
-```
-
-## Customization (with recompilation)
-
-The Markdown parser can be customized and
-[extensions](https://pkg.go.dev/github.com/gomarkdown/markdown/parser#Extensions)
-can be added. There's an example in the
-[usage](https://github.com/gomarkdown/markdown#usage) section. You'll
-need to make changes to the `viewHandler` yourself.
-
-### Render Gemtext
-
-In a first approximation, Gemtext is valid Markdown except for the
-rocket links (`=>`). Here's how to modify the `loadPage` so that a
-`.gmi` file is loaded if no `.md` is found, and the rocket links are
-translated into Markdown:
-
-```go
-func loadPage(name string) (*Page, error) {
-	filename := name + ".md"
-	body, err := os.ReadFile(filename)
-	if err == nil {
-		return &Page{Title: name, Name: name, Body: body}, nil
-	}
-	filename = name + ".gmi"
-	body, err = os.ReadFile(filename)
-	if err == nil {
-		re := regexp.MustCompile(`(?m)^=>\s*(\S+)\s+(.+)`)
-		body = []byte(re.ReplaceAllString(string(body), `* [$2]($1)`))
-		return &Page{Title: name, Name: name, Body: body}, nil
-	}
-	return nil, err
-}
-```
-
-There is a small problem, however: By default, Markdown expects an
-empty line before a list begins. The following change to `renderHtml`
-uses the `NoEmptyLineBeforeBlock` extension for the parser:
-
-```go
-func (p* Page) renderHtml() {
-    // Here is where a new extension is added!
-	extensions := parser.CommonExtensions | parser.NoEmptyLineBeforeBlock
-	markdownParser := parser.NewWithExtensions(extensions)
-	maybeUnsafeHTML := markdown.ToHTML(p.Body, markdownParser, nil)
-	html := bluemonday.UGCPolicy().SanitizeBytes(maybeUnsafeHTML)
-	p.Html = template.HTML(html);
-}
-```
-
-## Understanding search
-
-The index indexes trigrams. Each group of three characters is a
-trigram. A document with content "This is a test" is turned to lower
-case and indexed under the trigrams "thi", "his", "is ", "s i", " is",
-"is ", "s a", " a ", "a t", " te", "tes", "est".
-
-Each query is split into words and then processed the same way. A
-query with the words "this test" is turned to lower case and produces
-the trigrams "thi", "his", "tes", "est". This means that the word
-order is not considered when searching for documents.
-
-This also means that there is no stemming. Searching for "testing"
-won't find "This is a test" because there are no matches for the
-trigrams "sti", "tin", "ing".
-
-These trigrams are looked up in the index, resulting in the list of
-documents. Each document found is then scored. Each of the following
-increases the score by one point:
-
-- the entire phrase matches
-- a word matches
-- a word matches at the beginning of a word
-- a word matches at the end of a word
-- a word matches as a whole word
-
-A document with content "This is a test" when searched with the phrase
-"this test" therefore gets a score of 8: the entire phrase does not
-match but each word gets four points.
-
-Trigrams are sometimes strange: In a text containing the words "main"
-and "rail", a search for "mail" returns a match because the trigrams
-"mai" and "ail" are found. In this situation, the result has a score
-of 0.
-
-## Limitations
-
-Page titles are filenames with `.md` appended. If your filesystem
-cannot handle it, it can't be a page name.
-
-The pages are indexed as the server starts and the index is kept in
-memory. If you have a ton of pages, this surely wastes a lot of
-memory.
+[github.com/stretchr/testify/assert](https://github.com/stretchr/testify/assert)
+is used for testing. MIT.
 
 ## Bugs
 
@@ -443,9 +390,3 @@ If you spot any, [contact](https://alexschroeder.ch/wiki/Contact) me.
 
 [Writing Web Applications](https://golang.org/doc/articles/wiki/)
 provided the initial code for this wiki.
-
-For the proxy stuff, see
-[Apache: mod_proxy](https://httpd.apache.org/docs/current/mod/mod_proxy.html).
-
-For the usernames and password stuff, see
-[Apache: Authentication and Authorization](https://httpd.apache.org/docs/current/howto/auth.html).

RELEASE

@@ -0,0 +1,22 @@
+When preparing a new release
+----------------------------
+
+1. Run tests
+
+2. Update man/oddmu-releases.7.txt
+   - add missing items
+   - change "(unreleased)"
+
+3. make docs
+
+4. Make sure all files are checked in
+
+5. Tag the release and push the tag to all remotes
+
+6. cd man && make upload
+
+7. make dist
+
+8. create a new release at https://github.com/kensanata/oddmu/releases
+
+9. upload the four .tar.gz binaries to the GitHub release

TODO.md

@@ -1,12 +0,0 @@
-Upload files.
-
-Automatically scale or process files.
-
-Post by Delta Chat? That is, allow certain encrypted emails to post.
-
-Convert the existing wiki.
-
-Investigate how to run a multi-linugual wiki where an appropriate
-version of a page is served based on language preferences of the user.
-This is a low priority issue since it's probably only of interest for
-corporate or governmental sites.

accounts.go

@@ -0,0 +1,153 @@
+package main
+
+import (
+	"encoding/json"
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/gomarkdown/markdown/parser"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"sync"
+)
+
+// useWebfinger indicates whether Oddmu looks up the profile pages of fediverse accounts. To enable this, set the
+// environment variable ODDMU_WEBFINGER to "1".
+var useWebfinger = false
+
+// accountStore controlls access to the usernames. Make sure to lock and unlock as appropriate.
+type accountStore struct {
+	sync.RWMutex
+
+	// uris is a map, mapping account names likes "@alex@alexschroeder.ch" to URIs like
+	// "https://social.alexschroeder.ch/@alex".
+	uris map[string]string
+}
+
+// accounts holds the global mapping of accounts to profile URIs.
+var accounts accountStore
+
+// This is called once at startup and therefore does not need to be locked. On every restart, this map starts empty and
+// is slowly repopulated as pages are visited.
+func init() {
+	if os.Getenv("ODDMU_WEBFINGER") == "1" {
+		accounts.uris = make(map[string]string)
+		useWebfinger = true
+	}
+}
+
+// accountLink links a social media accountLink like @accountLink@domain to a profile page like https://domain/user/accountLink. Any
+// accountLink seen for the first time uses a best guess profile URI. It is also looked up using webfinger, in parallel. See
+// lookUpAccountUri. If the lookup succeeds, the best guess is replaced with the new URI so on subsequent requests, the
+// URI is correct.
+func accountLink(p *parser.Parser, data []byte, offset int) (int, ast.Node) {
+	data = data[offset:]
+	i := 1 // skip @ of username
+	n := len(data)
+	d := 0
+	for i < n && (data[i] >= 'a' && data[i] <= 'z' ||
+		data[i] >= 'A' && data[i] <= 'Z' ||
+		data[i] >= '0' && data[i] <= '9' ||
+		data[i] == '@' ||
+		data[i] == '.' ||
+		data[i] == '_' ||
+		data[i] == '-') {
+		if data[i] == '@' {
+			if d != 0 {
+				// more than one @ is invalid
+				return 0, nil
+			} else {
+				d = i + 1 // skip @ of domain
+			}
+		}
+		i++
+	}
+	for i > 1 && (data[i-1] == '.' ||
+		data[i-1] == '-') {
+		i--
+	}
+	if i == 0 || d == 0 {
+		return 0, nil
+	}
+	user := data[0 : d-1] // includes @
+	domain := data[d:i]   // excludes @
+	account := data[1:i]  // excludes @
+	accounts.RLock()
+	uri, ok := accounts.uris[string(account)]
+	defer accounts.RUnlock()
+	if !ok {
+		log.Printf("Looking up %s\n", account)
+		uri = "https://" + string(domain) + "/users/" + string(user[1:])
+		accounts.uris[string(account)] = uri // prevent more lookings
+		go lookUpAccountUri(string(account), string(domain))
+	}
+	link := &ast.Link{
+		AdditionalAttributes: []string{`class="account"`},
+		Destination:          []byte(uri),
+		Title:                data[0:i],
+	}
+	ast.AppendChild(link, &ast.Text{Leaf: ast.Leaf{Literal: data[0 : d-1]}})
+	return i, link
+}
+
+// lookUpAccountUri is called for accounts that haven't been seen before. It calls webfinger and parses the JSON. If
+// possible, it extracts the link to the profile page and replaces the entry in accounts.
+func lookUpAccountUri(account, domain string) {
+	uri := "https://" + domain + "/.well-known/webfinger"
+	resp, err := http.Get(uri + "?resource=acct:" + account)
+	if err != nil {
+		log.Printf("Failed to look up %s: %s", account, err)
+		return
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		log.Printf("Failed to read from %s: %s", account, err)
+		return
+	}
+	var wf webFinger
+	err = json.Unmarshal([]byte(body), &wf)
+	if err != nil {
+		log.Printf("Failed to parse the JSON from %s: %s", account, err)
+		return
+	}
+	uri, err = parseWebFinger(body)
+	if err != nil {
+		log.Printf("Could not find profile URI for %s: %s", account, err)
+	}
+	log.Printf("Found profile for %s: %s", account, uri)
+	accounts.Lock()
+	defer accounts.Unlock()
+	accounts.uris[account] = uri
+}
+
+// link a link in the WebFinger JSON.
+type link struct {
+	Rel  string `json:"rel"`
+	Type string `json:"type"`
+	Href string `json:"href"`
+}
+
+// webFinger is a structure used to unmarshall JSON.
+type webFinger struct {
+	Subject string   `json:"subject"`
+	Aliases []string `json:"aliases"`
+	Links   []link   `json:"links"`
+}
+
+// parseWebFinger parses the web finger JSON and returns the profile page URI. For unmarshalling the JSON, it uses the
+// Link and WebFinger structs.
+func parseWebFinger(body []byte) (string, error) {
+	var wf webFinger
+	err := json.Unmarshal(body, &wf)
+	if err != nil {
+		return "", err
+	}
+	for _, link := range wf.Links {
+		if link.Rel == "http://webfinger.net/rel/profile-page" &&
+			link.Type == "text/html" {
+			return link.Href, nil
+		}
+	}
+	return "", err
+}

accounts_test.go

@@ -0,0 +1,35 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestWebfingerParsing(t *testing.T) {
+	body := []byte(`{
+  "subject": "acct:Gargron@mastodon.social",
+  "aliases": [
+    "https://mastodon.social/@Gargron",
+    "https://mastodon.social/users/Gargron"
+  ],
+  "links": [
+    {
+      "rel": "http://webfinger.net/rel/profile-page",
+      "type": "text/html",
+      "href": "https://mastodon.social/@Gargron"
+    },
+    {
+      "rel": "self",
+      "type": "application/activity+json",
+      "href": "https://mastodon.social/users/Gargron"
+    },
+    {
+      "rel": "http://ostatus.org/schema/1.0/subscribe",
+      "template": "https://mastodon.social/authorize_interaction?uri={uri}"
+    }
+  ]
+}`)
+	uri, err := parseWebFinger(body)
+	assert.NoError(t, err)
+	assert.Equal(t, "https://mastodon.social/@Gargron", uri)
+}

add.html

@@ -1,21 +1,25 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
   <head>
     <meta charset="utf-8">
     <meta name="format-detection" content="telephone=no">
-    <meta name="viewport" content="width=device-width">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
     <title>Add to {{.Title}}</title>
     <style>
-html { max-width: 70ch; padding: 2ch; margin: auto; color: #111; background: #ffe; }
-form, textarea { width: 100%; }
+html { max-width: 70ch; padding: 1ch; height: calc(100% - 2ch); margin: auto }
+body { hyphens: auto; color: #111; background-color: #ffe; margin: 0; padding: 0; height: 100%; display: flex; flex-flow: column }
+form, textarea { box-sizing: border-box; width: 100%; font-size: inherit }
+#editor { flex: 1 1 auto; display: flex; flex-flow: column }
+textarea { flex: 1 1 auto }
     </style>
   </head>
   <body>
     <h1>Adding to {{.Title}}</h1>
-    <form action="/append/{{.Name}}" method="POST">
-      <div><textarea name="body" rows="20" cols="80" placeholder="Text" autofocus></textarea></div>
+    <form id="editor" action="/append/{{.Path}}" method="POST">
+      <textarea name="body" rows="20" cols="80" placeholder="Text" lang="{{.Language}}" autofocus required></textarea>
+      <p><label><input type="checkbox" name="notify" checked> Add link to <a href="/view/changes">the list of changes</a>.</label></p>
       <p><input type="submit" value="Add">
-        <a href="/view/{{.Name}}"><button>Cancel</button></a></p>
+        <a href="/view/{{.Path}}"><button type="button">Cancel</button></a></p>
     </form>
   </body>
 </html>

add_append.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"bytes"
+	"log"
+	"net/http"
+)
+
+// addHandler uses the "add.html" template to present an empty edit
+// page. What you type there is appended to the page using the
+// appendHandler.
+func addHandler(w http.ResponseWriter, r *http.Request, name string) {
+	p, err := loadPage(name)
+	if err != nil {
+		p = &Page{Title: name, Name: name}
+	} else {
+		p.handleTitle(false)
+	}
+	renderTemplate(w, p.Dir(), "add", p)
+}
+
+// appendHandler takes the "body" form parameter and appends it. The browser is redirected to the page view. This is
+// similar to the saveHandler.
+func appendHandler(w http.ResponseWriter, r *http.Request, name string) {
+	body := r.FormValue("body")
+	p, err := loadPage(name)
+	if err != nil {
+		p = &Page{Name: name, Body: []byte(body)}
+	} else {
+		p.append([]byte(body))
+	}
+	p.handleTitle(false)
+	err = p.save()
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	username, _, ok := r.BasicAuth()
+	if ok {
+		log.Println("Save", name, "by", username)
+	} else {
+		log.Println("Save", name)
+	}
+	if r.FormValue("notify") == "on" {
+		err = p.notify()
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+			return
+		}
+	}
+	http.Redirect(w, r, "/view/" + nameEscape(name), http.StatusFound)
+}
+
+func (p *Page) append(body []byte) {
+	// ensure an empty line at the end
+	if bytes.HasSuffix(p.Body, []byte("\n\n")) {
+	} else if bytes.HasSuffix(p.Body, []byte("\n")) {
+		p.Body = append(p.Body, '\n')
+	} else {
+		p.Body = append(p.Body, '\n', '\n')
+	}
+	p.Body = append(p.Body, body...)
+}

add_append_test.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"net/url"
+	"os"
+	"regexp"
+	"testing"
+	"time"
+)
+
+func TestEmptyLineAdd(t *testing.T) {
+	p := &Page{Name: "testdata/add/fire", Body: []byte(`# Coal
+Black rocks light as foam
+Shaking, puring, shoveling`)}
+	p.append([]byte("Into the oven"))
+	assert.Equal(t, string(p.Body), `# Coal
+Black rocks light as foam
+Shaking, puring, shoveling
+
+Into the oven`)
+}
+
+func TestAddAppend(t *testing.T) {
+	cleanup(t, "testdata/add")
+	index.load()
+	p := &Page{Name: "testdata/add/fire", Body: []byte(`# Fire
+Orange sky above
+Reflects a distant fire
+It's not `)}
+	p.save()
+
+	data := url.Values{}
+	data.Set("body", "barbecue")
+
+	assert.Regexp(t, regexp.MustCompile("a distant fire"),
+		assert.HTTPBody(makeHandler(viewHandler, false, http.MethodGet),
+			"GET", "/view/testdata/add/fire", nil))
+	assert.NotRegexp(t, regexp.MustCompile("a distant fire"),
+		assert.HTTPBody(makeHandler(addHandler, true, http.MethodGet),
+			"GET", "/add/testdata/add/fire", nil))
+	HTTPRedirectTo(t, makeHandler(appendHandler, true, http.MethodPost),
+		"POST", "/append/testdata/add/fire", data, "/view/testdata/add/fire")
+	assert.Regexp(t, regexp.MustCompile(`not</p>\s*<p>barbecue`),
+		assert.HTTPBody(makeHandler(viewHandler, false, http.MethodGet),
+			"GET", "/view/testdata/add/fire", nil))
+}
+
+func TestAddAppendChanges(t *testing.T) {
+	cleanup(t, "testdata/append")
+	today := time.Now().Format(time.DateOnly)
+	p := &Page{Name: "testdata/append/" + today + "-water", Body: []byte(`# Water
+Sunlight dancing fast
+Blue and green and pebbles gray
+`)}
+	p.save()
+	data := url.Values{}
+	data.Set("body", "Stand in cold water")
+	data.Add("notify", "on")
+	HTTPRedirectTo(t, makeHandler(appendHandler, true, http.MethodPost),
+		"POST", "/append/testdata/append/"+today+"-water",
+		data, "/view/testdata/append/"+today+"-water")
+	// The changes.md file was created
+	s, err := os.ReadFile("testdata/append/changes.md")
+	assert.NoError(t, err)
+	assert.Equal(t, "# Changes\n\n## "+today+"\n* [Water]("+today+"-water)\n", string(s))
+	// Link added to index.md file
+	s, err = os.ReadFile("testdata/append/index.md")
+	assert.NoError(t, err)
+	// New index contains just the link
+	assert.Equal(t, string(s), "* [Water]("+today+"-water)\n")
+}

archive.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"archive/zip"
+	"io"
+	"io/fs"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// archiveHandler serves a zip file. Directories starting with a period are skipped. Filenames starting with a period
+// are skipped. If the environment variable ODDMU_FILTER is a regular expression that matches the starting directory,
+// this is a "separate site"; if the regular expression does not match, this is the "main site" and page names must also
+// not match the regular expression.
+func archiveHandler(w http.ResponseWriter, r *http.Request, name string) {
+	filter := os.Getenv("ODDMU_FILTER")
+	re, err := regexp.Compile(filter)
+	if err != nil {
+		log.Println("ODDMU_FILTER does not compile:", filter, err)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	matches := re.MatchString(name)
+	dir := filepath.Dir(filepath.FromSlash(name))
+	z := zip.NewWriter(w)
+	err = filepath.Walk(dir, func(fp string, info fs.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.IsDir() {
+			if fp != "." && strings.HasPrefix(filepath.Base(fp), ".") {
+				return filepath.SkipDir
+			}
+		} else if !strings.HasPrefix(filepath.Base(fp), ".") &&
+			(matches || !re.MatchString(filepath.ToSlash(fp))) {
+			zf, err := z.Create(fp)
+			if err != nil {
+				log.Println(err)
+				return err
+			}
+			f, err := os.Open(fp)
+			if err != nil {
+				log.Println(err)
+				return err
+			}
+			_, err = io.Copy(zf, f)
+			if err != nil {
+				log.Println(err)
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		log.Println(err)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	err = z.Close()
+	if err != nil {
+		log.Println(err)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+}

archive_test.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"archive/zip"
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestArchive(t *testing.T) {
+	cleanup(t, "testdata/archive")
+	assert.NoError(t, os.MkdirAll("testdata/archive/public", 0755))
+	assert.NoError(t, os.MkdirAll("testdata/archive/secret", 0755))
+	assert.NoError(t, os.WriteFile("testdata/archive/public/index.md", []byte("# Public\nChurch tower bells ringing\nA cold wind biting my ears\nWalk across the square"), 0644))
+	assert.NoError(t, os.WriteFile("testdata/archive/secret/index.md", []byte("# Secret\nMany years ago I danced\nSpending nights in clubs and bars\nIt is my secret"), 0644))
+	os.Setenv("ODDMU_FILTER", "^testdata/archive/secret/")
+	body := assert.HTTPBody(makeHandler(archiveHandler, true, http.MethodGet), "GET", "/archive/testdata/data.zip", nil)
+	r, err := zip.NewReader(strings.NewReader(body), int64(len(body)))
+	assert.NoError(t, err, "Unzip")
+	names := []string{}
+	for _, file := range r.File {
+		names = append(names, file.Name)
+	}
+	assert.Contains(t, names, "testdata/archive/public/index.md")
+	assert.NotContains(t, names, "testdata/archive/secret/index.md")
+}

changes.go

@@ -0,0 +1,240 @@
+package main
+
+import (
+	"log"
+	"path"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// notify adds a link to the "changes" page, the "index" page, as well as to all the existing hashtag pages. The link to
+// the "index" page is only added if the page being edited is a blog page for the current year. The link to existing
+// hashtag pages is only added for blog pages. If the "changes" page does not exist, it is created. If the hashtag page
+// does not exist, it is not. Hashtag pages are considered optional. If the page that's being edited is in a
+// subdirectory, then the "changes", "index" and hashtag pages of that particular subdirectory are affected. Every
+// subdirectory is treated like a potentially independent wiki. Errors are logged before being returned because the
+// error messages are confusing from the point of view of the saveHandler.
+func (p *Page) notify() error {
+	p.handleTitle(false)
+	if p.Title == "" {
+		p.Title = p.Name
+	}
+	esc := nameEscape(p.Base())
+	link := "* [" + p.Title + "](" + esc + ")\n"
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(` + esc + `\)\n`)
+	dir := p.Dir()
+	err := addLinkWithDate(path.Join(dir, "changes"), link, re)
+	if err != nil {
+		log.Printf("Updating changes in %s failed: %s", dir, err)
+		return err
+	}
+	if p.IsBlog() {
+		// Add to the index only if the blog post is for the current year
+		if strings.HasPrefix(p.Base(), time.Now().Format("2006")) {
+			err := addLink(path.Join(dir, "index"), true, link, re)
+			if err != nil {
+				log.Printf("Updating index in %s failed: %s", dir, err)
+				return err
+			}
+		}
+		p.renderHtml() // to set hashtags
+		for _, hashtag := range p.Hashtags {
+			err := addLink(path.Join(dir, hashtag), false, link, re)
+			if err != nil {
+				log.Printf("Updating hashtag %s in %s failed: %s", hashtag, dir, err)
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// addLinkWithDate adds the link to a page, with date header for today. If a match already exists, it is removed. If
+// this leaves a date header without any links, it is removed as well. If a list is found, the link is added at the top
+// of the list. Lists must use the asterisk, not the minus character.
+func addLinkWithDate(name, link string, re *regexp.Regexp) error {
+	date := time.Now().Format(time.DateOnly)
+	org := ""
+	p, err := loadPage(name)
+	if err != nil {
+		// create a new page
+		p = &Page{Name: name, Body: []byte("# Changes\n\n## " + date + "\n" + link)}
+	} else {
+		org = string(p.Body)
+		// remove the old match, if one exists
+		loc := re.FindIndex(p.Body)
+		if loc != nil {
+			r := p.Body[:loc[0]]
+			if loc[1] < len(p.Body) {
+				r = append(r, p.Body[loc[1]:]...)
+			}
+			p.Body = r
+			if loc[0] >= 14 && len(p.Body) >= loc[0]+15 {
+				// remove the preceding date if there are now two dates following each other
+				re := regexp.MustCompile(`(?m)^## (\d\d\d\d-\d\d-\d\d)\n\n## (\d\d\d\d-\d\d-\d\d)\n`)
+				if re.Match(p.Body[loc[0]-14 : loc[0]+15]) {
+					p.Body = append(p.Body[0:loc[0]-14], p.Body[loc[0]+1:]...)
+				}
+			} else if len(p.Body) == loc[0] {
+				// remove a trailing date
+				re := regexp.MustCompile(`## (\d\d\d\d-\d\d-\d\d)\n`)
+				if re.Match(p.Body[loc[0]-14 : loc[0]]) {
+					p.Body = p.Body[0 : loc[0]-14]
+				}
+			}
+		}
+		// locate the beginning of the list to insert the line
+		re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\([^\)]+\)\n`)
+		loc = re.FindIndex(p.Body)
+		if loc == nil {
+			// if no list was found, use the end of the page
+			loc = []int{len(p.Body)}
+		}
+		// start with new page content
+		r := []byte("")
+		// check if there is a date right before the insertion point
+		addDate := true
+		if loc[0] >= 14 {
+			re := regexp.MustCompile(`(?m)^## (\d\d\d\d-\d\d-\d\d)\n`)
+			m := re.Find(p.Body[loc[0]-14 : loc[0]])
+			if m == nil {
+				// not a date: insert date, don't move insertion point
+			} else if string(p.Body[loc[0]-11:loc[0]-1]) == date {
+				// if the date is our date, don't add it, don't move insertion point
+				addDate = false
+			} else {
+				// if the date is not out date, move the insertion point
+				loc[0] -= 14
+			}
+		}
+		// append up to the insertion point
+		r = append(r, p.Body[:loc[0]]...)
+		// append date, if necessary
+		if addDate {
+			// ensure paragraph break
+			if len(r) > 0 && r[len(r)-1] != '\n' {
+				r = append(r, '\n')
+			}
+			if len(r) > 1 && r[len(r)-2] != '\n' {
+				r = append(r, '\n')
+			}
+			r = append(r, []byte("## ")...)
+			r = append(r, []byte(date)...)
+			r = append(r, '\n')
+		}
+		// append link
+		r = append(r, []byte(link)...)
+		// if we just added a date, add an empty line after the single-element list
+		if len(p.Body) > loc[0] && p.Body[loc[0]] != '*' {
+			r = append(r, '\n')
+		}
+		// append the rest
+		r = append(r, p.Body[loc[0]:]...)
+		p.Body = r
+	}
+	// only save if something changed
+	if string(p.Body) != org {
+		return p.save()
+	}
+	return nil
+}
+
+// addLink adds a link to a named page, if the page exists and doesn't contain the link. If the link exists but with a
+// different title, the title is fixed.
+func addLink(name string, mandatory bool, link string, re *regexp.Regexp) error {
+	p, err := loadPage(name)
+	if err != nil {
+		if mandatory {
+			p = &Page{Name: name, Body: []byte(link)}
+			return p.save()
+		} else {
+			// Skip non-existing files: no error
+			return nil
+		}
+	}
+	org := string(p.Body)
+	addLinkToPage(p, link, re)
+	// only save if something changed
+	if string(p.Body) != org {
+		return p.save()
+	}
+	return nil
+}
+
+func addLinkToPage(p *Page, link string, re *regexp.Regexp) {
+	// if a link exists, that's the place to insert the new link (in which case loc[0] and loc[1] differ)
+	loc := re.FindIndex(p.Body)
+	// if no link exists, find a good place to insert it
+	if loc == nil {
+		// locate the list items
+		re = regexp.MustCompile(`(?m)^\* \[[^\]]+\]\([^\)]+\)\n?`)
+		items := re.FindAllIndex(p.Body, -1)
+		first := false
+		pos := -1
+		// skip newer items
+		for i, it := range items {
+			// break if the current line is older (earlier in sort order)
+			stop := string(p.Body[it[0]:it[1]]) < link
+			// before the first match is always a good insert point
+			if i == 0 {
+				pos = it[0]
+				first = true
+			}
+			// if we're not stopping, then after the current item is a good insert point
+			if !stop {
+				pos = it[1]
+				first = false
+			} else {
+				break
+			}
+		}
+		// otherwise it's at the end of the list, after the last item
+		if pos == -1 && len(items) > 0 {
+			pos = items[len(items)-1][1]
+			first = false
+		}
+		// if no list was found, use the end of the page
+		if pos == -1 {
+			pos = len(p.Body)
+			first = true
+		}
+		if first {
+			p.Body, pos = ensureTwoNewlines(p.Body, pos)
+		}
+		// mimic a zero-width match at the insert point
+		loc = []int{pos, pos}
+	}
+	// start with new page content
+	r := []byte("")
+	// append up to the insertion point
+	r = append(r, p.Body[:loc[0]]...)
+	// append link
+	r = append(r, []byte(link)...)
+	// append the rest
+	r = append(r, p.Body[loc[1]:]...)
+	p.Body = r
+}
+
+// ensureTwoNewlines makes sure that the two bytes before pos in buf are newlines. If the are not, newlines are inserted
+// and pos is increased. The new buf and pos is returned.
+func ensureTwoNewlines(buf []byte, pos int) ([]byte, int) {
+	var insert []byte
+	if pos >= 1 && buf[pos-1] != '\n' {
+		// add two newlines if buf doesn't end with a newline
+		insert = []byte("\n\n")
+	} else if pos >= 2 && buf[pos-2] != '\n' {
+		// add one newline if Body ends with just one newline
+		insert = []byte("\n")
+	}
+	if insert != nil {
+		r := []byte("")
+		r = append(r, buf[:pos]...)
+		r = append(r, insert...)
+		r = append(r, buf[pos:]...)
+		buf = r
+		pos += len(insert)
+
+	}
+	return buf, pos
+}

changes_test.go

@@ -0,0 +1,262 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"os"
+	"regexp"
+	"testing"
+	"time"
+)
+
+// Note TestEditSaveChanges and TestAddAppendChanges.
+
+func TestAddLinkToPageWithNoList(t *testing.T) {
+	// no newlines
+	title := "# Test"
+	p := &Page{Body: []byte(title)}
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(2025-08-08\)\n`)
+	link := "* [2025-08-08](2025-08-08)\n"
+	addLinkToPage(p, link, re)
+	assert.Equal(t, title + "\n\n" + link, string(p.Body))
+}
+
+func TestAddLinkToPageWithOlderLink(t *testing.T) {
+	// one newline
+	title := "# Test\n"
+	old := "* [2025-08-08](2025-08-08)\n"
+	p := &Page{Body: []byte(title + old)}
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(2025-08-10\)\n`)
+	link := "* [2025-08-10](2025-08-10)\n"
+	addLinkToPage(p, link, re)
+	assert.Equal(t, title + "\n" + link + old, string(p.Body))
+}
+
+func TestAddLinkToPageBetweenToExistingLinks(t *testing.T) {
+	title := "# Test\n\n"
+	new := "* [2025-08-10](2025-08-10)\n"
+	old := "* [2025-08-08](2025-08-08)\n"
+	p := &Page{Body: []byte(title + new + old)}
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(2025-08-09\)\n`)
+	link := "* [2025-08-09](2025-08-09)\n"
+	addLinkToPage(p, link, re)
+	assert.Equal(t, title + new + link + old, string(p.Body))
+}
+
+func TestAddLinkToPageBetweenToExistingLinks2(t *testing.T) {
+	title := "# Test\n\n"
+	new := "* [2025-08-10](2025-08-10)\n* [2025-08-09](2025-08-09)\n"
+	old := "* [2025-08-07](2025-08-07)\n"
+	p := &Page{Body: []byte(title + new + old)}
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(2025-08-08\)\n`)
+	link := "* [2025-08-08](2025-08-08)\n"
+	addLinkToPage(p, link, re)
+	assert.Equal(t, title + new + link + old, string(p.Body))
+}
+
+func TestAddLinkToPageAtTheEnd(t *testing.T) {
+	title := "# Test\n\n"
+	new := "* [2025-08-10](2025-08-10)\n"
+	old := "* [2025-08-08](2025-08-08)\n"
+	p := &Page{Body: []byte(title + new + old)}
+	re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(2025-08-07\)\n`)
+	link := "* [2025-08-07](2025-08-07)\n"
+	addLinkToPage(p, link, re)
+	assert.Equal(t, title + new + old + link, string(p.Body))
+}
+
+func TestChanges(t *testing.T) {
+	cleanup(t, "testdata/washing")
+	today := time.Now().Format(time.DateOnly)
+	p := &Page{Name: "testdata/washing/" + today + "-machine",
+		Body: []byte(`# Washing machine
+Churning growling thing
+Water spraying in a box 
+Out of sight and dark`)}
+	p.notify()
+	// Link added to changes.md file
+	s, err := os.ReadFile("testdata/washing/changes.md")
+	assert.NoError(t, err)
+	assert.Contains(t, string(s), "[Washing machine]("+today+"-machine)")
+	// Link added to index.md file
+	s, err = os.ReadFile("testdata/washing/index.md")
+	assert.NoError(t, err)
+	// New index contains just the link
+	assert.Equal(t, string(s), "* [Washing machine]("+today+"-machine)\n")
+}
+
+func TestChangesWithHashtag(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Haiku\n"
+	line := "* [Hotel room](2023-10-27-hotel)\n"
+	h := &Page{Name: "testdata/changes/Haiku", Body: []byte(intro)}
+	h.save()
+	p := &Page{Name: "testdata/changes/2023-10-27-hotel",
+		Body: []byte(`# Hotel room
+White linen and white light
+Wooden floor and painted walls
+Home away from home
+
+#Haiku #Poetry`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	assert.Contains(t, string(s), line)
+	s, err = os.ReadFile("testdata/changes/Haiku.md")
+	assert.NoError(t, err)
+	// ensure an empty line when adding at the end of the page
+	assert.Equal(t, intro+"\n"+line, string(s))
+	assert.NoFileExists(t, "testdata/changes/Poetry.md")
+}
+
+func TestChangesWithList(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	line := "* [a change](change)\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+d+line), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// new line was added at the beginning of the list
+	assert.Equal(t, intro+d+new_line+line, string(s))
+}
+
+func TestChangesWithOldList(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	line := "* [a change](change)\n"
+	y := "## " + time.Now().Add(-24*time.Hour).Format(time.DateOnly) + "\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+y+line), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// new line was added at the beginning of the list
+	assert.Equal(t, intro+d+new_line+"\n"+y+line, string(s))
+}
+
+func TestChangesWithOldDisappearingListAtTheEnd(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	line := "* [a change](alex)\n"
+	y := "## " + time.Now().Add(-24*time.Hour).Format(time.DateOnly) + "\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+y+line), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// new line was added at the beginning of the list, with the new date, and the old date disappeared
+	assert.Equal(t, intro+d+new_line, string(s))
+}
+
+func TestChangesWithOldDisappearingListInTheMiddle(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	line := "* [a change](alex)\n"
+	other := "* [other change](whatever)\n"
+	yy := "## " + time.Now().Add(-48*time.Hour).Format(time.DateOnly) + "\n"
+	y := "## " + time.Now().Add(-24*time.Hour).Format(time.DateOnly) + "\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+y+line+"\n"+yy+other), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// new line was added at the beginning of the list, with the new date, and the old date disappeared
+	assert.Equal(t, intro+d+new_line+"\n"+yy+other, string(s))
+}
+
+func TestChangesWithListAtTheTop(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	line := "* [a change](change)\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(line), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// new line was added at the top, no error due to missing introduction
+	assert.Equal(t, d+new_line+line, string(s))
+}
+
+func TestChangesWithNoList(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph."
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// into is still there and a new list was started
+	assert.Equal(t, intro+"\n\n"+d+new_line, string(s))
+}
+
+func TestChangesWithUpdate(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	other := "* [other change](whatever)\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	line := "* [a change](alex)\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+d+other+line), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// the change was already listed, but now it moved up and has a new title
+	assert.Equal(t, intro+d+new_line+other, string(s))
+}
+
+func TestChangesWithNoChangeToTheOrder(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	line := "* [a change](alex)\n"
+	other := "* [other change](whatever)\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+d+line+other), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte(`Hallo!`)}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	new_line := "* [testdata/changes/alex](alex)\n"
+	// the change was already listed at the top, so just use the new title
+	assert.Equal(t, intro+d+new_line+other, string(s))
+	// since the file has changed, a backup was necessary
+	assert.FileExists(t, "testdata/changes/changes.md~")
+}
+
+func TestChangesWithNoChanges(t *testing.T) {
+	cleanup(t, "testdata/changes")
+	intro := "# Changes\n\nThis is a paragraph.\n\n"
+	d := "## " + time.Now().Format(time.DateOnly) + "\n"
+	line := "* [a change](alex)\n"
+	other := "* [other change](whatever)\n"
+	assert.NoError(t, os.MkdirAll("testdata/changes", 0755))
+	assert.NoError(t, os.WriteFile("testdata/changes/changes.md", []byte(intro+d+line+other), 0644))
+	p := &Page{Name: "testdata/changes/alex", Body: []byte("# a change\nHallo!")}
+	p.notify()
+	s, err := os.ReadFile("testdata/changes/changes.md")
+	assert.NoError(t, err)
+	// the change was already listed at the top, so no change was necessary
+	assert.Equal(t, intro+d+line+other, string(s))
+	// since the file hasn't changed, no backup was necessary
+	assert.NoFileExists(t, "testdata/changes/changes.md~")
+}

diff.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"bytes"
+	"github.com/sergi/go-diff/diffmatchpatch"
+	"html"
+	"html/template"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func diffHandler(w http.ResponseWriter, r *http.Request, name string) {
+	p, err := loadPage(name)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	p.handleTitle(true)
+	p.renderHtml()
+	renderTemplate(w, p.Dir(), "diff", p)
+}
+
+// Diff computes the diff for a page. At this point, renderHtml has already been called so the Name is escaped.
+func (p *Page) Diff() template.HTML {
+	fp := filepath.FromSlash(p.Name)
+	a := fp + ".md~"
+	t1, err := os.ReadFile(a)
+	if err != nil {
+		return template.HTML("Cannot read " + a + ", so the page is new.")
+	}
+	b := fp + ".md"
+	t2, err := os.ReadFile(b)
+	if err != nil {
+		return template.HTML("Cannot read " + b + ", so the page was deleted.")
+	}
+	dmp := diffmatchpatch.New()
+	diffs := dmp.DiffMain(string(t1), string(t2), false)
+	return template.HTML(diff2html(dmp.DiffCleanupSemantic(diffs)))
+}
+
+func diff2html(diffs []diffmatchpatch.Diff) string {
+	var buf bytes.Buffer
+	for _, item := range diffs {
+		text := strings.ReplaceAll(html.EscapeString(item.Text), "\n", "<br>")
+		switch item.Type {
+		case diffmatchpatch.DiffInsert:
+			_, _ = buf.WriteString("<ins>")
+			_, _ = buf.WriteString(text)
+			_, _ = buf.WriteString("</ins>")
+		case diffmatchpatch.DiffDelete:
+			_, _ = buf.WriteString("<del>")
+			_, _ = buf.WriteString(text)
+			_, _ = buf.WriteString("</del>")
+		case diffmatchpatch.DiffEqual:
+			_, _ = buf.WriteString("<span>")
+			_, _ = buf.WriteString(text)
+			_, _ = buf.WriteString("</span>")
+		}
+	}
+	return buf.String()
+}

diff.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="{{.Language}}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="format-detection" content="telephone=no">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
+    <title>{{.Title}}</title>
+    <style>
+html { max-width: 70ch; padding: 1ch; margin: auto; color: #111; background-color: #ffe }
+body { hyphens: auto }
+del  { background-color: #fab }
+ins  { background-color: #af8 }
+pre { white-space: normal; background-color: white; border: 1px solid #eee; padding: 1ch }
+    </style>
+  </head>
+  <body>
+    <header>
+      <a href="/view/{{.Path}}">Back</a>
+    </header>
+    <main id="main">
+      <h1>{{.Title}}</h1>
+      <p>This is the diff between <a href="/view/{{.Path}}.md~">the backup</a> and <a href="/view/{{.Path}}.md">the current copy</a>.</p>
+      <pre>
+{{.Diff}}
+      </pre>
+    </main>
+  </body>
+</html>

diff_test.go

@@ -0,0 +1,108 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+)
+
+func TestDiff(t *testing.T) {
+	cleanup(t, "testdata/diff")
+	index.load()
+	s := `# Bread
+
+The oven breathes
+Fills us with the thought of bread
+Oh so fresh, so warm.`
+	r := `# Bread
+
+The oven whispers
+Fills us with the thought of bread
+Oh so fresh, so warm.`
+	p := &Page{Name: "testdata/diff/bread", Body: []byte(s)}
+	p.save()
+	p.Body = []byte(r)
+	p.save()
+	body := assert.HTTPBody(makeHandler(diffHandler, true, http.MethodGet),
+		"GET", "/diff/testdata/diff/bread", nil)
+	assert.Contains(t, body, `<del>breathe</del>`)
+	assert.Contains(t, body, `<ins>whisper</ins>`)
+}
+
+func TestDiffPercentEncoded(t *testing.T) {
+	cleanup(t, "testdata/diff")
+	index.load()
+	s := `# Coup de Gras
+
+Playing D&D
+We talk about a killing
+Mispronouncing words`
+	r := `# Coup de Grace
+
+Playing D&D
+We talk about a killing
+Mispronouncing words`
+	p := &Page{Name: "testdata/diff/coup de grace", Body: []byte(s)}
+	p.save()
+	p.Body = []byte(r)
+	p.save()
+	body := assert.HTTPBody(makeHandler(diffHandler, true, http.MethodGet),
+		"GET", "/diff/testdata/diff/coup%20de%20grace", nil)
+	assert.Contains(t, body, `<del>s</del>`)
+	assert.Contains(t, body, `<ins>ce</ins>`)
+}
+
+func TestDiffBackup(t *testing.T) {
+	cleanup(t, "testdata/backup")
+	s := `# Cold Rooms
+
+I shiver at home
+the monitor glares and moans
+fear or cold, who knows?`
+	r := `# Cold Rooms
+
+I shiver at home
+the monitor glares and moans
+I hate the machine!`
+	u := `# Cold Rooms
+
+I shiver at home
+the monitor glares and moans
+my grey heart grows cold`
+	// create s and overwrite it with r
+	p := &Page{Name: "testdata/backup/cold", Body: []byte(s)}
+	p.save()
+	p = &Page{Name: "testdata/backup/cold", Body: []byte(r)}
+	p.save()
+	body := string(p.Diff())
+	// diff from s to r:
+	assert.Contains(t, body, `<del>fear or cold, who knows?</del>`)
+	assert.Contains(t, body, `<ins>I hate the machine!</ins>`)
+	// save u
+	p = &Page{Name: "testdata/backup/cold", Body: []byte(u)}
+	p.save()
+	body = string(p.Diff())
+	// diff from s to u since r was not 60 min or older and so the backup is kept
+	assert.Contains(t, body, `<del>fear or cold, who knows?</del>`)
+	assert.Contains(t, body, `<ins>my grey heart grows cold</ins>`)
+	// set timestamp 2h in the past
+	ts := time.Now().Add(-2 * time.Hour)
+	assert.NoError(t, os.Chtimes("testdata/backup/cold.md~", ts, ts))
+	assert.NoError(t, os.Chtimes("testdata/backup/cold.md", ts, ts))
+	// save r
+	p = &Page{Name: "testdata/backup/cold", Body: []byte(r)}
+	p.save()
+	body = string(p.Diff())
+	// diff from u to r since enough time has passed and the old backup is discarded
+	assert.Contains(t, body, `<del>my grey heart grows cold</del>`)
+	assert.Contains(t, body, `<ins>I hate the machine!</ins>`)
+	// save s
+	p = &Page{Name: "testdata/backup/cold", Body: []byte(s)}
+	p.save()
+	body = string(p.Diff())
+	// diff from u to s since this is still "the same" editing window
+	assert.Contains(t, body, `<del>my grey heart grows cold</del>`)
+	assert.Contains(t, body, `<ins>fear or cold, who knows?</ins>`)
+}

edit.html

@@ -1,23 +1,29 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
   <head>
     <meta charset="utf-8">
     <meta name="format-detection" content="telephone=no">
-    <meta name="viewport" content="width=device-width">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
+    <base href="/view/{{.Dir}}">
     <title>Editing {{.Title}}</title>
     <style>
-html { max-width: 70ch; padding: 2ch; margin: auto; color: #111; background: #ffe; }
-form, textarea { width: 100%; }
+html { max-width: 70ch; padding: 1ch; height: calc(100% - 2ch); margin: auto }
+body { hyphens: auto; color: #111; background-color: #ffe; margin: 0; padding: 0; height: 100%; display: flex; flex-flow: column }
+form, textarea { box-sizing: border-box; width: 100%; font-size: inherit }
+#editor { flex: 1 1 auto; display: flex; flex-flow: column }
+textarea { flex: 1 1 auto }
     </style>
   </head>
   <body>
     <h1>Editing {{.Title}}</h1>
-    <form action="/save/{{.Name}}" method="POST">
-      <div><textarea name="body" rows="20" cols="80" placeholder="# Title
+    <form id="editor" action="/save/{{.Path}}" method="POST">
+      <textarea name="body" rows="20" cols="80" placeholder="# Title
 
-Text" autofocus>{{printf "%s" .Body}}</textarea></div>
+Text" lang="{{.Language}}" autofocus>{{printf "%s" .Body}}</textarea>
+      <p><label><input type="checkbox" name="notify" checked> Add link to <a href="changes">the list of changes</a>.</label></p>
       <p><input type="submit" value="Save">
-        <a href="/view/{{.Name}}"><button>Cancel</button></a></p>
+        <button formaction="/preview/{{.Path}}" type="submit">Preview</button>
+        <a href="/view/{{.Path}}"><button type="button">Cancel</button></a></p>
     </form>
   </body>
 </html>

edit_save.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"log"
+	"net/http"
+)
+
+// editHandler uses the "edit.html" template to present an edit page. When editing, the page title is not overriden by a
+// title in the text. Instead, the page name is used. The edit is saved using the saveHandler.
+func editHandler(w http.ResponseWriter, r *http.Request, name string) {
+	p, err := loadPage(name)
+	if err != nil {
+		p = &Page{Title: name, Name: name}
+	} else {
+		p.handleTitle(false)
+	}
+	renderTemplate(w, p.Dir(), "edit", p)
+}
+
+// saveHandler takes the "body" form parameter and saves it. The browser is redirected to the page view. This is similar
+// to the appendHandler.
+func saveHandler(w http.ResponseWriter, r *http.Request, name string) {
+	body := r.FormValue("body")
+	p := &Page{Name: name, Body: []byte(body)}
+	err := p.save()
+	if err != nil {
+		log.Println(err)
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	username, _, ok := r.BasicAuth()
+	if ok {
+		log.Println("Save", name, "by", username)
+	} else {
+		log.Println("Save", name)
+	}
+	if r.FormValue("notify") == "on" {
+		err = p.notify() // errors have already been logged, so no logging here
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+			return
+		}
+	}
+	http.Redirect(w, r, "/view/" + nameEscape(name), http.StatusFound)
+}

edit_save_test.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"net/url"
+	"os"
+	"testing"
+	"time"
+)
+
+func TestEditSave(t *testing.T) {
+	cleanup(t, "testdata/save")
+
+	data := url.Values{}
+	data.Set("body", "Hallo!")
+
+	// View of the non-existing page redirects to the edit page
+	HTTPRedirectTo(t, makeHandler(viewHandler, false, http.MethodGet),
+		"GET", "/view/testdata/save/alex", nil, "/edit/testdata/save/alex")
+	// Edit page can be fetched
+	assert.HTTPStatusCode(t, makeHandler(editHandler, true, http.MethodGet),
+		"GET", "/edit/testdata/save/alex", nil, 200)
+	// Posting to the save URL saves a page
+	HTTPRedirectTo(t, makeHandler(saveHandler, true, http.MethodPost),
+		"POST", "/save/testdata/save/alex", data, "/view/testdata/save/alex")
+	// Page now contains the text
+	assert.Contains(t, assert.HTTPBody(makeHandler(viewHandler, false, http.MethodGet),
+		"GET", "/view/testdata/save/alex", nil),
+		"Hallo!")
+	// Delete the page and you're sent to the empty page
+	data.Set("body", "")
+	HTTPRedirectTo(t, makeHandler(saveHandler, true, http.MethodPost),
+		"POST", "/save/testdata/save/alex", data, "/view/testdata/save/alex")
+	// Viewing the non-existing page redirects to the edit page (like in the beginning)
+	HTTPRedirectTo(t, makeHandler(viewHandler, false, http.MethodGet),
+		"GET", "/view/testdata/save/alex", nil, "/edit/testdata/save/alex")
+}
+
+func TestEditSaveChanges(t *testing.T) {
+	cleanup(t, "testdata/notification")
+	data := url.Values{}
+	data.Set("body", "Hallo!")
+	data.Add("notify", "on")
+	today := time.Now().Format("2006-01-02")
+	// Posting to the save URL saves a page
+	HTTPRedirectTo(t, makeHandler(saveHandler, true, http.MethodPost),
+		"POST", "/save/testdata/notification/"+today,
+		data, "/view/testdata/notification/"+today)
+	// The changes.md file was created
+	s, err := os.ReadFile("testdata/notification/changes.md")
+	assert.NoError(t, err)
+	d := time.Now().Format(time.DateOnly)
+	assert.Equal(t, "# Changes\n\n## "+d+
+		"\n* [testdata/notification/"+today+"]("+today+")\n",
+		string(s))
+	// Link added to index.md file
+	s, err = os.ReadFile("testdata/notification/index.md")
+	assert.NoError(t, err)
+	// New index contains just the link
+	assert.Equal(t, string(s), "* [testdata/notification/"+today+"]("+today+")\n")
+}
+
+// Test the following view.html:
+// <form action="/edit/" method="GET">
+//
+//	<label for="id">New page:</label>
+//	<input id="id" type="text" spellcheck="false" name="id" accesskey="g" value="{{.Dir}}/{{.Today}}" required>
+//	<button>Edit</button>
+//
+// </form>
+func TestEditId(t *testing.T) {
+	cleanup(t, "testdata/id")
+	data := url.Values{}
+	data.Set("id", "testdata/id/alex")
+	assert.HTTPStatusCode(t, makeHandler(editHandler, true, http.MethodGet),
+		"GET", "/edit/", data, http.StatusBadRequest,
+		"No slashes in id")
+	data.Set("id", ".alex")
+	assert.HTTPStatusCode(t, makeHandler(editHandler, true, http.MethodGet),
+		"GET", "/edit/", data, http.StatusForbidden,
+		"No hidden files")
+	data.Set("id", "alex")
+	assert.Contains(t, assert.HTTPBody(makeHandler(editHandler, true, http.MethodGet),
+		"GET", "/edit/testdata/id/", data),
+		"Editing testdata/id/alex")
+}

export_cmd.go

@@ -0,0 +1,108 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	htmlTemplate "html/template"
+	"io"
+	"os"
+	"strings"
+	textTemplate "text/template"
+	"time"
+)
+
+type exportCmd struct {
+	templateName string
+}
+
+func (cmd *exportCmd) SetFlags(f *flag.FlagSet) {
+	f.StringVar(&cmd.templateName, "template", "feed.html", "template filename")
+}
+
+func (*exportCmd) Name() string     { return "export" }
+func (*exportCmd) Synopsis() string { return "export the whole site as one big RSS feed" }
+func (*exportCmd) Usage() string {
+	return `export:
+  Export the entire site as one big RSS feed. This may allow you to
+  import the whole site into a different content management system.
+  The feed contains every page, in HTML format, so the Markdown files
+  are part of the feed, but none of the other files.
+
+  The RSS feed is printed to stdout so you probably want to redirect
+  it:
+
+    oddmu export > /tmp/export.rss
+`
+}
+
+func (cmd *exportCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	index.load()
+	return exportCli(os.Stdout, cmd.templateName, &index)
+}
+
+// exportCli runs the export command on the command line. In order to make testing easier, it takes a Writer and an
+// indexStore. The Writer is important so that test code can provide a buffer instead of os.Stdout; the indexStore is
+// important so that test code can ensure no other test running in parallel can interfere with the list of known pages
+// (by adding or deleting pages).
+func exportCli(w io.Writer, templateName string, idx *indexStore) subcommands.ExitStatus {
+	loadLanguages()
+	feed := new(Feed)
+	items := []Item{}
+	// feed.Name remains unset
+	feed.Date = time.Now().Format(time.RFC3339)
+	for name, title := range idx.titles {
+		if name == "index" {
+			feed.Title = title
+		}
+		p, err := loadPage(name)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Loading %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		p.handleTitle(false)
+		p.renderHtml()
+		fi, err := os.Stat(name + ".md")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Stat %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		it := Item{Date: fi.ModTime().Format(time.RFC3339)}
+		it.Title = p.Title
+		it.Name = p.Name
+		it.Body = p.Body
+		it.Html = htmlTemplate.HTML(htmlTemplate.HTMLEscaper(p.Html))
+		it.Hashtags = p.Hashtags
+		items = append(items, it)
+	}
+	feed.Items = items
+	// No effort is made to work with the templates var.
+	if strings.HasSuffix(templateName, ".html") ||
+		strings.HasSuffix(templateName, ".xml") ||
+		strings.HasSuffix(templateName, ".rss") {
+		w.Write([]byte("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"))
+		t, err := htmlTemplate.ParseFiles(templateName)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Parsing %s: %s\n", templateName, err)
+			return subcommands.ExitFailure
+		}
+		err = t.Execute(w, feed)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Writing feed: %s\n", err)
+			return subcommands.ExitFailure
+		}
+	} else {
+		t, err := textTemplate.ParseFiles(templateName)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Parsing %s: %s\n", templateName, err)
+			return subcommands.ExitFailure
+		}
+		err = t.Execute(w, feed)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Writing feed: %s\n", err)
+			return subcommands.ExitFailure
+		}
+	}
+	return subcommands.ExitSuccess
+}

export_cmd_test.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"os"
+	"regexp"
+	"testing"
+)
+
+func TestExportCmd(t *testing.T) {
+	b := new(bytes.Buffer)
+	s := exportCli(b, "feed.html", minimalIndex(t))
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	assert.Contains(t, b.String(), "<title>Oddμ: A minimal wiki</title>")
+	assert.Contains(t, b.String(), "<title>Welcome to Oddμ</title>")
+}
+
+func TestExportCmdLanguage(t *testing.T) {
+	os.Setenv("ODDMU_LANGUAGES", "de,en")
+	loadLanguages()
+	p := Page{Body: []byte("This is an English text. All right then!")}
+	it := Item{Page: p}
+	assert.Equal(t, "en", it.Language())
+}
+
+func TestExportCmdJsonFeed(t *testing.T) {
+	cleanup(t, "testdata/json")
+	os.Mkdir("testdata/json", 0755)
+	assert.NoError(t, os.WriteFile("testdata/json/template.json", []byte(`{
+  "version": "https://jsonfeed.org/version/1.1",
+  "title": "{{.Title}}",
+  "home_page_url": "https://alexschroeder.ch",
+  "others": [],
+  "items": [{{range .Items}}
+    {
+      "id": "{{.Name}}",
+      "url": "https://alexschroeder.ch/view/{{.Name}}",
+      "title": "{{.Title}}",
+      "language": "{{.Language}}"
+      "date_modified": "{{.Date}}",
+      "content_html": "{{.Html}}",
+      "tags": [{{range .Hashtags}}"{{.}}",{{end}}""],
+    },{{end}}
+    {}
+  ]
+}
+`), 0644))
+	b := new(bytes.Buffer)
+	s := exportCli(b, "testdata/json/template.json", minimalIndex(t))
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	assert.Contains(t, b.String(), `"title": "Oddμ: A minimal wiki"`)
+	assert.Regexp(t, regexp.MustCompile("&lt;h1.*&gt;Welcome to Oddμ&lt;/h1&gt;"), b.String()) // skip id
+}

feed.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"bytes"
+	"github.com/gomarkdown/markdown"
+	"github.com/gomarkdown/markdown/ast"
+	"html/template"
+	"os"
+	"path"
+	"path/filepath"
+	"time"
+)
+
+// Item is a Page plus a Date.
+type Item struct {
+
+	// Page is the page being used as the feed item.
+	Page
+
+	// Date is the last modification date of the file storing the page. As the pages used by Oddmu are plain
+	// Markdown files, they don't contain any metadata. Instead, the last modification date of the file is used.
+	// This makes it work well with changes made to the files outside of Oddmu.
+	Date string
+}
+
+// Feed is an Item used for the feed itself, plus an array of items based on the linked pages.
+type Feed struct {
+
+	// Item is the page containing the list of links. It's title is used for the feed and it's last modified time is
+	// used for the publication date. Thus, if linked pages change but the page with the links doesn't change, the
+	// publication date remains unchanged.
+	Item
+
+	// Items are based on the pages linked in list items starting with an asterisk ("*"). Links in
+	// list items starting with a minus ("-") are ignored!
+	Items []Item
+}
+
+// feed returns a RSS 2.0 feed for any page. The feed items it contains are the pages linked from in list items starting
+// with an asterisk ("*").
+func feed(p *Page, ti time.Time) *Feed {
+	feed := new(Feed)
+	feed.Name = p.Name
+	feed.Title = p.Title
+	feed.Date = ti.Format(time.RFC1123Z)
+	parser, _ := wikiParser()
+	doc := markdown.Parse(p.Body, parser)
+	items := make([]Item, 0)
+	inListItem := false
+	ast.WalkFunc(doc, func(node ast.Node, entering bool) ast.WalkStatus {
+		// set the flag if we're in a list item
+		listItem, ok := node.(*ast.ListItem)
+		if ok && listItem.BulletChar == '*' {
+			inListItem = entering
+			return ast.GoToNext
+		}
+		// if we're not in a list item, continue
+		if !inListItem || !entering {
+			return ast.GoToNext
+		}
+		// if we're in a link and it's local
+		link, ok := node.(*ast.Link)
+		if !ok || bytes.Contains(link.Destination, []byte("//")) {
+			return ast.GoToNext
+		}
+		name := path.Join(p.Dir(), string(link.Destination))
+		fi, err := os.Stat(filepath.FromSlash(name) + ".md")
+		if err != nil {
+			return ast.GoToNext
+		}
+		p2, err := loadPage(name)
+		if err != nil {
+			return ast.GoToNext
+		}
+		p2.handleTitle(false)
+		p2.renderHtml()
+		it := Item{Date: fi.ModTime().Format(time.RFC1123Z)}
+		it.Title = p2.Title
+		it.Name = p2.Name
+		it.Html = template.HTML(template.HTMLEscaper(p2.Html))
+		it.Hashtags = p2.Hashtags
+		items = append(items, it)
+		if len(items) >= 10 {
+			return ast.Terminate
+		}
+		return ast.GoToNext
+	})
+	feed.Items = items
+	return feed
+}

feed.html

@@ -0,0 +1,28 @@
+<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
+  <channel>
+    <docs>http://blogs.law.harvard.edu/tech/rss</docs>
+    <title>{{.Title}}</title>
+    <link>https://example.org/</link>
+    <managingEditor>you@example.org (Your Name)</managingEditor>
+    <webMaster>you@example.org (Your Name)</webMaster>
+    <atom:link href="https://example.org/view/{{.Path}}.rss" rel="self" type="application/rss+xml"/>
+    <description>This is the digital garden of Your Name.</description>
+    <image>
+      <url>https://example.org/view/logo.jpg</url>
+      <title>{{.Title}}</title>
+      <link>https://example.org/</link>
+    </image>
+    {{range .Items}}
+    <item>
+      <title>{{.Title}}</title>
+      <link>https://example.org/view/{{.Path}}</link>
+      <guid>https://example.org/view/{{.Path}}</guid>
+      <description>{{.Html}}</description>
+      <pubDate>{{.Date}}</pubDate>
+      {{range .Hashtags}}
+      <category>{{.}}</category>
+      {{end}}
+    </item>
+    {{end}}
+  </channel>
+</rss>

feed_test.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"testing"
+)
+
+func TestFeed(t *testing.T) {
+	assert.Contains(t,
+		assert.HTTPBody(makeHandler(viewHandler, false, http.MethodGet), "GET", "/view/index.rss", nil),
+		"Welcome to Oddμ")
+}
+
+func TestNoFeed(t *testing.T) {
+	assert.HTTPStatusCode(t,
+		makeHandler(viewHandler, false, http.MethodGet), "GET", "/view/no-feed.rss", nil, http.StatusNotFound)
+}
+
+func TestFeedItems(t *testing.T) {
+	cleanup(t, "testdata/feed")
+	index.load()
+
+	p1 := &Page{Name: "testdata/feed/cactus", Body: []byte(`# Cactus
+Green head and white hair
+A bench in the evening sun
+Unmoved by the news
+
+#Succulent`)}
+	p1.save()
+
+	p2 := &Page{Name: "testdata/feed/dragon", Body: []byte(`# Dragon
+My palm tree grows straight
+Up and up to touch the sky
+Ignoring the roof
+
+#Palmtree`)}
+	p2.save()
+
+	p3 := &Page{Name: "testdata/feed/plants", Body: []byte(`# Plants
+Writing poems about plants.
+
+* [My Cactus](cactus)
+* [My Dragon Tree](dragon)`)}
+	p3.save()
+
+	body := assert.HTTPBody(makeHandler(viewHandler, false, http.MethodGet), "GET", "/view/testdata/feed/plants.rss", nil)
+	assert.Contains(t, body, "<title>Plants</title>")
+	assert.Contains(t, body, "<title>Cactus</title>")
+	assert.Contains(t, body, "<title>Dragon</title>")
+	assert.Contains(t, body, "&lt;h1 id=&#34;cactus&#34;&gt;Cactus&lt;/h1&gt;")
+	assert.Contains(t, body, "&lt;h1 id=&#34;dragon&#34;&gt;Dragon&lt;/h1&gt;")
+	assert.Contains(t, body, "<category>Succulent</category>")
+	assert.Contains(t, body, "<category>Palmtree</category>")
+}

go.mod

@@ -1,19 +1,41 @@
 module alexschroeder.ch/cgit/oddmu
 
-go 1.21.0
+go 1.22
+
+toolchain go1.22.3
 
 require (
-	github.com/dgryski/go-trigram v0.0.0-20160407183937-79ec494e1ad0
-	github.com/gomarkdown/markdown v0.0.0-20230716120725-531d2d74bc12
-	github.com/microcosm-cc/bluemonday v1.0.25
+	github.com/disintegration/imaging v1.6.2
+	github.com/edwvee/exiffix v0.0.0-20210922235313-0f6cbda5e58f
+	github.com/fsnotify/fsnotify v1.7.0
+	github.com/gabriel-vasile/mimetype v1.4.3
+	github.com/gen2brain/heic v0.3.1
+	github.com/gen2brain/webp v0.5.2
+	github.com/gomarkdown/markdown v0.0.0-20250207164621-7a1f277a159e
+	github.com/google/subcommands v1.2.0
+	github.com/hexops/gotextdiff v1.0.3
+	github.com/microcosm-cc/bluemonday v1.0.26
+	github.com/muesli/reflow v0.3.0
+	github.com/pemistahl/lingua-go v1.4.0
+	github.com/sergi/go-diff v1.3.1
+	github.com/stretchr/testify v1.8.4
+	golang.org/x/exp v0.0.0-20240119083558-1b970713d09a
 )
 
 require (
 	github.com/aymerick/douceur v0.2.0 // indirect
-	github.com/gorilla/css v1.0.0 // indirect
-	github.com/pemistahl/lingua-go v1.4.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/ebitengine/purego v0.8.1 // indirect
+	github.com/gorilla/css v1.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.15 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rivo/uniseg v0.4.6 // indirect
+	github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd // indirect
 	github.com/shopspring/decimal v1.3.1 // indirect
-	golang.org/x/exp v0.0.0-20221106115401-f9659909a136 // indirect
-	golang.org/x/net v0.12.0 // indirect
-	google.golang.org/protobuf v1.31.0 // indirect
+	github.com/tetratelabs/wazero v1.8.1 // indirect
+	golang.org/x/image v0.15.0 // indirect
+	golang.org/x/net v0.20.0 // indirect
+	golang.org/x/sys v0.21.0 // indirect
+	google.golang.org/protobuf v1.32.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,24 +1,80 @@
 github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
 github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
-github.com/dgryski/go-trigram v0.0.0-20160407183937-79ec494e1ad0 h1:b+7JSiBM+hnLQjP/lXztks5hnLt1PS46hktG9VOJgzo=
-github.com/dgryski/go-trigram v0.0.0-20160407183937-79ec494e1ad0/go.mod h1:qzKC/DpcxK67zaSHdCmIv3L9WJViHVinYXN2S7l3RM8=
-github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
-github.com/gomarkdown/markdown v0.0.0-20230716120725-531d2d74bc12 h1:uK3X/2mt4tbSGoHvbLBHUny7CKiuwUip3MArtukol4E=
-github.com/gomarkdown/markdown v0.0.0-20230716120725-531d2d74bc12/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
-github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/gorilla/css v1.0.0 h1:BQqNyPTi50JCFMTw/b67hByjMVXZRwGha6wxVGkeihY=
-github.com/gorilla/css v1.0.0/go.mod h1:Dn721qIggHpt4+EFCcTLTU/vk5ySda2ReITrtgBl60c=
-github.com/microcosm-cc/bluemonday v1.0.25 h1:4NEwSfiJ+Wva0VxN5B8OwMicaJvD8r9tlJWm9rtloEg=
-github.com/microcosm-cc/bluemonday v1.0.25/go.mod h1:ZIOjCQp1OrzBBPIJmfX4qDYFuhU02nx4bn030ixfHLE=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c=
+github.com/disintegration/imaging v1.6.2/go.mod h1:44/5580QXChDfwIclfc/PCwrr44amcmDAg8hxG0Ewe4=
+github.com/ebitengine/purego v0.8.1 h1:sdRKd6plj7KYW33EH5As6YKfe8m9zbN9JMrOjNVF/BE=
+github.com/ebitengine/purego v0.8.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/edwvee/exiffix v0.0.0-20210922235313-0f6cbda5e58f h1:RMnUwTnNR070mFAEIoqMYjNirHj8i0h79VXTYyBCyVA=
+github.com/edwvee/exiffix v0.0.0-20210922235313-0f6cbda5e58f/go.mod h1:KoE3Ti1qbQXCb3s/XGj0yApHnbnNnn1bXTtB5Auq/Vc=
+github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
+github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
+github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
+github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
+github.com/gen2brain/heic v0.3.1 h1:ClY5YTdXdIanw7pe9ZVUM9XcsqH6CCCa5CZBlm58qOs=
+github.com/gen2brain/heic v0.3.1/go.mod h1:m2sVIf02O7wfO8mJm+PvE91lnq4QYJy2hseUon7So10=
+github.com/gen2brain/webp v0.5.2 h1:aYdjbU/2L98m+bqUdkYMOIY93YC+EN3HuZLMaqgMD9U=
+github.com/gen2brain/webp v0.5.2/go.mod h1:Nb3xO5sy6MeUAHhru9H3GT7nlOQO5dKRNNlE92CZrJw=
+github.com/gomarkdown/markdown v0.0.0-20250207164621-7a1f277a159e h1:ESHlT0RVZphh4JGBz49I5R6nTdC8Qyc08vU25GQHzzQ=
+github.com/gomarkdown/markdown v0.0.0-20250207164621-7a1f277a159e/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
+github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
+github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/subcommands v1.2.0 h1:vWQspBTo2nEqTUFita5/KeEWlUL8kQObDFbub/EN9oE=
+github.com/google/subcommands v1.2.0/go.mod h1:ZjhPrFU+Olkh9WazFPsl27BQ4UPiG37m3yTrtFlrHVk=
+github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
+github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
+github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
+github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
+github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
+github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U=
+github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/microcosm-cc/bluemonday v1.0.26 h1:xbqSvqzQMeEHCqMi64VAs4d8uy6Mequs3rQ0k/Khz58=
+github.com/microcosm-cc/bluemonday v1.0.26/go.mod h1:JyzOCs9gkyQyjs+6h10UEVSe02CGwkhd72Xdqh78TWs=
+github.com/muesli/reflow v0.3.0 h1:IFsN6K9NfGtjeggFP+68I4chLZV2yIKsXJFNZ+eWh6s=
+github.com/muesli/reflow v0.3.0/go.mod h1:pbwTDkVPibjO2kyvBQRBxTWEEGDGq0FlB1BIKtnHY/8=
 github.com/pemistahl/lingua-go v1.4.0 h1:ifYhthrlW7iO4icdubwlduYnmwU37V1sbNrwhKBR4rM=
 github.com/pemistahl/lingua-go v1.4.0/go.mod h1:ECuM1Hp/3hvyh7k8aWSqNCPlTxLemFZsRjocUf3KgME=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.6 h1:Sovz9sDSwbOz9tgUy8JpT+KgCkPYJEN/oYzlJiYTNLg=
+github.com/rivo/uniseg v0.4.6/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd h1:CmH9+J6ZSsIjUK3dcGsnCnO41eRBOnY12zwkn5qVwgc=
+github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk=
+github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
+github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
 github.com/shopspring/decimal v1.3.1 h1:2Usl1nmF/WZucqkFZhnfFYxxxu8LG21F6nPQBE5gKV8=
 github.com/shopspring/decimal v1.3.1/go.mod h1:DKyhrW/HYNuLGql+MJL6WCR6knT2jwCFRcu2hWCYk4o=
-golang.org/x/exp v0.0.0-20221106115401-f9659909a136 h1:Fq7F/w7MAa1KJ5bt2aJ62ihqp9HDcRuyILskkpIAurw=
-golang.org/x/exp v0.0.0-20221106115401-f9659909a136/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc=
-golang.org/x/net v0.12.0 h1:cfawfvKITfUsFCeJIHJrbSxpeu/E81khclypR0GVT50=
-golang.org/x/net v0.12.0/go.mod h1:zEVYFnQC7m/vmpQFELhcD1EWkZlX69l4oqgmer6hfKA=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
-google.golang.org/protobuf v1.31.0 h1:g0LDEJHgrBl9N9r17Ru3sqWhkIx2NB67okBHPwC7hs8=
-google.golang.org/protobuf v1.31.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/tetratelabs/wazero v1.8.1 h1:NrcgVbWfkWvVc4UtT4LRLDf91PsOzDzefMdwhLfA550=
+github.com/tetratelabs/wazero v1.8.1/go.mod h1:yAI0XTsMBhREkM/YDAK/zNou3GoiAce1P6+rp/wQhjs=
+golang.org/x/exp v0.0.0-20240119083558-1b970713d09a h1:Q8/wZp0KX97QFTc2ywcOE0YRjZPVIx+MXInMzdvQqcA=
+golang.org/x/exp v0.0.0-20240119083558-1b970713d09a/go.mod h1:idGWGoKP1toJGkd5/ig9ZLuPcZBC3ewk7SzmH0uou08=
+golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
+golang.org/x/image v0.15.0 h1:kOELfmgrmJlw4Cdb7g/QGuB3CvDrXbqEIww/pNtNBm8=
+golang.org/x/image v0.15.0/go.mod h1:HUYqC05R2ZcZ3ejNQsIHQDQiwWM4JBqmm6MKANTp4LE=
+golang.org/x/net v0.20.0 h1:aCL9BSgETF1k+blQaYUBx9hJ9LOGP3gAVemcZlf1Kpo=
+golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
+golang.org/x/sys v0.21.0 h1:rF+pYz3DAGSQAxAu1CbC7catZg4ebC4UIeIhKxBZvws=
+golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+google.golang.org/protobuf v1.32.0 h1:pPC6BG5ex8PDFnkbrGU3EixyhKcQ2aDuBS36lqK/C7I=
+google.golang.org/protobuf v1.32.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

hashtags_cmd.go

@@ -0,0 +1,208 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	"github.com/gomarkdown/markdown"
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/hexops/gotextdiff"
+	"github.com/hexops/gotextdiff/myers"
+	"github.com/hexops/gotextdiff/span"
+	"io"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+type hashtagsCmd struct {
+	update bool
+	dryRun bool
+}
+
+func (cmd *hashtagsCmd) SetFlags(f *flag.FlagSet) {
+	f.BoolVar(&cmd.update, "update", false, "create and update hashtag pages")
+	f.BoolVar(&cmd.dryRun, "dry-run", false, "only report the changes it would make")
+}
+
+func (*hashtagsCmd) Name() string     { return "hashtags" }
+func (*hashtagsCmd) Synopsis() string { return "hashtag overview" }
+func (*hashtagsCmd) Usage() string {
+	return `hashtags:
+  Count the use of all hashtags and list them, separated by a tabulator.
+`
+}
+
+func (cmd *hashtagsCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	if cmd.update {
+		return hashtagsUpdateCli(os.Stdout, cmd.dryRun)
+	}
+	return hashtagsCli(os.Stdout)
+}
+
+// hashtagsCli runs the hashtags command on the command line. It is used
+// here with an io.Writer for easy testing.
+func hashtagsCli(w io.Writer) subcommands.ExitStatus {
+	index.load()
+	index.RLock()
+	defer index.RUnlock()
+
+	type hashtag struct {
+		label string
+		count int
+	}
+
+	hashtags := []hashtag{}
+
+	for token, docids := range index.token {
+		hashtags = append(hashtags, hashtag{label: token, count: len(docids)})
+	}
+
+	sort.Slice(hashtags, func(i, j int) bool {
+		return hashtags[i].count > hashtags[j].count
+	})
+
+	fmt.Fprintln(w, "Rank\tHashtag\tCount")
+	for i, hashtag := range hashtags {
+		fmt.Fprintf(w, "%d\t%s\t%d\n", i+1, hashtag.label, hashtag.count)
+	}
+
+	return subcommands.ExitSuccess
+}
+
+// hashtagsUpdateCli runs the hashtags command on the command line and creates and updates the hashtag pages in the
+// current directory. That is, pages in subdirectories are skipped! It is used here with an io.Writer for easy testing.
+func hashtagsUpdateCli(w io.Writer, dryRun bool) subcommands.ExitStatus {
+	index.load()
+	// no locking necessary since this is for the command-line
+	namesMap := make(map[string]string)
+	for hashtag, docids := range index.token {
+		if len(docids) <= 5 {
+			if dryRun {
+				fmt.Fprintf(w, "Skipping #%s because there are not enough entries (%d)\n", hashtag, len(docids))
+			}
+			continue
+		}
+		title, ok := namesMap[hashtag]
+		if (!ok) {
+			title = hashtagName(namesMap, hashtag, docids)
+			namesMap[hashtag] = title
+		}
+		pageName := strings.ReplaceAll(title, " ", "_")
+		h, err := loadPage(pageName)
+		original := ""
+		new := false
+		if err != nil {
+			new = true
+			h = &Page{Name: pageName, Body: []byte("# " + title + "\n\n#" + pageName + "\n\nBlog posts:\n\n")}
+		} else {
+			original = string(h.Body)
+		}
+		for _, docid := range docids {
+			name := index.documents[docid]
+			if strings.Contains(name, "/") {
+				continue
+			}
+			p, err := loadPage(name)
+			if err != nil {
+				fmt.Fprintf(w, "Loading %s: %s\n", name, err)
+				return subcommands.ExitFailure
+			}
+			if !p.IsBlog() {
+				continue
+			}
+			p.handleTitle(false)
+			if p.Title == "" {
+				p.Title = p.Name
+			}
+			esc := nameEscape(p.Base())
+			link := "* [" + p.Title + "](" + esc + ")\n"
+			// I guess & used to get escaped and now no longer does
+			re := regexp.MustCompile(`(?m)^\* \[[^\]]+\]\(` + strings.ReplaceAll(esc, "&", "(&|%26)") + `\)\n`)
+			addLinkToPage(h, link, re)
+		}
+		// only save if something changed
+		if string(h.Body) != original {
+			if dryRun {
+				if new {
+					fmt.Fprintf(w, "Creating %s.md\n", title)
+				} else {
+					fmt.Fprintf(w, "Updating %s.md\n", title)
+				}
+				fn := h.Name + ".md"
+				edits := myers.ComputeEdits(span.URIFromPath(fn), original, string(h.Body))
+				diff := fmt.Sprint(gotextdiff.ToUnified(fn + "~", fn, original, edits))
+				fmt.Fprint(w, diff)
+			} else {
+				err = h.save()
+				if err != nil {
+					fmt.Fprintf(w, "Saving hashtag %s failed: %s", hashtag, err)
+					return subcommands.ExitFailure
+				}
+			}
+		}
+	}
+	return subcommands.ExitSuccess
+}
+
+// Go through all the documents in the same directory and look for hashtag matches in the rendered HTML in order to
+// determine the most likely capitalization.
+func hashtagName (namesMap map[string]string, hashtag string, docids []docid) string {
+	candidate := make(map[string]int)
+	var mostPopular string
+	for _, docid := range docids {
+		name := index.documents[docid]
+		if strings.Contains(name, "/") {
+			continue
+		}
+		p, err := loadPage(name)
+		if err != nil {
+			continue
+		}
+		// parsing finds all the hashtags
+		parser, _ := wikiParser()
+		doc := markdown.Parse(p.Body, parser)
+		ast.WalkFunc(doc, func(node ast.Node, entering bool) ast.WalkStatus {
+			if entering {
+				switch v := node.(type) {
+				case *ast.Link:
+					for _, attr := range v.AdditionalAttributes {
+						if attr == `class="tag"` {
+							tagName := []byte("")
+							ast.WalkFunc(v, func(node ast.Node, entering bool) ast.WalkStatus {
+								if entering && node.AsLeaf() != nil {
+									tagName = append(tagName, node.AsLeaf().Literal...)
+								}
+								return ast.GoToNext
+							})
+							tag := string(tagName[1:])
+							if strings.EqualFold(hashtag, strings.ReplaceAll(tag, " ", "_")) {
+								_, ok := candidate[tag]
+								if ok {
+									candidate[tag] += 1
+								} else {
+									candidate[tag] = 1
+								}
+							}
+						}
+					}
+				}
+			}
+			return ast.GoToNext
+		})
+		count := 0
+		for key, val := range candidate {
+			if val > count {
+				mostPopular = key
+				count = val
+			}
+		}
+		// shortcut
+		if count >= 5 {
+			return mostPopular
+		}
+	}
+	return mostPopular
+}

hashtags_cmd_test.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestHashtagsCmd(t *testing.T) {
+	cleanup(t, "testdata/hashtag")
+	p := &Page{Name: "testdata/hashtag/hash", Body: []byte(`# Hash
+
+I hope for a time
+not like today, relentless,
+just crocus blooming
+
+#Crocus`)}
+	p.save()
+	b := new(bytes.Buffer)
+	s := hashtagsCli(b)
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	x := b.String()
+	assert.Contains(t, x, "crocus\t")
+}

highlight.go

@@ -4,10 +4,8 @@ import (
 	"regexp"
 )
 
-// highlight splits the query string q into terms and highlights them
-// using the bold tag. Return the highlighted string.
-// This assumes that q already has all its meta characters quoted.
-func highlight(q string, re *regexp.Regexp, s string) string {
+// highlight matches for the regular expression using the bold tag.
+func highlight(re *regexp.Regexp, s string) string {
 	s = re.ReplaceAllString(s, "<b>$1</b>")
 	return s
 }

highlight_test.go

@@ -16,7 +16,7 @@ No birds to be heard.`
 
 	q := "window"
 	re, _ := re(q)
-	r := highlight(q, re, s)
+	r := highlight(re, s)
 	if r != h {
 		t.Logf("The highlighting is wrong in ｢%s｣", r)
 		t.Fail()
@@ -35,7 +35,7 @@ I hear the fountain`
 
 	q := "shout out"
 	re, _ := re(q)
-	r := highlight(q, re, s)
+	r := highlight(re, s)
 	if r != h {
 		t.Logf("The highlighting is wrong in ｢%s｣", r)
 		t.Fail()

html_cmd.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	"io"
+	"os"
+	"strings"
+)
+
+type htmlCmd struct {
+	template string
+}
+
+func (*htmlCmd) Name() string     { return "html" }
+func (*htmlCmd) Synopsis() string { return "render a page as HTML" }
+func (*htmlCmd) Usage() string {
+	return `html [-template <template name>] <page name> ...:
+  Render one or more pages as HTML.
+  Use a single - to read Markdown from stdin.
+`
+}
+
+func (cmd *htmlCmd) SetFlags(f *flag.FlagSet) {
+	f.StringVar(&cmd.template, "template", "",
+		"use the given HTML file as a template (probably view.html or static.html).")
+}
+
+func (cmd *htmlCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	return htmlCli(os.Stdout, cmd.template, f.Args())
+}
+
+func htmlCli(w io.Writer, template string, args []string) subcommands.ExitStatus {
+	if len(args) == 1 && args[0] == "-" {
+		body, err := io.ReadAll(os.Stdin)
+		if err != nil {
+			fmt.Fprintf(w, "Cannot read from stdin: %s\n", err)
+			return subcommands.ExitFailure
+		}
+		p := &Page{Name: "stdin", Body: body}
+		return p.printHtml(w, template)
+	}
+	for _, name := range args {
+		if !strings.HasSuffix(name, ".md") {
+			fmt.Fprintf(os.Stderr, "%s does not end in '.md'\n", name)
+			return subcommands.ExitFailure
+		}
+		name = name[0:len(name)-3]
+		p, err := loadPage(name)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Cannot load %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		status := p.printHtml(w, template)
+		if status != subcommands.ExitSuccess {
+			return status
+		}
+	}
+	return subcommands.ExitSuccess
+}
+
+func (p *Page) printHtml(w io.Writer, template string) subcommands.ExitStatus {
+	if len(template) > 0 {
+		t := template
+		loadTemplates()
+		p.handleTitle(true)
+		p.renderHtml()
+		err := templates.template[t].Execute(w, p)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Cannot execute %s template for %s: %s\n", t, p.Name, err)
+			return subcommands.ExitFailure
+		}
+	} else {
+		// do not handle title
+		p.renderHtml()
+		fmt.Fprintln(w, p.Html)
+	}
+	return subcommands.ExitSuccess
+}

html_cmd_test.go

@@ -0,0 +1,24 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestHtmlCmd(t *testing.T) {
+	b := new(bytes.Buffer)
+	s := htmlCli(b, "", []string{"index.md"})
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	r := `<h1 id="welcome-to-oddμ">Welcome to Oddμ</h1>
+
+<p>Hello! 🙃</p>
+
+<p>Check out the <a href="README">README</a> and <a href="themes">themes</a>.</p>
+
+<p>Or <a href="test">create a new page</a>.</p>
+
+`
+	assert.Equal(t, b.String(), r)
+}

index.go

@@ -0,0 +1,252 @@
+// Read Artem Krylysov's blog post on full text search as an
+// introduction.
+// https://artem.krylysov.com/blog/2020/07/28/lets-build-a-full-text-search-engine/
+
+package main
+
+import (
+	"golang.org/x/exp/constraints"
+	"html/template"
+	"io/fs"
+	"log"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+)
+
+type docid uint
+
+// ImageData holds the data used to search for images using the alt-text. Title is the alt-text; Name is the complete
+// URL including path (which is important since the image link itself only has the URL relative to the page in which it
+// is found; and Html is a copy of the Title with highlighting of a term as applied when searching. This is temporary.
+// It depends on the fact that Title is always plain text.
+type ImageData struct {
+	Title, Name string
+	Html        template.HTML
+}
+
+// indexStore controls access to the maps used for search. Make sure to lock and unlock as appropriate.
+type indexStore struct {
+	sync.RWMutex
+
+	// next_id is the number of the next document added to the index
+	next_id docid
+
+	// index is an inverted index mapping tokens to document ids.
+	token map[string][]docid
+
+	// documents is a map, mapping document ids to page names.
+	documents map[docid]string
+
+	// titles is a map, mapping page names to titles.
+	titles map[string]string
+
+	// images is a map, mapping pages names to alt text to an array of image data.
+	images map[string][]ImageData
+}
+
+var index indexStore
+
+func init() {
+	index.reset()
+}
+
+// reset the index. This assumes that the index is locked. It's useful for tests.
+func (idx *indexStore) reset() {
+	idx.next_id = 0
+	idx.token = make(map[string][]docid)
+	idx.documents = make(map[docid]string)
+	idx.titles = make(map[string]string)
+	idx.images = make(map[string][]ImageData)
+}
+
+// addDocument adds the text as a new document. This assumes that the index is locked!
+// The hashtags (only!) are used as tokens. They are stored in lower case.
+func (idx *indexStore) addDocument(text []byte) docid {
+	id := idx.next_id
+	idx.next_id++
+	for _, token := range hashtags(text) {
+		token = strings.ToLower(token)
+		ids := idx.token[token]
+		// Don't add same ID more than once. Checking the last
+		// position of the []docid works because the id is
+		// always a new one, i.e. the last one, if at all.
+		if len(ids) > 0 && ids[len(ids)-1] == id {
+			continue
+		}
+		idx.token[token] = append(ids, id)
+	}
+	return id
+}
+
+// deleteDocument deletes all references to the id. The id can no longer be used. This assumes that the index is locked.
+func (idx *indexStore) deleteDocument(id docid) {
+	// Looping through all tokens makes sense if there are few tokens (like hashtags). It doesn't make sense if the
+	// number of tokens is large (like for full-text search or a trigram index).
+	for token, ids := range idx.token {
+		// If the token appears only in this document, remove the whole entry.
+		if len(ids) == 1 && ids[0] == id {
+			delete(idx.token, token)
+			continue
+		}
+		// Otherwise, remove the token from the index.
+		i := sort.Search(len(ids), func(i int) bool { return ids[i] >= id })
+		if i != -1 && i < len(ids) && ids[i] == id {
+			copy(ids[i:], ids[i+1:])
+			idx.token[token] = ids[:len(ids)-1]
+			continue
+		}
+	}
+}
+
+// deletePageName determines the document id based on the page name and calls deleteDocument to delete all references.
+// This assumes that the index is unlocked.
+func (idx *indexStore) deletePageName(name string) {
+	idx.Lock()
+	defer idx.Unlock()
+	var id docid
+	// Reverse lookup! At least it's in memory.
+	for key, value := range idx.documents {
+		if value == name {
+			id = key
+			break
+		}
+	}
+	if id != 0 {
+		idx.deleteDocument(id)
+		delete(idx.documents, id)
+	}
+	delete(idx.titles, name)
+	delete(idx.images, name)
+}
+
+// remove the page from the index. Do this when deleting a page. This assumes that the index is unlocked.
+func (idx *indexStore) remove(p *Page) {
+	idx.deletePageName(p.Name)
+}
+
+// load loads all the pages and indexes them. This takes a while. It returns the number of pages indexed.
+func (idx *indexStore) load() (int, error) {
+	idx.Lock()
+	defer idx.Unlock()
+	err := filepath.Walk(".", idx.walk)
+	if err != nil {
+		return 0, err
+	}
+	n := len(idx.documents)
+	return n, nil
+}
+
+// walk reads a file and adds it to the index. This assumes that the index is locked.
+func (idx *indexStore) walk(fp string, info fs.FileInfo, err error) error {
+	if err != nil {
+		return err
+	}
+	// skip hidden directories and files
+	if fp != "." && strings.HasPrefix(filepath.Base(fp), ".") {
+		if info.IsDir() {
+			return filepath.SkipDir
+		} else {
+			return nil
+		}
+	}
+	// skipp all but page files
+	if !strings.HasSuffix(fp, ".md") {
+		return nil
+	}
+	p, err := loadPage(strings.TrimSuffix(filepath.ToSlash(fp), ".md"))
+	if err != nil {
+		return err
+	}
+	p.handleTitle(false)
+	idx.addPage(p)
+	return nil
+}
+
+// addPage adds a page to the index. This assumes that the index is locked.
+func (idx *indexStore) addPage(p *Page) {
+	id := idx.addDocument(p.Body)
+	idx.documents[id] = p.Name
+	p.handleTitle(false)
+	idx.titles[p.Name] = p.Title
+	idx.images[p.Name] = p.images()
+}
+
+// add a page to the index. This assumes that the index is unlocked.
+func (idx *indexStore) add(p *Page) {
+	idx.Lock()
+	defer idx.Unlock()
+	idx.addPage(p)
+}
+
+// dump prints the index to the log for debugging.
+func (idx *indexStore) dump() {
+	idx.RLock()
+	defer idx.RUnlock()
+	for token, ids := range idx.token {
+		log.Printf("%s: %v", token, ids)
+	}
+}
+
+// updateIndex updates the index for a single page.
+func (idx *indexStore) update(p *Page) {
+	idx.remove(p)
+	idx.add(p)
+}
+
+// search searches the index. The query string is parsed for tokens. Each token is turned to lower cased and looked up
+// in the index. Each page in the result must contain all the tokens. Returns page names.
+func (idx *indexStore) search(q string) []string {
+	idx.RLock()
+	defer idx.RUnlock()
+	names := make([]string, 0)
+	hashtags := hashtags([]byte(q))
+	if len(hashtags) > 0 {
+		var r []docid
+		for _, token := range hashtags {
+			token = strings.ToLower(token)
+			if ids, ok := idx.token[token]; ok {
+				if r == nil {
+					r = ids
+				} else {
+					r = intersection(r, ids)
+				}
+			} else {
+				// Token doesn't exist therefore abort search.
+				return nil
+			}
+		}
+		for _, id := range r {
+			names = append(names, idx.documents[id])
+		}
+	} else {
+		for _, name := range idx.documents {
+			names = append(names, name)
+		}
+	}
+	return names
+}
+
+// intersection returns the set intersection between a and b.
+// a and b have to be sorted in ascending order and contain no duplicates.
+func intersection[T constraints.Ordered](a []T, b []T) []T {
+	maxLen := len(a)
+	if len(b) > maxLen {
+		maxLen = len(b)
+	}
+	r := make([]T, 0, maxLen)
+	var i, j int
+	for i < len(a) && j < len(b) {
+		if a[i] < b[j] {
+			i++
+		} else if a[i] > b[j] {
+			j++
+		} else {
+			r = append(r, a[i])
+			i++
+			j++
+		}
+	}
+	return r
+}

index.md

@@ -1,5 +1,7 @@
-# Welcome to Oddµ
+# Welcome to Oddμ
 
 Hello! 🙃
 
-Check out the [README](README).
+Check out the [[README]] and [[themes]].
+
+Or [create a new page](test).

index_test.go

@@ -0,0 +1,118 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"strings"
+	"testing"
+)
+
+func TestIndexAdd(t *testing.T) {
+	idx := &indexStore{}
+	idx.reset()
+	idx.Lock()
+	defer idx.Unlock()
+	tag := "hello"
+	id := idx.addDocument([]byte("oh hi #" + tag))
+	assert.Contains(t, idx.token, tag)
+	idx.deleteDocument(id)
+	assert.NotContains(t, idx.token, tag)
+}
+
+// TestIndex relies on README.md being indexed
+func TestIndex(t *testing.T) {
+	index.load()
+	q := "Oddμ"
+	pages, _ := search(q, "", "", 1, false)
+	assert.NotZero(t, len(pages))
+	for _, p := range pages {
+		assert.NotContains(t, p.Title, "<b>")
+		assert.True(t, strings.Contains(string(p.Body), q) || strings.Contains(string(p.Title), q))
+		assert.NotZero(t, p.Score, "Score %d for %s", p.Score, p.Name)
+	}
+}
+
+// Lower case hashtag!
+func TestSearchHashtag(t *testing.T) {
+	cleanup(t, "testdata/search-hashtag")
+	p := &Page{Name: "testdata/search-hashtag/search", Body: []byte(`# Search
+
+I'm back in this room
+Shelf, table, chair, and shelf again
+Where are my glasses?
+
+#Searching`)}
+	p.save()
+	index.load()
+	pages, _ := search("#searching", "", "", 1, false)
+	assert.NotZero(t, len(pages))
+}
+
+func TestIndexUpdates(t *testing.T) {
+	cleanup(t, "testdata/update")
+	name := "testdata/update/test"
+	index.load()
+	p := &Page{Name: name, Body: []byte("#Old Name\nThis is a test.")}
+	p.save()
+
+	// Find the phrase
+	pages, _ := search("This is a test", "", "", 1, false)
+	found := false
+	for _, p := range pages {
+		if p.Name == name {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found)
+
+	// Find the phrase, case insensitive
+	pages, _ = search("this is a test", "", "", 1, false)
+	found = false
+	for _, p := range pages {
+		if p.Name == name {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found)
+
+	// Find some words
+	pages, _ = search("this test", "", "", 1, false)
+	found = false
+	for _, p := range pages {
+		if p.Name == name {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found)
+
+	// Update the page and no longer find it with the old phrase
+	p = &Page{Name: name, Body: []byte("# New page\nGuvf vf n grfg.")}
+	p.save()
+	pages, _ = search("This is a test", "", "", 1, false)
+	found = false
+	for _, p := range pages {
+		if p.Name == name {
+			found = true
+			break
+		}
+	}
+	assert.False(t, found)
+
+	// Find page using a new word
+	pages, _ = search("Guvf", "", "", 1, false)
+	found = false
+	for _, p := range pages {
+		if p.Name == name {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found)
+
+	// Make sure the title was updated
+	index.RLock()
+	defer index.RUnlock()
+	assert.Equal(t, "New page", index.titles[name])
+}

languages.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"errors"
+	"github.com/pemistahl/lingua-go"
+	"os"
+	"strings"
+)
+
+// getLanguages returns the environment variable ODDMU_LANGUAGES or all languages.
+func getLanguages() ([]lingua.Language, error) {
+	v := os.Getenv("ODDMU_LANGUAGES")
+	if v == "" {
+		return lingua.AllLanguages(), nil
+	}
+	codes := strings.Split(v, ",")
+	if len(codes) == 1 {
+		return nil, errors.New("detection unnecessary")
+	}
+
+	var langs []lingua.Language
+	for _, lang := range codes {
+		langs = append(langs, lingua.GetLanguageFromIsoCode639_1(lingua.GetIsoCode639_1FromValue(lang)))
+	}
+	return langs, nil
+}
+
+// detector is the LanguageDetector initialized at startup by loadLanguages.
+var detector lingua.LanguageDetector
+
+// loadLanguages initializes the detector using the languages returned by getLanguages and returns the number of
+// languages loaded. If this is skipped, no language detection happens and the templates cannot use {{.Language}} to use
+// this. Usually this is used for correct hyphenation by the browser.
+func loadLanguages() int {
+	langs, err := getLanguages()
+	if err == nil {
+		detector = lingua.NewLanguageDetectorBuilder().
+			FromLanguages(langs...).
+			WithPreloadedLanguageModels().
+			WithLowAccuracyMode().
+			Build()
+	} else {
+		detector = nil
+	}
+	return len(langs)
+}
+
+// language returns the language used for a string, as a lower case
+// ISO 639-1 string, e.g. "en" or "de".
+func language(s string) string {
+	if detector == nil {
+		return os.Getenv("ODDMU_LANGUAGES")
+	}
+	if language, ok := detector.DetectLanguageOf(s); ok {
+		return strings.ToLower(language.IsoCode639_1().String())
+	}
+	return ""
+}
+
+// Language returns the language used for the page, as a lower case
+// ISO 639-1 string, e.g. "en" or "de".
+func (p *Page) Language() string {
+	return language(p.plainText())
+}

languages_test.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"os"
+	"testing"
+)
+
+func TestAllLanguage(t *testing.T) {
+	os.Unsetenv("ODDMU_LANGUAGES")
+	loadLanguages()
+	l := language(`
+My back hurts at night
+My shoulders won't budge today
+Winter bones I say`)
+	assert.Equal(t, "en", l)
+}
+
+func TestSomeLanguages(t *testing.T) {
+	os.Setenv("ODDMU_LANGUAGES", "en,de")
+	loadLanguages()
+	l := language(`
+Kühle Morgenluft
+Keine Amsel singt heute
+Mensch im Dämmerlicht
+`)
+	assert.Equal(t, "de", l)
+}
+
+func TestOneLanguages(t *testing.T) {
+	os.Setenv("ODDMU_LANGUAGES", "en")
+	loadLanguages()
+	l := language(`
+Schwer wiegt die Luft hier
+Atme ein, ermahn' ich mich
+Erinnerungen
+`)
+	assert.Equal(t, "en", l)
+}
+
+func TestWrongLanguages(t *testing.T) {
+	os.Setenv("ODDMU_LANGUAGES", "de,fr")
+	loadLanguages()
+	l := language(`
+Something drifts down there
+Head submerged oh god a man
+Drowning as we stare
+`)
+	assert.NotEqual(t, "en", l)
+}

links_cmd.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	"io"
+	"os"
+	"strings"
+)
+
+type linksCmd struct {
+}
+
+func (cmd *linksCmd) SetFlags(f *flag.FlagSet) {
+}
+
+func (*linksCmd) Name() string     { return "links" }
+func (*linksCmd) Synopsis() string { return "list outgoing links for a page" }
+func (*linksCmd) Usage() string {
+	return `links <page name> ...:
+  Lists all the links on a page. Use a single - to read Markdown from stdin.
+`
+}
+
+func (cmd *linksCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	return linksCli(os.Stdout, f.Args())
+}
+
+// linksCli runs the links command on the command line. It is used
+// here with an io.Writer for easy testing.
+func linksCli(w io.Writer, args []string) subcommands.ExitStatus {
+	if len(args) == 1 && args[0] == "-" {
+		body, err := io.ReadAll(os.Stdin)
+		if err != nil {
+			fmt.Fprintf(w, "Cannot read from stdin: %s\n", err)
+			return subcommands.ExitFailure
+		}
+		p := &Page{Body: body}
+		for _, link := range p.links() {
+			fmt.Fprintln(w, link)
+		}
+		return subcommands.ExitSuccess
+	}
+	for _, name := range args {
+		if !strings.HasSuffix(name, ".md") {
+			fmt.Fprintf(os.Stderr, "%s does not end in '.md'\n", name)
+			return subcommands.ExitFailure
+		}
+		name = name[0:len(name)-3]
+		p, err := loadPage(name)
+		if err != nil {
+			fmt.Fprintf(w, "Loading %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		for _, link := range p.links() {
+			fmt.Fprintln(w, link)
+		}
+	}
+	return subcommands.ExitSuccess
+}

links_cmd_test.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestLinksCmd(t *testing.T) {
+	b := new(bytes.Buffer)
+	s := linksCli(b, []string{"README.md"})
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	x := b.String()
+	assert.Contains(t, x, "https://alexschroeder.ch/view/oddmu/oddmu.1\n")
+}

list_cmd.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type listCmd struct {
+	dir string
+}
+
+func (cmd *listCmd) SetFlags(f *flag.FlagSet) {
+	f.StringVar(&cmd.dir, "dir", "", "list only pages within this sub-directory")
+}
+
+func (*listCmd) Name() string     { return "list" }
+func (*listCmd) Synopsis() string { return "list pages with name and title" }
+func (*listCmd) Usage() string {
+	return `list [-dir string]:
+  List all pages with name and title, separated by a tabulator.
+`
+}
+
+func (cmd *listCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	return listCli(os.Stdout, cmd.dir, f.Args())
+}
+
+// listCli runs the list command on the command line. It is used
+// here with an io.Writer for easy testing.
+func listCli(w io.Writer, dir string, args []string) subcommands.ExitStatus {
+	dir, err := checkDir(dir)
+	if err != nil {
+		return subcommands.ExitFailure
+	}
+	index.load()
+	index.RLock()
+	defer index.RUnlock()
+	for name, title := range index.titles {
+		if strings.HasPrefix(name, dir) {
+			name = strings.Replace(name, dir, "", 1)
+			fmt.Fprintf(w, "%s\t%s\n", name, title)
+		}
+	}
+	return subcommands.ExitSuccess
+}
+
+// checkDir returns an error if the directory doesn't exist. If if exists, it returns a copy ending in a slash suiteable
+// for substring matching of page names.
+func checkDir(dir string) (string, error) {
+	if dir != "" {
+		fi, err := os.Stat(filepath.FromSlash(dir))
+		if err != nil {
+			fmt.Println(err)
+			return "", err
+		}
+		if !fi.IsDir() {
+			fmt.Println("This is not a sub-directory:", dir)
+			return "", err
+		}
+		if !strings.HasSuffix(dir, "/") {
+			dir += "/"
+		}
+	}
+	return dir, nil
+}

list_cmd_test.go

@@ -0,0 +1,31 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestListCmd(t *testing.T) {
+	b := new(bytes.Buffer)
+	s := listCli(b, "", nil)
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	x := b.String()
+	assert.Contains(t, x, "README\tOddμ: A minimal wiki\n")
+	assert.Contains(t, x, "index\tWelcome to Oddμ\n")
+}
+
+func TestListSubdirCmd(t *testing.T) {
+	cleanup(t, "testdata/list")
+	p := &Page{Name: "testdata/list/red", Body: []byte(`# Red
+Shifting darkness waits
+I open my eyes in fear
+And see the red dot`)}
+	p.save()
+	b := new(bytes.Buffer)
+	s := listCli(b, "testdata/list", nil)
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	x := b.String()
+	assert.Contains(t, x, "red\tRed\n")
+}

man/.gitignore

@@ -0,0 +1 @@
+*.md

man/Makefile

@@ -0,0 +1,55 @@
+TEXT=$(wildcard *.txt)
+MAN=$(patsubst %.txt,%,${TEXT})
+HTML=$(patsubst %.txt,%.html,${TEXT})
+MD=$(patsubst %.txt,%.md,${TEXT})
+
+help:
+	@echo Help for Oddmu Documentation
+	@echo ============================
+	@echo make man
+	@echo "    regenerate man pages"
+	@echo make html
+	@echo "    generate HTML pages"
+	@echo make md
+	@echo "    generate Markdown pages"
+	@echo make clean
+	@echo "    delete HTML and Markdown pages"
+	@echo make realclean
+	@echo "    delete HTML, Markdown and man pages"
+
+man: ${MAN}
+
+%: %.txt
+	scdoc < $< > $@
+
+html: ${HTML}
+
+%.html: %.md
+	@echo Making $@
+	@echo '<!DOCTYPE html>' > $@
+	@oddmu html $< | sed --regexp-extended \
+	  -e 's/<a href="(oddmu[a-z.-]*.[1-9])">([^<>]*)<\/a>/<a href="\1.html">\2<\/a>/g' >> $@
+
+md: ${MD}
+
+%.md: %.txt
+	@echo Making $@
+	@perl scdoc-to-markdown < $< > $@
+
+README.md: ../README.md
+	@echo Making $@
+	@sed --regexp-extended \
+	  -e 's/\]\(.*\/(.*)\.txt\)/](\1)/' \
+	  < $< > $@
+
+upload: ${MD} README.md
+	rsync --itemize-changes --archive *.md sibirocobombus:alexschroeder.ch/wiki/oddmu/
+	make clean
+
+clean:
+	@echo Removing HTML and Markdown files
+	@rm --force ${HTML} ${MD} README.md
+
+realclean: clean
+	@echo Removing man pages
+	@rm --force ${MAN}

man/oddmu-apache.5

@@ -0,0 +1,406 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-APACHE" "5" "2025-07-16"
+.PP
+.SH NAME
+.PP
+oddmu-apache - how to setup Apache as a reverse proxy for Oddmu
+.PP
+.SH DESCRIPTION
+.PP
+The oddmu program serves the current working directory as a wiki on port 8080.\&
+This is an unpriviledged port so an ordinary user account can do this.\&
+Alternatively, you can reverse proxy HTTP over a Unix-domain socket,
+as shown later.\&
+.PP
+The best way to protect the wiki against vandalism and spam is to use a regular
+web server as reverse proxy.\& This page explains how to setup Apache on Debian to
+do this.\&
+.PP
+.SH CONFIGURATION
+.PP
+HTTPS is not part of Oddmu.\& You probably want to configure this in your
+webserver.\& I guess you could use stunnel, too.\& If you'\&re using Apache, you can
+use "mod_md" to manage your domain.\&
+.PP
+The examples below use the domain "transjovian.\&org" and the Apache installation
+is the one that comes with Debian.\&
+.PP
+The site itself is configured in a file called
+"/etc/apache2/sites-available/transjovian.\&conf" and a link points there from
+"/etc/apache2/sites-enabled".\& Create this link using \fIa2ensite\fR(1).\&
+.PP
+.nf
+.RS 4
+MDomain transjovian\&.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder\&.ch
+
+<VirtualHost *:80>
+  ServerName transjovian\&.org
+  Redirect "/" "https://transjovian\&.org/"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian\&.org
+  SSLEngine on
+  ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(\&.*))?$" 
+                 "http://localhost:8080/$1"
+</VirtualHost>
+.fi
+.RE
+.PP
+First, it manages the domain, getting the necessary certificates.\& It redirects
+regular HTTP traffic from port 80 to port 443.\& It turns on the SSL engine for
+port 443.\& It proxies the requests for Oddmu to port 8080.\& Importantly, it
+doesn'\&t send \fIall\fR the requests to Oddmu.\& This allows us to still host static
+files using the web server (see \fBServe static files\fR).\&
+.PP
+This is what happens:
+.PP
+.PD 0
+.IP \(bu 4
+The user tells the browser to visit "transjovian.\&org"
+.IP \(bu 4
+The browser sends a request for "http://transjovian.\&org" (on port 80)
+.IP \(bu 4
+Apache redirects this to "https://transjovian.\&org/" by default (now on port 443)
+.IP \(bu 4
+This is proxied to "http://transjovian.\&org:8080/" (now on port 8080)
+.PD
+.PP
+Restart the server, gracefully:
+.PP
+.nf
+.RS 4
+apachectl graceful
+.fi
+.RE
+.PP
+In a situation where Apache acts as a reverse proxy, you can prevent some
+actions from being proxied.\& If you don'\&t want to allow strangers to make
+changes, search or archive the site, use a limited setup like the following:
+.PP
+.nf
+.RS 4
+MDomain transjovian\&.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder\&.ch
+
+<VirtualHost *:80>
+  ServerName transjovian\&.org
+  Redirect "/" "https://transjovian\&.org/"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian\&.org
+  SSLEngine on
+  ProxyPassMatch "^/(view/\&.*)?$" "http://localhost:8080/$1"
+</VirtualHost>
+.fi
+.RE
+.PP
+You'\&ll need to edit the source pages some other way.\& Edit them locally and
+upload them using rsync; edit them remotely using an editor that can do this;
+use SSHFS to mount the remote directory locally for editing; use \fIstunnel\fR(8) to
+access the remote wiki on the local port 8080 for editing.\& There are probably a
+lot more such options available.\& All of them have the drawback that they'\&re
+probably not easy to use when on a mobile phone.\&
+.PP
+.SS Allow HTTP for viewing
+.PP
+When looking at pages, you might want to allow HTTP since no password is
+required.\& Therefore, proxy the read-only requests from the virtual host on port
+80 to the wiki instead of redirecting them to port 443.\&
+.PP
+.nf
+.RS 4
+MDomain transjovian\&.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder\&.ch
+
+<VirtualHost *:80>
+  ServerName transjovian\&.org
+  ProxyPassMatch "^/((view|diff|search|archive)/(\&.*))?$" 
+                 "http://localhost:8080/$1"
+  RedirectMatch  "^/((edit|save|add|append|upload|drop)/(\&.*))?$" 
+                 "https://transjovian\&.org/$1"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian\&.org
+  SSLEngine on
+  ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(\&.*))?$" 
+                 "http://localhost:8080/$1"
+</VirtualHost>
+.fi
+.RE
+.PP
+.SS Using a Unix-domain Socket
+.PP
+Instead of having Oddmu listen on a TCP port, you can have it listen on a
+Unix-domain socket.\& This requires socket activation.\& An example of configuring
+the service is given in \fIoddmu.\&service(5)\fR.\&
+.PP
+On the Apache side, you can proxy to the socket directly.\& This sends all
+requests to the socket:
+.PP
+.nf
+.RS 4
+ProxyPass "/" "unix:/run/oddmu/oddmu\&.sock|http://localhost/"
+.fi
+.RE
+.PP
+Now, all traffic between the web server and the wiki goes over the socket at
+"/run/oddmu/oddmu.\&sock".\&
+.PP
+To test it on the command-line, use a tool like \fIcurl(1)\fR.\& Make sure to provide
+the correct servername!\&
+.PP
+.nf
+.RS 4
+curl http://transjovian\&.org/view/index
+.fi
+.RE
+.PP
+You probably want to serve some static files as well (see \fBServe static files\fR).\&
+In that case, you need to use the ProxyPassMatch directive.\&
+.PP
+.nf
+.RS 4
+ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(\&.*))?$" 
+               "unix:/run/oddmu/oddmu\&.sock|http://localhost/$1"
+.fi
+.RE
+.PP
+There'\&s a curious problem with this expression, however.\& If you use \fIcurl(1)\fR to
+get the root path, Apache hangs:
+.PP
+.nf
+.RS 4
+curl http://transjovian\&.org/
+.fi
+.RE
+.PP
+A workaround is to add the redirect manually and drop the question-mark:
+.PP
+.nf
+.RS 4
+RedirectMatch "^/$" "/view/index"
+ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(\&.*))$" 
+               "unix:/run/oddmu/oddmu\&.sock|http://localhost/$1"
+.fi
+.RE
+.PP
+If you know why this is happening, let me know.\&
+.PP
+.SS Access
+.PP
+Access control is not part of Oddmu.\& By default, the wiki is editable by all.\&
+This is most likely not what you want unless you'\&re running it stand-alone,
+unconnected to the Internet – a personal memex on your laptop, for example.\&
+.PP
+The following instructions create user accounts with passwords just for Oddmu.\&
+These users are not real users on the web server and don'\&t have access to a
+shell, mail, or any other service.\&
+.PP
+Create a new password file called ".\&htpasswd" and add the user "alex".\& The "-c"
+flag creates the file.\&
+.PP
+.nf
+.RS 4
+cd /home/oddmu
+htpasswd -c \&.htpasswd alex
+.fi
+.RE
+.PP
+To add more users, don'\&t use the "-c" option or you will overwrite the existing
+file.\& To add another user, use no option at all.\&
+.PP
+.nf
+.RS 4
+htpasswd \&.htpasswd berta
+.fi
+.RE
+.PP
+To remove a user, use the "-D" option.\&
+.PP
+.nf
+.RS 4
+htpasswd -D \&.htpasswd berta
+.fi
+.RE
+.PP
+Modify your site configuration and protect the "/edit/", "/save/", "/add/",
+"/append/", "/upload/" and "/drop/" URLs with a password by adding the following
+to your "<VirtualHost *:443>" section:
+.PP
+.nf
+.RS 4
+<LocationMatch "^/(edit|save|add|append|upload|drop)/">
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/\&.htpasswd
+  Require valid-user
+</LocationMatch>
+.fi
+.RE
+.PP
+The way Oddmu handles subdirectories is that all files and directories are
+visible, except for "hidden" files and directories (whose name starts with a
+period).\& Specifically, do not rely on Apache to hide locations in subdirectories
+from public view.\& Search reveals the existence of these pages and produces an
+extract, even if users cannot follow the links.\& Archive links pack all the
+subdirectories, including locations you may have hidden from view using Apache.\&
+.PP
+If you to treat subdirectories as separate sites, you need to set the
+environment variable ODDMU_FILTER to a regular expression matching the those
+directories.\& If search starts in a directory that doesn'\&t match the regular
+expression, all directories matching the regular expression are excluded.\& See
+\fIoddmu-filter\fR(7).\&
+.PP
+In the following example, ODDMU_FILTER is set to "^secret/".\&
+.PP
+"http://transjovian.\&org/search/index?\&q=something" does not search the "secret/"
+directory and its subdirectories are excluded.\&
+.PP
+"http://transjovian.\&org/search/secret/index?\&q=something" searches just the
+"secret" directory and its subdirectories.\&
+.PP
+You need to configure the web server to prevent access to the "secret/"
+directory:
+.PP
+.nf
+.RS 4
+<LocationMatch "^/(edit|save|add|append|upload|drop|(view|preview|search|archive)/secret)/">
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/\&.htpasswd
+  Require valid-user
+</LocationMatch>
+.fi
+.RE
+.PP
+.SS Serve static files
+.PP
+If you want to serve static files as well, add a document root to your webserver
+configuration.\& In this case, the document root is the directory where all the
+data files are.\& Apache does not serve files such as ".\&htpasswd".\&
+.PP
+.nf
+.RS 4
+DocumentRoot /home/oddmu
+<Directory /home/oddmu>
+  Require all granted
+</Directory>
+.fi
+.RE
+.PP
+Make sure that none of the subdirectories look like the wiki paths "/view/",
+"/diff/", "/edit/", "/save/", "/add/", "/append/", "/upload/", "/drop/",
+"/search/" or "/archive/".\& For example, create a file called "robots.\&txt"
+containing the following, telling all robots that they'\&re not welcome.\&
+.PP
+.nf
+.RS 4
+User-agent: *
+Disallow: /
+.fi
+.RE
+.PP
+Your site now serves "/robots.\&txt" without interfering with the wiki, and
+without needing a wiki page.\&
+.PP
+Another option would be to create a CSS file and use it with a <link> element in
+all the templates instead of relying on the <style> element.\&
+.PP
+The "view.\&html" template would start as follows:
+.PP
+.nf
+.RS 4
+<!DOCTYPE html>
+<html lang="{{\&.Language}}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="format-detection" content="telephone=no">
+    <meta name="viewport" content="width=device-width">
+    <title>{{\&.Title}}</title>
+    <link href="/css/oddmu-2023\&.css" rel="stylesheet" />
+    <link rel="alternate" type="application/rss+xml" title="Alex Schroeder: {{\&.Title}}" href="/view/{{\&.Name}}\&.rss" />
+  </head>
+…
+.fi
+.RE
+.PP
+In this case, "/css/oddmu-2023.\&css" would be the name of your stylesheet.\& If
+your document root is "/home/oddmu", then the filename of your stylesheet would
+have to be "/home/oddmu/css/oddmu-2023.\&css" for this to work.\&
+.PP
+.SS Different logins for different access rights
+.PP
+What if you have a site with various subdirectories and each subdirectory is for
+a different group of friends?\& You can set this up using your webserver.\& One way
+to do this is to require specific usernames (which must have a password in the
+password file mentioned above.\&
+.PP
+This requires a valid login by the user "alex" or "berta":
+.PP
+.nf
+.RS 4
+<LocationMatch "^/(edit|save|add|append|upload|drop)/intetebi/">
+  Require user alex berta
+</LocationMatch>
+.fi
+.RE
+.PP
+.SS Private wikis
+.PP
+Based on the above, you can prevent people from \fIreading\fR the wiki.\& The location
+must cover all the URLs in order to protect everything.\&
+.PP
+.nf
+.RS 4
+<Location />
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/\&.htpasswd
+  Require valid-user
+</Location>
+.fi
+.RE
+.PP
+.SS Virtual hosting
+.PP
+Virtual hosting in this context means that the program serves two different
+sites for two different domains from the same machine.\& Oddmu doesn'\&t support
+that, but your webserver does.\& Therefore, start an Oddmu instance for every
+domain name, each listening on a different port.\& Then set up your web server
+such that ever domain acts as a reverse proxy to a different Oddmu instance.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-filter\fR(7), \fIoddmu-nginx\fR(5)
+.PP
+"Apache Core Features".\&
+https://httpd.\&apache.\&org/docs/current/mod/core.\&html
+.PP
+"Apache: Authentication and Authorization".\&
+https://httpd.\&apache.\&org/docs/current/howto/auth.\&html
+.PP
+"Apache Module mod_proxy".\&
+https://httpd.\&apache.\&org/docs/current/mod/mod_proxy.\&html
+.PP
+"Robot exclusion standard" on Wikipedia.\&
+https://en.\&wikipedia.\&org/wiki/Robot_exclusion_standard
+.PP
+"<style>: The Style Information element"
+https://developer.\&mozilla.\&org/en-US/docs/Web/HTML/Element/style
+.PP
+"<link>: The External Resource Link element"
+https://developer.\&mozilla.\&org/en-US/docs/Web/HTML/Element/link
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-apache.5.txt

@@ -0,0 +1,355 @@
+ODDMU-APACHE(5)
+
+# NAME
+
+oddmu-apache - how to setup Apache as a reverse proxy for Oddmu
+
+# DESCRIPTION
+
+The oddmu program serves the current working directory as a wiki on port 8080.
+This is an unpriviledged port so an ordinary user account can do this.
+Alternatively, you can reverse proxy HTTP over a Unix-domain socket,
+as shown later.
+
+The best way to protect the wiki against vandalism and spam is to use a regular
+web server as reverse proxy. This page explains how to setup Apache on Debian to
+do this.
+
+# CONFIGURATION
+
+HTTPS is not part of Oddmu. You probably want to configure this in your
+webserver. I guess you could use stunnel, too. If you're using Apache, you can
+use "mod_md" to manage your domain.
+
+The examples below use the domain "transjovian.org" and the Apache installation
+is the one that comes with Debian.
+
+The site itself is configured in a file called
+"/etc/apache2/sites-available/transjovian.conf" and a link points there from
+"/etc/apache2/sites-enabled". Create this link using _a2ensite_(1).
+
+```
+MDomain transjovian.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder.ch
+
+<VirtualHost *:80>
+  ServerName transjovian.org
+  Redirect "/" "https://transjovian.org/"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian.org
+  SSLEngine on
+  ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(.*))?$" \
+                 "http://localhost:8080/$1"
+</VirtualHost>
+```
+
+First, it manages the domain, getting the necessary certificates. It redirects
+regular HTTP traffic from port 80 to port 443. It turns on the SSL engine for
+port 443. It proxies the requests for Oddmu to port 8080. Importantly, it
+doesn't send _all_ the requests to Oddmu. This allows us to still host static
+files using the web server (see *Serve static files*).
+
+This is what happens:
+
+- The user tells the browser to visit "transjovian.org"
+- The browser sends a request for "http://transjovian.org" (on port 80)
+- Apache redirects this to "https://transjovian.org/" by default (now on port 443)
+- This is proxied to "http://transjovian.org:8080/" (now on port 8080)
+
+Restart the server, gracefully:
+
+```
+apachectl graceful
+```
+
+In a situation where Apache acts as a reverse proxy, you can prevent some
+actions from being proxied. If you don't want to allow strangers to make
+changes, search or archive the site, use a limited setup like the following:
+
+```
+MDomain transjovian.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder.ch
+
+<VirtualHost *:80>
+  ServerName transjovian.org
+  Redirect "/" "https://transjovian.org/"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian.org
+  SSLEngine on
+  ProxyPassMatch "^/(view/.*)?$" "http://localhost:8080/$1"
+</VirtualHost>
+```
+
+You'll need to edit the source pages some other way. Edit them locally and
+upload them using rsync; edit them remotely using an editor that can do this;
+use SSHFS to mount the remote directory locally for editing; use _stunnel_(8) to
+access the remote wiki on the local port 8080 for editing. There are probably a
+lot more such options available. All of them have the drawback that they're
+probably not easy to use when on a mobile phone.
+
+## Allow HTTP for viewing
+
+When looking at pages, you might want to allow HTTP since no password is
+required. Therefore, proxy the read-only requests from the virtual host on port
+80 to the wiki instead of redirecting them to port 443.
+
+```
+MDomain transjovian.org
+MDCertificateAgreement accepted
+ServerAdmin alex@alexschroeder.ch
+
+<VirtualHost *:80>
+  ServerName transjovian.org
+  ProxyPassMatch "^/((view|diff|search|archive)/(.*))?$" \
+                 "http://localhost:8080/$1"
+  RedirectMatch  "^/((edit|save|add|append|upload|drop)/(.*))?$" \
+                 "https://transjovian.org/$1"
+</VirtualHost>
+<VirtualHost *:443>
+  ServerName transjovian.org
+  SSLEngine on
+  ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(.*))?$" \
+                 "http://localhost:8080/$1"
+</VirtualHost>
+```
+
+## Using a Unix-domain Socket
+
+Instead of having Oddmu listen on a TCP port, you can have it listen on a
+Unix-domain socket. This requires socket activation. An example of configuring
+the service is given in _oddmu.service(5)_.
+
+On the Apache side, you can proxy to the socket directly. This sends all
+requests to the socket:
+
+```
+ProxyPass "/" "unix:/run/oddmu/oddmu.sock|http://localhost/"
+```
+
+Now, all traffic between the web server and the wiki goes over the socket at
+"/run/oddmu/oddmu.sock".
+
+To test it on the command-line, use a tool like _curl(1)_. Make sure to provide
+the correct servername!
+
+```
+curl http://transjovian.org/view/index
+```
+
+You probably want to serve some static files as well (see *Serve static files*).
+In that case, you need to use the ProxyPassMatch directive.
+
+```
+ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(.*))?$" \
+               "unix:/run/oddmu/oddmu.sock|http://localhost/$1"
+```
+
+There's a curious problem with this expression, however. If you use _curl(1)_ to
+get the root path, Apache hangs:
+
+```
+curl http://transjovian.org/
+```
+
+A workaround is to add the redirect manually and drop the question-mark:
+
+```
+RedirectMatch "^/$" "/view/index"
+ProxyPassMatch "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive)/(.*))$" \
+               "unix:/run/oddmu/oddmu.sock|http://localhost/$1"
+```
+
+If you know why this is happening, let me know.
+
+## Access
+
+Access control is not part of Oddmu. By default, the wiki is editable by all.
+This is most likely not what you want unless you're running it stand-alone,
+unconnected to the Internet – a personal memex on your laptop, for example.
+
+The following instructions create user accounts with passwords just for Oddmu.
+These users are not real users on the web server and don't have access to a
+shell, mail, or any other service.
+
+Create a new password file called ".htpasswd" and add the user "alex". The "-c"
+flag creates the file.
+
+```
+cd /home/oddmu
+htpasswd -c .htpasswd alex
+```
+
+To add more users, don't use the "-c" option or you will overwrite the existing
+file. To add another user, use no option at all.
+
+```
+htpasswd .htpasswd berta
+```
+
+To remove a user, use the "-D" option.
+
+```
+htpasswd -D .htpasswd berta
+```
+
+Modify your site configuration and protect the "/edit/", "/save/", "/add/",
+"/append/", "/upload/" and "/drop/" URLs with a password by adding the following
+to your "<VirtualHost \*:443>" section:
+
+```
+<LocationMatch "^/(edit|save|add|append|upload|drop)/">
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/.htpasswd
+  Require valid-user
+</LocationMatch>
+```
+
+The way Oddmu handles subdirectories is that all files and directories are
+visible, except for "hidden" files and directories (whose name starts with a
+period). Specifically, do not rely on Apache to hide locations in subdirectories
+from public view. Search reveals the existence of these pages and produces an
+extract, even if users cannot follow the links. Archive links pack all the
+subdirectories, including locations you may have hidden from view using Apache.
+
+If you to treat subdirectories as separate sites, you need to set the
+environment variable ODDMU_FILTER to a regular expression matching the those
+directories. If search starts in a directory that doesn't match the regular
+expression, all directories matching the regular expression are excluded. See
+_oddmu-filter_(7).
+
+In the following example, ODDMU_FILTER is set to "^secret/".
+
+"http://transjovian.org/search/index?q=something" does not search the "secret/"
+directory and its subdirectories are excluded.
+
+"http://transjovian.org/search/secret/index?q=something" searches just the
+"secret" directory and its subdirectories.
+
+You need to configure the web server to prevent access to the "secret/"
+directory:
+
+```
+<LocationMatch "^/(edit|save|add|append|upload|drop|(view|preview|search|archive)/secret)/">
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/.htpasswd
+  Require valid-user
+</LocationMatch>
+```
+
+## Serve static files
+
+If you want to serve static files as well, add a document root to your webserver
+configuration. In this case, the document root is the directory where all the
+data files are. Apache does not serve files such as ".htpasswd".
+
+```
+DocumentRoot /home/oddmu
+<Directory /home/oddmu>
+  Require all granted
+</Directory>
+```
+
+Make sure that none of the subdirectories look like the wiki paths "/view/",
+"/diff/", "/edit/", "/save/", "/add/", "/append/", "/upload/", "/drop/",
+"/search/" or "/archive/". For example, create a file called "robots.txt"
+containing the following, telling all robots that they're not welcome.
+
+```
+User-agent: *
+Disallow: /
+```
+
+Your site now serves "/robots.txt" without interfering with the wiki, and
+without needing a wiki page.
+
+Another option would be to create a CSS file and use it with a \<link\> element in
+all the templates instead of relying on the \<style\> element.
+
+The "view.html" template would start as follows:
+
+```
+<!DOCTYPE html>
+<html lang="{{.Language}}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="format-detection" content="telephone=no">
+    <meta name="viewport" content="width=device-width">
+    <title>{{.Title}}</title>
+    <link href="/css/oddmu-2023.css" rel="stylesheet" />
+    <link rel="alternate" type="application/rss+xml" title="Alex Schroeder: {{.Title}}" href="/view/{{.Name}}.rss" />
+  </head>
+…
+```
+
+In this case, "/css/oddmu-2023.css" would be the name of your stylesheet. If
+your document root is "/home/oddmu", then the filename of your stylesheet would
+have to be "/home/oddmu/css/oddmu-2023.css" for this to work.
+
+## Different logins for different access rights
+
+What if you have a site with various subdirectories and each subdirectory is for
+a different group of friends? You can set this up using your webserver. One way
+to do this is to require specific usernames (which must have a password in the
+password file mentioned above.
+
+This requires a valid login by the user "alex" or "berta":
+
+```
+<LocationMatch "^/(edit|save|add|append|upload|drop)/intetebi/">
+  Require user alex berta
+</LocationMatch>
+```
+
+## Private wikis
+
+Based on the above, you can prevent people from _reading_ the wiki. The location
+must cover all the URLs in order to protect everything.
+
+```
+<Location />
+  AuthType Basic
+  AuthName "Password Required"
+  AuthUserFile /home/oddmu/.htpasswd
+  Require valid-user
+</Location>
+```
+
+## Virtual hosting
+
+Virtual hosting in this context means that the program serves two different
+sites for two different domains from the same machine. Oddmu doesn't support
+that, but your webserver does. Therefore, start an Oddmu instance for every
+domain name, each listening on a different port. Then set up your web server
+such that ever domain acts as a reverse proxy to a different Oddmu instance.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-filter_(7), _oddmu-nginx_(5)
+
+"Apache Core Features".
+https://httpd.apache.org/docs/current/mod/core.html
+
+"Apache: Authentication and Authorization".
+https://httpd.apache.org/docs/current/howto/auth.html
+
+"Apache Module mod_proxy".
+https://httpd.apache.org/docs/current/mod/mod_proxy.html
+
+"Robot exclusion standard" on Wikipedia.
+https://en.wikipedia.org/wiki/Robot_exclusion_standard
+
+"\<style\>: The Style Information element"
+https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style
+
+"\<link\>: The External Resource Link element"
+https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-export.1

@@ -0,0 +1,79 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-EXPORT" "1" "2024-08-29"
+.PP
+.SH NAME
+.PP
+oddmu-export - export all pages into one file
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu export\fR [\fB-template\fR \fIfilename\fR]
+.PP
+.SH DESCRIPTION
+.PP
+The "export" subcommand prints a RSS file containing all the pages to stdout.\&
+You probably want to redirect this into a file so that you can upload and import
+it somewhere.\&
+.PP
+Note that this only handles pages (Markdown files).\& All other files (images,
+PDFs, whatever else you uploaded) are not part of the feed and has to be
+uploaded to the new platform in some other way.\&
+.PP
+The \fB-template\fR option specifies the template to use.\& If the template filename
+ends in \fI.\&xml\fR, \fI.\&html\fR or \fI.\&rss\fR, it is assumed to contain XML and the optional
+XML preamble is printed and appropriate escaping rules are used.\&
+.PP
+.SH FILES
+.PP
+By default, the export uses the \fB\fRfeed.\&html\fB\fR template in the current directory.\&
+.PP
+.SH EXAMPLES
+.PP
+Export all the pages into a big XML file:
+.PP
+.nf
+.RS 4
+env ODDMU_LANGUAGES=de,en oddmu export > /tmp/export\&.xml
+.fi
+.RE
+.PP
+Alternatively, consider a template file like the following, to generate a JSON
+feed.\& The rule to disallow a comma at the end of arrays means that we need to
+add an empty tag and an empty item, unfortunately:
+.PP
+.nf
+.RS 4
+{
+  "version": "https://jsonfeed\&.org/version/1\&.1",
+  "title": "{{\&.Title}}",
+  "home_page_url": "https://alexschroeder\&.ch",
+  "others": [],
+  "items": [{{range \&.Items}}
+    {
+      "id": "{{\&.Name}}",
+      "url": "https://alexschroeder\&.ch/view/{{\&.Name}}",
+      "title": "{{\&.Title}}",
+      "content_html": "{{\&.Html}}",
+      "date_modified": "{{\&.Date}}",
+      "tags": [{{range \&.Hashtags}}"{{\&.}}",{{end}}""],
+      "language": "{{\&.Language}}"
+    },{{end}}
+    {}
+  ]
+}
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-templates\fR(5), \fIoddmu-static\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-export.1.txt

@@ -0,0 +1,68 @@
+ODDMU-EXPORT(1)
+
+# NAME
+
+oddmu-export - export all pages into one file
+
+# SYNOPSIS
+
+*oddmu export* [*-template* _filename_]
+
+# DESCRIPTION
+
+The "export" subcommand prints a RSS file containing all the pages to stdout.
+You probably want to redirect this into a file so that you can upload and import
+it somewhere.
+
+Note that this only handles pages (Markdown files). All other files (images,
+PDFs, whatever else you uploaded) are not part of the feed and has to be
+uploaded to the new platform in some other way.
+
+The *-template* option specifies the template to use. If the template filename
+ends in _.xml_, _.html_ or _.rss_, it is assumed to contain XML and the optional
+XML preamble is printed and appropriate escaping rules are used.
+
+# FILES
+
+By default, the export uses the **feed.html** template in the current directory.
+
+# EXAMPLES
+
+Export all the pages into a big XML file:
+
+```
+env ODDMU_LANGUAGES=de,en oddmu export > /tmp/export.xml
+```
+
+Alternatively, consider a template file like the following, to generate a JSON
+feed. The rule to disallow a comma at the end of arrays means that we need to
+add an empty tag and an empty item, unfortunately:
+
+```
+{
+  "version": "https://jsonfeed.org/version/1.1",
+  "title": "{{.Title}}",
+  "home_page_url": "https://alexschroeder.ch",
+  "others": [],
+  "items": [{{range .Items}}
+    {
+      "id": "{{.Name}}",
+      "url": "https://alexschroeder.ch/view/{{.Name}}",
+      "title": "{{.Title}}",
+      "content_html": "{{.Html}}",
+      "date_modified": "{{.Date}}",
+      "tags": [{{range .Hashtags}}"{{.}}",{{end}}""],
+      "language": "{{.Language}}"
+    },{{end}}
+    {}
+  ]
+}
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-templates_(5), _oddmu-static_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-filter.7

@@ -0,0 +1,58 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-FILTER" "7" "2024-09-30"
+.PP
+.SH NAME
+.PP
+oddmu-filter - keeping subdirectories separate
+.PP
+.SH DESCRIPTION
+.PP
+There are actions such as searching and archiving that act on multiple pages,
+not just a single page.\& These actions walk the directory tree, including all
+subdirectories.\& In some cases, this is not desirable.\&
+.PP
+Sometimes, subdirectories are separate sites, like the sites of other projects
+or different people.\& Depending on how you think about it, you might not want to
+include those "sites" in searches or archives of the whole site.\&
+.PP
+Since directory tree actions always start in the directory the visitor is
+currently looking at, directory tree actions starting in a "separate site"
+automatically act as expected.\& The action is limited to that subdirectory tree.\&
+.PP
+When visitors look at a page in the "main site", however, directory tree actions
+must skip any sub directories that are part of a "separate site".\&
+.PP
+The way to identify separate sites is via the environment variable ODDMU_FILTER.\&
+It'\&s value is a regular expression matching separate sites.\&
+.PP
+.SH EXAMPLES
+.PP
+"ODDMU_FILTER=^project/" means that a directory tree action outside the
+"project/" directory does not include pages in the "project/" directory.\&
+.PP
+In other words, http://localhost:8080/search/?\&q=oddmu skips any pages in
+"project/".\&
+.PP
+At the same time, http://localhost:8080/search/project/?\&q=oddmu works like it
+always does: search is limited to "project/" and its subdirectories.\&
+.PP
+.SH SECURITY
+.PP
+If the subdirectory is a private site, then you need to use ODDMU_FILTER to
+exclude it from directory tree actions in the main site, and you need to
+configure your web server such that it doesn'\&t allow visitors access to the
+directory tree without authentication.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-search\fR(7), \fIoddmu-apache\fR(5), \fIoddmu-nginx\fR(5)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-filter.7.txt

@@ -0,0 +1,51 @@
+ODDMU-FILTER(7)
+
+# NAME
+
+oddmu-filter - keeping subdirectories separate
+
+# DESCRIPTION
+
+There are actions such as searching and archiving that act on multiple pages,
+not just a single page. These actions walk the directory tree, including all
+subdirectories. In some cases, this is not desirable.
+
+Sometimes, subdirectories are separate sites, like the sites of other projects
+or different people. Depending on how you think about it, you might not want to
+include those "sites" in searches or archives of the whole site.
+
+Since directory tree actions always start in the directory the visitor is
+currently looking at, directory tree actions starting in a "separate site"
+automatically act as expected. The action is limited to that subdirectory tree.
+
+When visitors look at a page in the "main site", however, directory tree actions
+must skip any sub directories that are part of a "separate site".
+
+The way to identify separate sites is via the environment variable ODDMU_FILTER.
+It's value is a regular expression matching separate sites.
+
+# EXAMPLES
+
+"ODDMU_FILTER=^project/" means that a directory tree action outside the
+"project/" directory does not include pages in the "project/" directory.
+
+In other words, http://localhost:8080/search/?q=oddmu skips any pages in
+"project/".
+
+At the same time, http://localhost:8080/search/project/?q=oddmu works like it
+always does: search is limited to "project/" and its subdirectories.
+
+# SECURITY
+
+If the subdirectory is a private site, then you need to use ODDMU_FILTER to
+exclude it from directory tree actions in the main site, and you need to
+configure your web server such that it doesn't allow visitors access to the
+directory tree without authentication.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-search_(7), _oddmu-apache_(5), _oddmu-nginx_(5)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-hashtags.1

@@ -0,0 +1,66 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-HASHTAGS" "1" "2025-08-09"
+.PP
+.SH NAME
+.PP
+oddmu-hashtags - work with hashtags
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu hashtags\fR
+.PP
+\fBoddmu hashtags -update\fR [\fB-dry-run\fR]
+.PP
+.SH DESCRIPTION
+.PP
+By default, the "hashtags" subcommand counts all the hashtags used and lists
+them, separated by a TAB character.\&
+.PP
+With the \fB-update\fR flag, the hashtag pages are update with links to all the blog
+pages having the corresponding tag.\& This only necessary when migrating a
+collection of Markdown files.\& Ordinarily, Oddmu maintains the hashtag pages
+automatically.\& When writing pages offline, use \fIoddmu-notify\fR(1) to update the
+hashtag pages.\&
+.PP
+Use the \fB-dry-run\fR flag to see what would change with the \fB-update\fR flag without
+actually changing any files.\&
+.PP
+.SH EXAMPLES
+.PP
+List the top 10 hashtags.\& This requires 11 lines because of the header line.\&
+.PP
+.nf
+.RS 4
+oddmu hashtags | head -n 11
+.fi
+.RE
+.PP
+See what kind of changes Oddmu would suggest:
+.PP
+.nf
+.RS 4
+oddmu hashtags -update -dry-run
+.fi
+.RE
+.PP
+And then do it:
+.PP
+.nf
+.RS 4
+oddmu hashtags -update
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-hashtags.1.txt

@@ -0,0 +1,53 @@
+ODDMU-HASHTAGS(1)
+
+# NAME
+
+oddmu-hashtags - work with hashtags
+
+# SYNOPSIS
+
+*oddmu hashtags*
+
+*oddmu hashtags -update* [*-dry-run*]
+
+# DESCRIPTION
+
+By default, the "hashtags" subcommand counts all the hashtags used and lists
+them, separated by a TAB character.
+
+With the *-update* flag, the hashtag pages are update with links to all the blog
+pages having the corresponding tag. This only necessary when migrating a
+collection of Markdown files. Ordinarily, Oddmu maintains the hashtag pages
+automatically. When writing pages offline, use _oddmu-notify_(1) to update the
+hashtag pages.
+
+Use the *-dry-run* flag to see what would change with the *-update* flag without
+actually changing any files.
+
+# EXAMPLES
+
+List the top 10 hashtags. This requires 11 lines because of the header line.
+
+```
+oddmu hashtags | head -n 11
+```
+
+See what kind of changes Oddmu would suggest:
+
+```
+oddmu hashtags -update -dry-run
+```
+
+And then do it:
+
+```
+oddmu hashtags -update
+```
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-html.1

@@ -0,0 +1,63 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-HTML" "1" "2025-04-05"
+.PP
+.SH NAME
+.PP
+oddmu-html - render Oddmu page HTML
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu html\fR [\fB\fR-template\fB\fR \fItemplate-name\fR] \fIpage-name\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "html" subcommand opens the given Markdown file and prints the resulting
+HTML to STDOUT without invoking the "view.\&html" template.\& Use "-" as the page
+name if you want to read Markdown from \fBstdin\fR.\&
+.PP
+.SH OPTIONS
+.PP
+\fB\fR-template\fB\fR \fItemplate-name\fR
+.RS 4
+Use the given template to render the page.\& Without this, the HTML lacks
+html and body tags.\& The only two options that make sense are "view.\&html"
+and "static.\&html".\&
+.PP
+.RE
+.SH EXAMPLES
+.PP
+Generate "README.\&html" from "README.\&md":
+.PP
+.nf
+.RS 4
+oddmu html README\&.md > README\&.html
+.fi
+.RE
+.PP
+Alternatively:
+.PP
+.nf
+.RS 4
+oddmu html - < README\&.md > README\&.html
+.fi
+.RE
+.PP
+.PP
+.SH ENVIRONMENT
+.PP
+The ODDMU_WEBFINGER environment variable has no effect in this situation.\&
+Fediverse accounts are not linked to their profile pages.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-html.1.txt

@@ -0,0 +1,50 @@
+ODDMU-HTML(1)
+
+# NAME
+
+oddmu-html - render Oddmu page HTML
+
+# SYNOPSIS
+
+*oddmu html* [**-template** _template-name_] _page-name_
+
+# DESCRIPTION
+
+The "html" subcommand opens the given Markdown file and prints the resulting
+HTML to STDOUT without invoking the "view.html" template. Use "-" as the page
+name if you want to read Markdown from *stdin*.
+
+# OPTIONS
+
+**-template** _template-name_
+	Use the given template to render the page. Without this, the HTML lacks
+	html and body tags. The only two options that make sense are "view.html"
+	and "static.html".
+
+# EXAMPLES
+
+Generate "README.html" from "README.md":
+
+```
+oddmu html README.md > README.html
+```
+
+Alternatively:
+
+```
+oddmu html - < README.md > README.html
+```
+
+
+# ENVIRONMENT
+
+The ODDMU_WEBFINGER environment variable has no effect in this situation.
+Fediverse accounts are not linked to their profile pages.
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-links.1

@@ -0,0 +1,29 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-LINKS" "1" "2025-04-05"
+.PP
+.SH NAME
+.PP
+oddmu-links - list outgoing links for pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu links\fR  \fIpage names.\&.\&.\&\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "links" subcommand lists outgoing links for one or more Markdown files.\& Use
+"-" as the page name if you want to read Markdown from \fBstdin\fR.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-missing\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-links.1.txt

@@ -0,0 +1,22 @@
+ODDMU-LINKS(1)
+
+# NAME
+
+oddmu-links - list outgoing links for pages
+
+# SYNOPSIS
+
+*oddmu links*  _page names..._
+
+# DESCRIPTION
+
+The "links" subcommand lists outgoing links for one or more Markdown files. Use
+"-" as the page name if you want to read Markdown from *stdin*.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-missing_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-list.1

@@ -0,0 +1,56 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-LIST" "1" "2024-08-29"
+.PP
+.SH NAME
+.PP
+oddmu-list - list page names and titles
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu list\fR [-dir \fIstring\fR]
+.PP
+.SH DESCRIPTION
+.PP
+The "list" subcommand lists page names and their titles, separated by a TAB
+character.\& This saves you from opening and parsing all the files yourself if you
+need the page titles.\&
+.PP
+If a directory is provided, only files from the tree starting at that
+subdirectory are listed, and the directory is stripped from the page name.\&
+.PP
+.SH OPTIONS
+.PP
+\fB-dir\fR \fIstring\fR
+.RS 4
+Limit the list to a particular directory.\&
+.PP
+.RE
+.SH EXAMPLES
+.PP
+Create list of links to pages in the "dad" directory, filter it for date pages
+(starting with "2"), format it as a list of links and sort in reverse order.\&
+This is a list of links you could append to "dad/index.\&md" if it doesn'\&t already
+have a list of links.\&
+.PP
+.nf
+.RS 4
+oddmu list -dir dad 
+| grep \&'^2\&' 
+| awk -F "t" -e \&'{ print "* [" $2 "](" $1 ")" }\&' 
+| sort -r
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-search\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-list.1.txt

@@ -0,0 +1,45 @@
+ODDMU-LIST(1)
+
+# NAME
+
+oddmu-list - list page names and titles
+
+# SYNOPSIS
+
+*oddmu list* [-dir _string_]
+
+# DESCRIPTION
+
+The "list" subcommand lists page names and their titles, separated by a TAB
+character. This saves you from opening and parsing all the files yourself if you
+need the page titles.
+
+If a directory is provided, only files from the tree starting at that
+subdirectory are listed, and the directory is stripped from the page name.
+
+# OPTIONS
+
+*-dir* _string_
+	Limit the list to a particular directory.
+
+# EXAMPLES
+
+Create list of links to pages in the "dad" directory, filter it for date pages
+(starting with "2"), format it as a list of links and sort in reverse order.
+This is a list of links you could append to "dad/index.md" if it doesn't already
+have a list of links.
+
+```
+oddmu list -dir dad \
+| grep '^2' \
+| awk -F "\t" -e '{ print "* [" $2 "](" $1 ")" }' \
+| sort -r
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-search_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-missing.1

@@ -0,0 +1,57 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-MISSING" "1" "2024-08-29"
+.PP
+.SH NAME
+.PP
+oddmu-missing - list missing pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu missing\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "missing" subcommand lists pages and their local links that are missing.\&
+.PP
+Any links that seem like they might point outside the wiki are ignored: links
+that start with a slash "/" and links that start with a known URL schema
+(currently: "http:", "https:", "ftp:", "mailto:", "gopher:", "gemini:",
+"finger:").\&
+.PP
+Notably, links that start with ".\&.\&/" are reported as missing.\&
+.PP
+.SH EXAMPLES
+.PP
+Looking for broken links:
+.PP
+.nf
+.RS 4
+oddmu missing
+.fi
+.RE
+.PP
+Result:
+.PP
+.nf
+.RS 4
+Page	Missing
+README	github\&.com/pemistahl/lingua-go
+.fi
+.RE
+.PP
+This shows how the README file had a link where the URL was missing the scheme
+"https://".\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-replace\fR(1), \fIoddmu-missing\fR(7)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-missing.1.txt

@@ -0,0 +1,46 @@
+ODDMU-MISSING(1)
+
+# NAME
+
+oddmu-missing - list missing pages
+
+# SYNOPSIS
+
+*oddmu missing*
+
+# DESCRIPTION
+
+The "missing" subcommand lists pages and their local links that are missing.
+
+Any links that seem like they might point outside the wiki are ignored: links
+that start with a slash "/" and links that start with a known URL schema
+(currently: "http:", "https:", "ftp:", "mailto:", "gopher:", "gemini:",
+"finger:").
+
+Notably, links that start with "../" are reported as missing.
+
+# EXAMPLES
+
+Looking for broken links:
+
+```
+oddmu missing
+```
+
+Result:
+
+```
+Page	Missing
+README	github.com/pemistahl/lingua-go
+```
+
+This shows how the README file had a link where the URL was missing the scheme
+"https://".
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-replace_(1), _oddmu-missing_(7)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-nginx.5

@@ -0,0 +1,140 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-NGINX" "5" "2025-07-16"
+.PP
+.SH NAME
+.PP
+oddmu-nginx - how to setup nginx as a reverse proxy for Oddmu
+.PP
+.SH DESCRIPTION
+.PP
+The oddmu program serves the current working directory as a wiki on port 8080.\&
+This is an unpriviledged port so an ordinary user account can do this.\&
+.PP
+This page explains how to setup nginx on Debian to act as a reverse proxy for
+Oddmu.\& Once this is done, you can use nginx to provide HTTPS, request users to
+authenticate themselves, and so on.\&
+.PP
+.SH CONFIGURATION
+.PP
+The site is defined in "/etc/nginx/sites-available/default", in the \fIserver\fR
+section.\& Add a new \fIlocation\fR section after the existing \fIlocation\fR section:
+.PP
+.nf
+.RS 4
+location ~ ^/(view|preview|diff|edit|save|add|append|upload|drop|search|archive)/ {
+        proxy_pass http://localhost:8080;
+}
+.fi
+.RE
+.PP
+If you remove an action from the regular expression, those requests no longer
+get passed on to Oddmu.\& They are essentially disabled.\& Somebody on the same
+machine pointing their browser at http://localhost:8080/ directly would still
+have access to all the actions, of course.\&
+.PP
+.SS Access
+.PP
+Access control is not part of Oddmu.\& By default, the wiki is editable by all.\&
+This is most likely not what you want unless you'\&re running it stand-alone,
+unconnected to the Internet – a personal memex on your laptop, for example.\&
+.PP
+To restrict access to some actions, use two different \fIlocation\fR sections:
+.PP
+.nf
+.RS 4
+# public
+location ~ ^/(view|diff|search)/ {
+        proxy_pass http://localhost:8080;
+}
+# password required
+location ~ ^/(edit|save|add|append|upload|drop|archive)/ {
+        auth_basic            "Oddmu author";
+        auth_basic_user_file  /etc/nginx/conf\&.d/htpasswd;
+        proxy_pass            http://localhost:8080;
+}
+.fi
+.RE
+.PP
+The passwords in "/etc/nginx/conf.\&d/htpasswd" are generated using \fIopenssl\fR(1).\&
+Assuming the password is "CPTk&qO[Y@?\&M~L>qKOkd", this is how you encrypt it:
+.PP
+.nf
+.RS 4
+openssl passwd \&'CPTk&qO[Y@?M~L>qKOkd\&'
+.fi
+.RE
+.PP
+The output gets used in "/etc/nginx/conf.\&d/htpasswd".\& Here'\&s the user "alex"
+using this password:
+.PP
+.nf
+.RS 4
+alex:$1$DOwphABk$W4VmR9p8t2\&.htxF6ctXHX\&.
+.fi
+.RE
+.PP
+These instructions create user accounts with passwords just for Oddmu.\&
+These users are not real users on the web server and don'\&t have access to a
+shell, mail, or any other service.\&
+.PP
+.SS Using a Unix-domain Socket
+.PP
+Instead of having Oddmu listen on a TCP port, you can have it listen on a
+Unix-domain socket.\& This requires socket activation.\& An example of configuring
+the service is given in \fIoddmu.\&service\fR(5).\&
+.PP
+On the nginx side, you can proxy to the socket using an \fIupstream\fR section.\& This
+sends all requests to the socket.\& Use the upstream name as the server name for
+\fIproxy_pass\fR.\& Add something like the configuration below to your existing nginx
+server configuration.\& On a Debian system, that'\&d be in
+"/etc/nginx/sites-available/default".\&
+.PP
+.nf
+.RS 4
+location ~ ^/(view|preview|diff|edit|save|add|append|upload|drop|search|archive)/ {
+  proxy_pass http://unix:/run/oddmu/oddmu\&.sock:;
+}
+.fi
+.RE
+.PP
+Reload the configuration:
+.PP
+.nf
+.RS 4
+sudo systemd reload nginx
+.fi
+.RE
+.PP
+Now, all traffic between the web server and the wiki goes over the socket at
+"/run/oddmu/oddmu.\&sock".\&
+.PP
+To test it on the command-line, use a tool like \fIcurl(1)\fR.\&
+.PP
+.nf
+.RS 4
+curl http://localhost/view/index
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-apache\fR(5)
+.PP
+"freenginx"
+http://freenginx.\&org/
+.PP
+"freenginx ngx_http_proxy_module", proxy_pass
+http://freenginx.\&org/en/docs/http/ngx_http_proxy_module.\&html#proxy_pass
+.PP
+"freenginx ngx_http_auth_basic_module"
+http://freenginx.\&org/en/docs/http/ngx_http_auth_basic_module.\&html
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-nginx.5.txt

@@ -0,0 +1,119 @@
+ODDMU-NGINX(5)
+
+# NAME
+
+oddmu-nginx - how to setup nginx as a reverse proxy for Oddmu
+
+# DESCRIPTION
+
+The oddmu program serves the current working directory as a wiki on port 8080.
+This is an unpriviledged port so an ordinary user account can do this.
+
+This page explains how to setup nginx on Debian to act as a reverse proxy for
+Oddmu. Once this is done, you can use nginx to provide HTTPS, request users to
+authenticate themselves, and so on.
+
+# CONFIGURATION
+
+The site is defined in "/etc/nginx/sites-available/default", in the _server_
+section. Add a new _location_ section after the existing _location_ section:
+
+```
+location ~ ^/(view|preview|diff|edit|save|add|append|upload|drop|search|archive)/ {
+        proxy_pass http://localhost:8080;
+}
+```
+
+If you remove an action from the regular expression, those requests no longer
+get passed on to Oddmu. They are essentially disabled. Somebody on the same
+machine pointing their browser at http://localhost:8080/ directly would still
+have access to all the actions, of course.
+
+## Access
+
+Access control is not part of Oddmu. By default, the wiki is editable by all.
+This is most likely not what you want unless you're running it stand-alone,
+unconnected to the Internet – a personal memex on your laptop, for example.
+
+To restrict access to some actions, use two different _location_ sections:
+
+```
+# public
+location ~ ^/(view|diff|search)/ {
+        proxy_pass http://localhost:8080;
+}
+# password required
+location ~ ^/(edit|save|add|append|upload|drop|archive)/ {
+        auth_basic            "Oddmu author";
+        auth_basic_user_file  /etc/nginx/conf.d/htpasswd;
+        proxy_pass            http://localhost:8080;
+}
+```
+
+The passwords in "/etc/nginx/conf.d/htpasswd" are generated using _openssl_(1).
+Assuming the password is "CPTk&qO[Y@?M~L>qKOkd", this is how you encrypt it:
+
+```
+openssl passwd 'CPTk&qO[Y@?M~L>qKOkd'
+```
+
+The output gets used in "/etc/nginx/conf.d/htpasswd". Here's the user "alex"
+using this password:
+
+```
+alex:$1$DOwphABk$W4VmR9p8t2.htxF6ctXHX.
+```
+
+These instructions create user accounts with passwords just for Oddmu.
+These users are not real users on the web server and don't have access to a
+shell, mail, or any other service.
+
+## Using a Unix-domain Socket
+
+Instead of having Oddmu listen on a TCP port, you can have it listen on a
+Unix-domain socket. This requires socket activation. An example of configuring
+the service is given in _oddmu.service_(5).
+
+On the nginx side, you can proxy to the socket using an _upstream_ section. This
+sends all requests to the socket. Use the upstream name as the server name for
+_proxy_pass_. Add something like the configuration below to your existing nginx
+server configuration. On a Debian system, that'd be in
+"/etc/nginx/sites-available/default".
+
+```
+location ~ ^/(view|preview|diff|edit|save|add|append|upload|drop|search|archive)/ {
+  proxy_pass http://unix:/run/oddmu/oddmu.sock:;
+}
+```
+
+Reload the configuration:
+
+```
+sudo systemd reload nginx
+```
+
+Now, all traffic between the web server and the wiki goes over the socket at
+"/run/oddmu/oddmu.sock".
+
+To test it on the command-line, use a tool like _curl(1)_.
+
+```
+curl http://localhost/view/index
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-apache_(5)
+
+"freenginx"
+http://freenginx.org/
+
+"freenginx ngx_http_proxy_module", proxy_pass
+http://freenginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
+
+"freenginx ngx_http_auth_basic_module"
+http://freenginx.org/en/docs/http/ngx_http_auth_basic_module.html
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-notify.1

@@ -0,0 +1,108 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-NOTIFY" "1" "2025-04-05"
+.PP
+.SH NAME
+.PP
+oddmu-notify - add links to changes.\&md, index.\&md, and hashtag pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu notify\fR \fIpage names.\&.\&.\&\fR 
+.PP
+.SH DESCRIPTION
+.PP
+The "notify" subcommand takes all the Markdown files provided and adds links to
+these pages from other pages.\&
+.PP
+A new link is added to the \fBchanges\fR page in the current directory if it doesn'\&t
+exist.\& The current date of the machine Oddmu is running on is used as the
+heading.\& If the requested link already exists on the changes page, it is moved
+up to the current date.\& If that leaves an old date without any links, that date
+heading is removed.\&
+.PP
+A page whose name starts with an ISO date (YYYY-MM-DD, e.\&g.\& "2023-10-28") is
+called a \fBblog\fR page.\&
+.PP
+A link is created from the \fBindex\fR page in the current directory to blog pages
+if and only if the blog pages are from the current year.\& The idea is that the
+front page contains a lot of links to blog posts but eventually the blog post
+links are moved onto archive pages (one per year, for example), or simply
+deleted.\& As when editing older pages, links to those pages should not get added
+to the index as if those older pages were new again.\& A link on the changes page
+is enough.\&
+.PP
+For every \fBhashtag\fR used on the pages named, another link might be created.\& If a
+page named like the hashtag exists, a backlink is added to it.\& A hashtag
+consists of a number sign ('\&#'\&) followed by Unicode letters, numbers or the
+underscore ('\&_'\&).\& Thus, a hashtag ends with punctuation or whitespace.\&
+.PP
+If a link already exists but it'\&s title is no longer correct, it is updated.\&
+.PP
+New links added for blog pages are added at the top of the first unnumbered list
+using the asterisk ('\&*'\&).\& If no such list exists, a new one is started at the
+bottom of the page.\& This allows you to have a different unnumbered list further
+up on the page, as long as it uses the minus for items ('\&-'\&).\&
+.PP
+.SH EXAMPLES
+.PP
+After writing the file "2023-11-05-climate.\&md" containing the hashtag
+"#Climate", add links to it from "index.\&md", "changes.\&md", and "Climate.\&md" (if
+it exists):
+.PP
+.nf
+.RS 4
+oddmu notify 2023-11-05-climate\&.md
+.fi
+.RE
+.PP
+The changes file might look as follows:
+.PP
+.nf
+.RS 4
+# Changes
+
+This page lists all the changes made to the wiki\&.
+
+## 2023-11-05
+
+* [Global warming](2023-11-05-climate)
+.fi
+.RE
+.PP
+The index file might look as follows:
+.PP
+.nf
+.RS 4
+# Blog
+
+This page links to all the blog posts\&.
+
+* [Global warming](2023-11-05-climate)
+.fi
+.RE
+.PP
+The hashtag file might look as follows:
+.PP
+.nf
+.RS 4
+# Climate
+
+This page links to all the blog posts tagged #Climate\&.
+
+* [Global warming](2023-11-05-climate)
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-notify.1.txt

@@ -0,0 +1,93 @@
+ODDMU-NOTIFY(1)
+
+# NAME
+
+oddmu-notify - add links to changes.md, index.md, and hashtag pages
+
+# SYNOPSIS
+
+*oddmu notify* _page names..._ 
+
+# DESCRIPTION
+
+The "notify" subcommand takes all the Markdown files provided and adds links to
+these pages from other pages.
+
+A new link is added to the *changes* page in the current directory if it doesn't
+exist. The current date of the machine Oddmu is running on is used as the
+heading. If the requested link already exists on the changes page, it is moved
+up to the current date. If that leaves an old date without any links, that date
+heading is removed.
+
+A page whose name starts with an ISO date (YYYY-MM-DD, e.g. "2023-10-28") is
+called a *blog* page.
+
+A link is created from the *index* page in the current directory to blog pages
+if and only if the blog pages are from the current year. The idea is that the
+front page contains a lot of links to blog posts but eventually the blog post
+links are moved onto archive pages (one per year, for example), or simply
+deleted. As when editing older pages, links to those pages should not get added
+to the index as if those older pages were new again. A link on the changes page
+is enough.
+
+For every *hashtag* used on the pages named, another link might be created. If a
+page named like the hashtag exists, a backlink is added to it. A hashtag
+consists of a number sign ('#') followed by Unicode letters, numbers or the
+underscore ('\_'). Thus, a hashtag ends with punctuation or whitespace.
+
+If a link already exists but it's title is no longer correct, it is updated.
+
+New links added for blog pages are added at the top of the first unnumbered list
+using the asterisk ('\*'). If no such list exists, a new one is started at the
+bottom of the page. This allows you to have a different unnumbered list further
+up on the page, as long as it uses the minus for items ('-').
+
+# EXAMPLES
+
+After writing the file "2023-11-05-climate.md" containing the hashtag
+"#Climate", add links to it from "index.md", "changes.md", and "Climate.md" (if
+it exists):
+
+```
+oddmu notify 2023-11-05-climate.md
+```
+
+The changes file might look as follows:
+
+```
+# Changes
+
+This page lists all the changes made to the wiki.
+
+## 2023-11-05
+
+* [Global warming](2023-11-05-climate)
+```
+
+The index file might look as follows:
+
+```
+# Blog
+
+This page links to all the blog posts.
+
+* [Global warming](2023-11-05-climate)
+```
+
+The hashtag file might look as follows:
+
+```
+# Climate
+
+This page links to all the blog posts tagged #Climate.
+
+* [Global warming](2023-11-05-climate)
+```
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-releases.7

@@ -0,0 +1,409 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-RELEASES" "7" "2025-08-10"
+.PP
+.SH NAME
+.PP
+oddmu-releases - what'\&s new?\&
+.PP
+.SH DESCRIPTION
+.PP
+This page lists user-visible features and template changes to consider.\&
+.PP
+.SS 1.18 (2025)
+.PP
+The \fIhashtags\fR gained the option of checking and fixing the hashtag pages by
+adding missing links to tagged blog pages.\& See \fIoddmu-hashtags\fR(1) for more.\&
+.PP
+In an effort to remove features that can be handled by the web server, the
+\fIlist\fR, \fIdelete\fR and \fIrename\fR actions were removed again.\& See \fIoddmu-webdav\fR(5)
+for a better solution.\&
+.PP
+You probably need to remove a sentence linking to the list action from the
+upload template ("upload.\&html").\&
+.PP
+.SS 1.17 (2025)
+.PP
+You need to update the upload template ("upload.\&html").\& Many things have
+changed!\& See \fIoddmu-templates\fR(5) for more.\&
+.PP
+You probably want to ensure that the upload link on the view template
+("view.\&html") and others, if you added it, has a \fIfilename\fR and \fIpagename\fR
+parameters.\&
+.PP
+Example:
+.PP
+.nf
+.RS 4
+<a href="/upload/{{\&.Dir}}?filename={{\&.Base}}-1\&.jpg&pagename={{\&.Base}}">Upload</a>
+.fi
+.RE
+.PP
+You need to change {{.\&Name}} to {{.\&Path}} when it is used in URLs, in the list
+template ("list.\&html").\& If you don'\&t do this, file deleting and rename may not
+work on files containing a comma, a semicolon, a questionmark or a hash
+character.\& This fix was necessary because URLs for files containing a
+questionmark or a hash character would end the path at this character and treat
+the rest as a query parameter or fragment, respectively.\&
+.PP
+Updated the example themes.\& Some of my sites got a text area that tries to take
+all the vertical space available.\& This is great for monitors in portrait mode.\&
+.PP
+\fIlist\fR action now skips dot files.\&
+.PP
+.SS 1.16 (2025)
+.PP
+Add support for WebP images for uploading and resizing.\&
+.PP
+You need to change {{.\&Name}} to {{.\&Path}} in HTML templates where pages are
+concerned.\& If you don'\&t do this, your page names (i.\&e.\& filenames for pages) may
+not include a comma, a semicolon, a questionmark or a hash sign.\& This fix was
+necessary because file uploads of filenames with non-ASCII characters ended up
+double-encoded.\&
+.PP
+Note that on the "list.\&html" template, {{.\&Name}} refers to file instead of a
+page and File.\&Path() isn'\&t implemented, yet.\& This is fixed in the next release.\&
+.PP
+Improved the example themes.\& The chat theme got better list styling and better
+upload functionality with automatic "add" button; the plain theme got rocket
+links via JavaScript; the alexschroeder.\&ch theme got a preview button and better
+image support for upload and search; the transjovian.\&org theme got better image
+support for upload.\&
+.PP
+Switch the \fIhtml\fR, \fIlink\fR, \fInotify\fR and \fItoc\fR subcommand to take filenames
+(including the `.\&md` suffix) instead of page names (without the `.\&md` suffix).\&
+.PP
+.SS 1.15 (2025)
+.PP
+Fix the hashtag detection.\& This was necessary to cut down on the many false
+positives.\& They were most obvious with the \fIhashtags\fR subcommand.\& Now the
+Markdown parser is used at startup to index the pages, making startup slower
+(about twice as long with my blog).\& The Markdown parser is also used to parse
+search terms (where it makes little difference).\&
+.PP
+Fix the timestamp for backup files.\& This was necessary because the diff didn'\&t
+work as intended.\&
+.PP
+.SS 1.14 (2024)
+.PP
+Add \fIlist\fR, \fIdelete\fR and \fIrename\fR actions.\&
+.PP
+This requires a change to your web server setup if you are using a it as a
+reverse proxy because you need to pass these new actions along to Oddmu,
+together with appropriate permission checks.\&
+.PP
+See \fIoddmu-apache\fR(5) or \fIoddmu-nginx\fR(5) for example.\&
+.PP
+In addition to that, you might want a link to the \fIlist\fR action from one of the
+existing templates.\& For example, from upload.\&html:
+.PP
+.nf
+.RS 4
+<p>You can rename and delete files <a href="/list/{{\&.Dir}}">from the file list</a>\&.
+.fi
+.RE
+.PP
+The following line was added to the "preview.\&html" and "edit.\&html" template:
+.PP
+.nf
+.RS 4
+<base href="/view/{{\&.Dir}}">
+.fi
+.RE
+.PP
+You might want to do that as well, if you have your own.\& Without this, links in
+the preview cannot be followed as they all point to \fB/preview\fR instead of
+\fB/view\fR and the link to the list of changes cannot be followed from the edit
+page: it leads to editing the list of changes.\&
+.PP
+.SS 1.13 (2024)
+.PP
+Add \fIexport\fR subcommand.\&
+.PP
+.SS 1.12 (2024)
+.PP
+Add \fIhashtags\fR, \fIlinks\fR and \fItoc\fR subcommands.\&
+.PP
+Support searching for multiple words using all sorts of quotation marks.\& That
+means that it is now impossible to search for words that begin with such a
+quotation mark.\&
+.PP
+These are the quotation marks currently supported: '\&foo'\& "foo" ‘foo’ ‚foo‘ ’foo’
+“foo” „foo“ ”foo” «foo» »foo« ‹foo› ›foo‹ ｢foo｣ 「ｆｏｏ」 『ｆｏｏ』 – any such
+quoted text is searched as-is, including whitespace.\&
+.PP
+Add loading="lazy" for images in search.\&html
+.PP
+If you want to take advantage of this, you'\&ll need to adapt your "search.\&html"
+template accordingly.\& Use like this, for example:
+.PP
+.nf
+.RS 4
+{{range \&.Items}}
+<article lang="{{\&.Language}}">
+  <p><a class="result" href="/view/{{\&.Name}}">{{\&.Title}}</a>
+    <span class="score">{{\&.Score}}</span></p>
+  <blockquote>{{\&.Html}}</blockquote>
+  {{range \&.Images}}
+  <p class="image"><a href="/view/{{\&.Name}}"><img loading="lazy" src="/view/{{\&.Name}}"></a><br/>{{\&.Html}}
+  {{end}}
+</article>
+{{end}}
+.fi
+.RE
+.PP
+.SS 1.11 (2024)
+.PP
+The HTML renderer option for smart fractions support was removed.\& Therefore, 1/8
+no longer turns into ⅛ or ¹⁄₈.\& The benefit is that something like "doi:
+10.\&1017/9781009157926.\&007" doesn'\&t turn into "doi: 10.\&1017⁄9781009157926.\&007".\&
+If you need to change this, take a look at the \fIwikiRenderer\fR function.\&
+.PP
+When search terms (excluding hashtags) match the alt text given for an image,
+that image is part of the data available to the search template.\&
+.PP
+If you want to take advantage of this, you'\&ll need to adapt your "search.\&html"
+template accordingly.\& Use like this, for example:
+.PP
+.nf
+.RS 4
+{{range \&.Items}}
+<article lang="{{\&.Language}}">
+  <p><a class="result" href="/view/{{\&.Name}}">{{\&.Title}}</a>
+    <span class="score">{{\&.Score}}</span></p>
+  <blockquote>{{\&.Html}}</blockquote>
+  {{range \&.Images}}
+  <p class="image"><a href="/view/{{\&.Name}}"><img class="last" src="/view/{{\&.Name}}"></a><br/>{{\&.Html}}
+  {{end}}
+</article>
+{{end}}
+.fi
+.RE
+.PP
+.SS 1.10 (2024)
+.PP
+You can now preview edits instead of saving them.\&
+.PP
+.PD 0
+.IP \(bu 4
+a preview button was added to "edit.\&html"
+.IP \(bu 4
+a new "preview.\&html" was added
+.PD
+.PP
+If you want to take advantage of this, you'\&ll need to adapt your templates
+accordingly.\& The "preview.\&html" template is a mix of "view.\&html" and
+"edit.\&html".\&
+.PP
+There is an optional change to make to copies of \fIupload.\&html\fR if you upload
+multiple images at a time.\& Instead of showing just the link to the last upload,
+you can now show the link (and the images or links, if you want to) to all the
+files uploaded.\& Use like this, for example:
+.PP
+.nf
+.RS 4
+Links:<tt>{{range \&.Actual}}<br>![]({{\&.}}){{end}}</tt>
+.fi
+.RE
+.PP
+.SS 1.9 (2024)
+.PP
+There is a change to make to copies of \fIupload.\&html\fR if subdirectories are being
+used.\& The \fILast\fR property no longer contains the directory.\& It has to be added
+to the template as follows:
+.PP
+.nf
+.RS 4
+{{if ne \&.Last ""}}
+<p>Previous upload: <a href="/view/{{\&.Dir}}{{\&.Last}}">{{\&.Last}}</a></p>
+{{if \&.Image}}
+<p><img class="last" src="/view/{{\&.Dir}}{{\&.Last}}"></p>
+{{end}}
+{{end}}
+.fi
+.RE
+.PP
+You can use the \fILast\fR property without a directory to suggest the markup to
+use, for example:
+.PP
+.nf
+.RS 4
+<p>Use the following for <a href="/view/{{\&.Dir}}{{\&.Today}}">{{\&.Today}}</a>:
+<pre>![]({{\&.Last}})</a></pre>
+.fi
+.RE
+.PP
+The upload template can use the \fIToday\fR property.\&
+.PP
+The upload template comes with JavaScript that allows users to paste images or
+drag and drop files.\&
+.PP
+The upload template changed the id for the filename field from `text` to `name`.\&
+.PP
+The source repository now comes with example templates.\&
+.PP
+.SS 1.8 (2024)
+.PP
+No user-visible changes.\& Documentation and code comments got better.\&
+.PP
+.SS 1.7 (2024)
+.PP
+Allow upload of multiple files.\& This requires an update to the \fIupload.\&html\fR
+template: Add the \fImultiple\fR attribute to the file input element and change the
+label from "file" to "files".\&
+.PP
+Fix orientation of uploaded images.\& JPG and HEIC images have EXIF data telling a
+viewer how to orient the image.\& Oddmu now uses this information to rotate the
+image correctly before stripping it.\&
+.PP
+The version command now displays much less information unless given the -full
+argument.\&
+.PP
+.SS 1.6 (2024)
+.PP
+Add \fIarchive\fR action to serve a zip file.\&
+.PP
+.SS 1.5 (2024)
+.PP
+Filtering separate sites in subdirectories via the ODDMU_FILTER environment
+variable in order to exclude them from the \fIsearch\fR action.\&
+.PP
+Add \fIversion\fR subcommand.\&
+.PP
+Add filesystem watchers to automatically reindex changed pages and reload
+changed templates.\&
+.PP
+When rendering a page, use templates in the same directory, if available.\&
+.PP
+Delete uploaded files by uploading a file with zero bytes.\&
+.PP
+.SS 1.4 (2024)
+.PP
+If stdin is a Unix-domain socket, use that to serve the site.\& Otherwise, allow
+specifying a listen address via the ODDMU_ADDRESS environment variable.\&
+.PP
+.SS 1.3 (2024)
+.PP
+Add support for resizing HEIC images (and saving them as JPG files).\&
+.PP
+.SS 1.2 (2023)
+.PP
+Add \fIlist\fR subcommand.\&
+.PP
+.SS 1.1 (2023)
+.PP
+Rewrote most of the README into man pages.\&
+.PP
+Add fediverse account rendering if ODDMU_WEBFINGER is set.\&
+.PP
+Add notifications when saving files: adding links to \fIindex\fR, \fIchanges\fR and
+\fIhashtag\fR pages.\&
+.PP
+Add \fIreplace\fR subcommand.\& Add \fImissing\fR subcommand.\& Add \fInotify\fR command.\& Add
+\fIstatic\fR command.\&
+.PP
+Add \fIdiff\fR action.\&
+.PP
+Add feed generation based on the local links from a page.\&
+.PP
+Add caching support by considering the If-Modified-Since header in requests and
+providing a Last-Modified header in responses.\&
+.PP
+Handle HEAD requests.\&
+.PP
+Remove HTML sanitization.\&
+.PP
+Remove MathJax support from the wiki parser.\& The templates never included the
+necessary MathJax JavaScript anyway so the special handling of $ was just an
+annoyance.\&
+.PP
+Drop trigram index and just search all the files.\& This takes much less RAM and
+doesn'\&t take too much time even with a few thousand pages.\&
+.PP
+Add "blog:true" and "blog:false" predicates to search.\&
+.PP
+Limit search to the current directory tree.\&
+.PP
+Do not overwrite fresh backups: there must be a 1h break before the backup is
+overwritten.\&
+.PP
+.SS 1.0 (2023)
+.PP
+Paginate search results and no longer sort search results by score.\&
+.PP
+.SS 0.9 (2023)
+.PP
+Add image resizing.\&
+.PP
+Add wiki links in double square brackets to the parser.\&
+.PP
+.SS 0.8 (2023)
+.PP
+Rename files to backups before saving.\&
+.PP
+Rename the \fIsaveUpload\fR action to \fIdrop\fR.\&
+.PP
+Add the \fIsearch\fR subcommand.\&
+.PP
+.SS 0.7 (2023)
+.PP
+Add \fIupload\fR and \fIsaveUpload\fR action so that one can upload files.\&
+.PP
+Add \fIhtml\fR subcommand.\&
+.PP
+.SS 0.6 (2003)
+.PP
+Add \fIadd\fR and \fIappend\fR action so that one can add to an existing page.\& This is
+important for me as editing pages on the phone can be cumbersome but leaving
+comments on my own site has always been easy to do.\&
+.PP
+Serve all existing files, not just text files.\&
+.PP
+Save an empty page to delete it.\&
+.PP
+Changed default permissions from 600 to 644 for files and from 700 to 755 for
+directories.\&
+.PP
+Make language detection configurable using an environment variable.\&
+.PP
+.SS 0.5 (2023)
+.PP
+Add hyphenation to templates using Peter M.\& Stahl'\&s Lingua library.\&
+.PP
+.SS 0.4 (2023)
+.PP
+Create subdirectories as necessary.\&
+.PP
+.SS 0.3 (2023)
+.PP
+Add \fIsearch\fR action using Damian Gryski'\&s trigram indexing, with scoring,
+highlighting and snippet extraction.\&
+.PP
+.SS 0.2 (2023)
+.PP
+Switch to Krzysztof Kowalczyk'\&s Go Markdown fork of Blackfriday to render
+Markdown.\& Use Dee'\&s Bluemonday to sanitize HTML.\&
+.PP
+Switch to GNU Affero GPL 3 license.\&
+.PP
+Serve text files (.\&txt).\&
+.PP
+Support serving on any port via the environment variable ODDMU_PORT.\&
+.PP
+.SS 0.1 (2015)
+.PP
+A web server that allows editing files in Wiki Creole Matt Self'\&s Cajun library.\&
+Supported actions are \fIedit\fR, \fIsave\fR, and \fIview\fR.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-releases.7.txt

@@ -0,0 +1,382 @@
+ODDMU-RELEASES(7)
+
+# NAME
+
+oddmu-releases - what's new?
+
+# DESCRIPTION
+
+This page lists user-visible features and template changes to consider.
+
+## 1.18 (2025)
+
+The _hashtags_ gained the option of checking and fixing the hashtag pages by
+adding missing links to tagged blog pages. See _oddmu-hashtags_(1) for more.
+
+In an effort to remove features that can be handled by the web server, the
+_list_, _delete_ and _rename_ actions were removed again. See _oddmu-webdav_(5)
+for a better solution.
+
+You probably need to remove a sentence linking to the list action from the
+upload template ("upload.html").
+
+## 1.17 (2025)
+
+You need to update the upload template ("upload.html"). Many things have
+changed! See _oddmu-templates_(5) for more.
+
+You probably want to ensure that the upload link on the view template
+("view.html") and others, if you added it, has a _filename_ and _pagename_
+parameters.
+
+Example:
+
+```
+<a href="/upload/{{.Dir}}?filename={{.Base}}-1.jpg&pagename={{.Base}}">Upload</a>
+```
+
+You need to change {{.Name}} to {{.Path}} when it is used in URLs, in the list
+template ("list.html"). If you don't do this, file deleting and rename may not
+work on files containing a comma, a semicolon, a questionmark or a hash
+character. This fix was necessary because URLs for files containing a
+questionmark or a hash character would end the path at this character and treat
+the rest as a query parameter or fragment, respectively.
+
+Updated the example themes. Some of my sites got a text area that tries to take
+all the vertical space available. This is great for monitors in portrait mode.
+
+_list_ action now skips dot files.
+
+## 1.16 (2025)
+
+Add support for WebP images for uploading and resizing.
+
+You need to change {{.Name}} to {{.Path}} in HTML templates where pages are
+concerned. If you don't do this, your page names (i.e. filenames for pages) may
+not include a comma, a semicolon, a questionmark or a hash sign. This fix was
+necessary because file uploads of filenames with non-ASCII characters ended up
+double-encoded.
+
+Note that on the "list.html" template, {{.Name}} refers to file instead of a
+page and File.Path() isn't implemented, yet. This is fixed in the next release.
+
+Improved the example themes. The chat theme got better list styling and better
+upload functionality with automatic "add" button; the plain theme got rocket
+links via JavaScript; the alexschroeder.ch theme got a preview button and better
+image support for upload and search; the transjovian.org theme got better image
+support for upload.
+
+Switch the _html_, _link_, _notify_ and _toc_ subcommand to take filenames
+(including the `.md` suffix) instead of page names (without the `.md` suffix).
+
+## 1.15 (2025)
+
+Fix the hashtag detection. This was necessary to cut down on the many false
+positives. They were most obvious with the _hashtags_ subcommand. Now the
+Markdown parser is used at startup to index the pages, making startup slower
+(about twice as long with my blog). The Markdown parser is also used to parse
+search terms (where it makes little difference).
+
+Fix the timestamp for backup files. This was necessary because the diff didn't
+work as intended.
+
+## 1.14 (2024)
+
+Add _list_, _delete_ and _rename_ actions.
+
+This requires a change to your web server setup if you are using a it as a
+reverse proxy because you need to pass these new actions along to Oddmu,
+together with appropriate permission checks.
+
+See _oddmu-apache_(5) or _oddmu-nginx_(5) for example.
+
+In addition to that, you might want a link to the _list_ action from one of the
+existing templates. For example, from upload.html:
+
+```
+<p>You can rename and delete files <a href="/list/{{.Dir}}">from the file list</a>.
+```
+
+The following line was added to the "preview.html" and "edit.html" template:
+
+```
+<base href="/view/{{.Dir}}">
+```
+
+You might want to do that as well, if you have your own. Without this, links in
+the preview cannot be followed as they all point to */preview* instead of
+*/view* and the link to the list of changes cannot be followed from the edit
+page: it leads to editing the list of changes.
+
+## 1.13 (2024)
+
+Add _export_ subcommand.
+
+## 1.12 (2024)
+
+Add _hashtags_, _links_ and _toc_ subcommands.
+
+Support searching for multiple words using all sorts of quotation marks. That
+means that it is now impossible to search for words that begin with such a
+quotation mark.
+
+These are the quotation marks currently supported: 'foo' "foo" ‘foo’ ‚foo‘ ’foo’
+“foo” „foo“ ”foo” «foo» »foo« ‹foo› ›foo‹ ｢foo｣ 「ｆｏｏ」 『ｆｏｏ』 – any such
+quoted text is searched as-is, including whitespace.
+
+Add loading="lazy" for images in search.html
+
+If you want to take advantage of this, you'll need to adapt your "search.html"
+template accordingly. Use like this, for example:
+
+```
+{{range .Items}}
+<article lang="{{.Language}}">
+  <p><a class="result" href="/view/{{.Name}}">{{.Title}}</a>
+    <span class="score">{{.Score}}</span></p>
+  <blockquote>{{.Html}}</blockquote>
+  {{range .Images}}
+  <p class="image"><a href="/view/{{.Name}}"><img loading="lazy" src="/view/{{.Name}}"></a><br/>{{.Html}}
+  {{end}}
+</article>
+{{end}}
+```
+
+## 1.11 (2024)
+
+The HTML renderer option for smart fractions support was removed. Therefore, 1/8
+no longer turns into ⅛ or ¹⁄₈. The benefit is that something like "doi:
+10.1017/9781009157926.007" doesn't turn into "doi: 10.1017⁄9781009157926.007".
+If you need to change this, take a look at the _wikiRenderer_ function.
+
+When search terms (excluding hashtags) match the alt text given for an image,
+that image is part of the data available to the search template.
+
+If you want to take advantage of this, you'll need to adapt your "search.html"
+template accordingly. Use like this, for example:
+
+```
+{{range .Items}}
+<article lang="{{.Language}}">
+  <p><a class="result" href="/view/{{.Name}}">{{.Title}}</a>
+    <span class="score">{{.Score}}</span></p>
+  <blockquote>{{.Html}}</blockquote>
+  {{range .Images}}
+  <p class="image"><a href="/view/{{.Name}}"><img class="last" src="/view/{{.Name}}"></a><br/>{{.Html}}
+  {{end}}
+</article>
+{{end}}
+```
+
+## 1.10 (2024)
+
+You can now preview edits instead of saving them.
+
+- a preview button was added to "edit.html"
+- a new "preview.html" was added
+
+If you want to take advantage of this, you'll need to adapt your templates
+accordingly. The "preview.html" template is a mix of "view.html" and
+"edit.html".
+
+There is an optional change to make to copies of _upload.html_ if you upload
+multiple images at a time. Instead of showing just the link to the last upload,
+you can now show the link (and the images or links, if you want to) to all the
+files uploaded. Use like this, for example:
+
+```
+Links:<tt>{{range .Actual}}<br>![]({{.}}){{end}}</tt>
+```
+
+## 1.9 (2024)
+
+There is a change to make to copies of _upload.html_ if subdirectories are being
+used. The _Last_ property no longer contains the directory. It has to be added
+to the template as follows:
+
+```
+{{if ne .Last ""}}
+<p>Previous upload: <a href="/view/{{.Dir}}{{.Last}}">{{.Last}}</a></p>
+{{if .Image}}
+<p><img class="last" src="/view/{{.Dir}}{{.Last}}"></p>
+{{end}}
+{{end}}
+```
+
+You can use the _Last_ property without a directory to suggest the markup to
+use, for example:
+
+```
+<p>Use the following for <a href="/view/{{.Dir}}{{.Today}}">{{.Today}}</a>:
+<pre>![]({{.Last}})</a></pre>
+```
+
+The upload template can use the _Today_ property.
+
+The upload template comes with JavaScript that allows users to paste images or
+drag and drop files.
+
+The upload template changed the id for the filename field from `text` to `name`.
+
+The source repository now comes with example templates.
+
+## 1.8 (2024)
+
+No user-visible changes. Documentation and code comments got better.
+
+## 1.7 (2024)
+
+Allow upload of multiple files. This requires an update to the _upload.html_
+template: Add the _multiple_ attribute to the file input element and change the
+label from "file" to "files".
+
+Fix orientation of uploaded images. JPG and HEIC images have EXIF data telling a
+viewer how to orient the image. Oddmu now uses this information to rotate the
+image correctly before stripping it.
+
+The version command now displays much less information unless given the -full
+argument.
+
+## 1.6 (2024)
+
+Add _archive_ action to serve a zip file.
+
+## 1.5 (2024)
+
+Filtering separate sites in subdirectories via the ODDMU_FILTER environment
+variable in order to exclude them from the _search_ action.
+
+Add _version_ subcommand.
+
+Add filesystem watchers to automatically reindex changed pages and reload
+changed templates.
+
+When rendering a page, use templates in the same directory, if available.
+
+Delete uploaded files by uploading a file with zero bytes.
+
+## 1.4 (2024)
+
+If stdin is a Unix-domain socket, use that to serve the site. Otherwise, allow
+specifying a listen address via the ODDMU_ADDRESS environment variable.
+
+## 1.3 (2024)
+
+Add support for resizing HEIC images (and saving them as JPG files).
+
+## 1.2 (2023)
+
+Add _list_ subcommand.
+
+## 1.1 (2023)
+
+Rewrote most of the README into man pages.
+
+Add fediverse account rendering if ODDMU_WEBFINGER is set.
+
+Add notifications when saving files: adding links to _index_, _changes_ and
+_hashtag_ pages.
+
+Add _replace_ subcommand. Add _missing_ subcommand. Add _notify_ command. Add
+_static_ command.
+
+Add _diff_ action.
+
+Add feed generation based on the local links from a page.
+
+Add caching support by considering the If-Modified-Since header in requests and
+providing a Last-Modified header in responses.
+
+Handle HEAD requests.
+
+Remove HTML sanitization.
+
+Remove MathJax support from the wiki parser. The templates never included the
+necessary MathJax JavaScript anyway so the special handling of $ was just an
+annoyance.
+
+Drop trigram index and just search all the files. This takes much less RAM and
+doesn't take too much time even with a few thousand pages.
+
+Add "blog:true" and "blog:false" predicates to search.
+
+Limit search to the current directory tree.
+
+Do not overwrite fresh backups: there must be a 1h break before the backup is
+overwritten.
+
+## 1.0 (2023)
+
+Paginate search results and no longer sort search results by score.
+
+## 0.9 (2023)
+
+Add image resizing.
+
+Add wiki links in double square brackets to the parser.
+
+## 0.8 (2023)
+
+Rename files to backups before saving.
+
+Rename the _saveUpload_ action to _drop_.
+
+Add the _search_ subcommand.
+
+## 0.7 (2023)
+
+Add _upload_ and _saveUpload_ action so that one can upload files.
+
+Add _html_ subcommand.
+
+## 0.6 (2003)
+
+Add _add_ and _append_ action so that one can add to an existing page. This is
+important for me as editing pages on the phone can be cumbersome but leaving
+comments on my own site has always been easy to do.
+
+Serve all existing files, not just text files.
+
+Save an empty page to delete it.
+
+Changed default permissions from 600 to 644 for files and from 700 to 755 for
+directories.
+
+Make language detection configurable using an environment variable.
+
+## 0.5 (2023)
+
+Add hyphenation to templates using Peter M. Stahl's Lingua library.
+
+## 0.4 (2023)
+
+Create subdirectories as necessary.
+
+## 0.3 (2023)
+
+Add _search_ action using Damian Gryski's trigram indexing, with scoring,
+highlighting and snippet extraction.
+
+## 0.2 (2023)
+
+Switch to Krzysztof Kowalczyk's Go Markdown fork of Blackfriday to render
+Markdown. Use Dee's Bluemonday to sanitize HTML.
+
+Switch to GNU Affero GPL 3 license.
+
+Serve text files (.txt).
+
+Support serving on any port via the environment variable ODDMU_PORT.
+
+## 0.1 (2015)
+
+A web server that allows editing files in Wiki Creole Matt Self's Cajun library.
+Supported actions are _edit_, _save_, and _view_.
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-replace.1

@@ -0,0 +1,105 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-REPLACE" "1" "2025-03-05"
+.PP
+.SH NAME
+.PP
+oddmu-replace - replace text in Oddmu pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu replace\fR [-confirm] [-regexp] \fIterm\fR \fIreplacement\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "replace" subcommand does a search and replace on all the Markdown files in
+the current directory and its subdirectories.\&
+.PP
+.SH OPTIONS
+.PP
+\fB-confirm\fR
+.RS 4
+By default, the replacement doesn'\&t save the changes made.\& Instead, a
+unified diff is produced and printed.\& Given this option, the changed
+Markdown files are saved to disk.\&
+.PP
+.RE
+\fB-regexp\fR
+.RS 4
+By default, the term to be replaced is just a string.\& With this flag,
+the term is a regular expression and the replacement can contain
+backreferences ($1, $2, $3, etc.\&) to capture groups.\&
+.PP
+.RE
+.SH EXAMPLES
+.PP
+Replace "Oddmu" in the Markdown files of the current directory:
+.PP
+.nf
+.RS 4
+oddmu replace Oddmu Oddμ
+.fi
+.RE
+.PP
+Result:
+.PP
+.nf
+.RS 4
+--- README\&.md~
++++ README\&.md
+
+(diff omitted)
+
+1 file would be changed\&.
+This is a dry run\&. Use -confirm to make it happen\&.
+.fi
+.RE
+.PP
+.SH NOTES
+.PP
+This is the equivalent of using \fIsed\fR(1) with the --quiet, --regexp-extended,
+--in-place=~ and --expression command with the s command
+"s/regexp/replacement/g" except that it prints a unified diff per default
+instead of making any changes and the regexp rules differ slightly.\&
+.PP
+The search is case-sensitive.\& To make it case-insensitive, search for a regular
+expression that sets the case-insensitive flag, e.\&g.\& "(?\&i)oddmu".\&
+.PP
+.SH SECURITY
+.PP
+Consider creating a backup before doing replacements!\&
+.PP
+The following Bash script creates a copy of the current directory using hard
+links.\& If you'\&re in a directory called "wiki", it creates a sibling directory
+called "wiki-2023-11-24" (using the current date) full of links.\& This takes
+little space and time.\& It works as a backup as long as you don'\&t use an
+application that edits files in place.\& Most programs overwrite old files by
+creating new files with the same name, so you should be safe.\&
+.PP
+.nf
+.RS 4
+#!/usr/bin/bash
+d=$(basename $(pwd))
+t=$(date --iso-8601)
+echo Creating a snapshot of $d in \&.\&./$d-$t
+rsync --link-dest "\&.\&./$d" --archive \&. "\&.\&./$d-$t/"
+.fi
+.RE
+.PP
+The above wouldn'\&t work for database files, for example.\& There, the database
+changes the file in place thus the file is changed in the backup directory as
+well.\& For Oddmu and the usual text editors, it works.\& If you use Emacs, don'\&t
+set \fIbackup-by-copying\fR, \fIbackup-by-copying-when-linked\fR and related variables.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-search\fR(7)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-replace.1.txt

@@ -0,0 +1,88 @@
+ODDMU-REPLACE(1)
+
+# NAME
+
+oddmu-replace - replace text in Oddmu pages
+
+# SYNOPSIS
+
+*oddmu replace* [-confirm] [-regexp] _term_ _replacement_
+
+# DESCRIPTION
+
+The "replace" subcommand does a search and replace on all the Markdown files in
+the current directory and its subdirectories.
+
+# OPTIONS
+
+*-confirm*
+	By default, the replacement doesn't save the changes made. Instead, a
+	unified diff is produced and printed. Given this option, the changed
+	Markdown files are saved to disk.
+
+*-regexp*
+	By default, the term to be replaced is just a string. With this flag,
+	the term is a regular expression and the replacement can contain
+	backreferences ($1, $2, $3, etc.) to capture groups.
+
+# EXAMPLES
+
+Replace "Oddmu" in the Markdown files of the current directory:
+
+```
+oddmu replace Oddmu Oddμ
+```
+
+Result:
+
+```
+--- README.md~
++++ README.md
+
+(diff omitted)
+
+1 file would be changed.
+This is a dry run. Use -confirm to make it happen.
+```
+
+# NOTES
+
+This is the equivalent of using _sed_(1) with the --quiet, --regexp-extended,
+\--in-place=~ and --expression command with the s command
+"s/regexp/replacement/g" except that it prints a unified diff per default
+instead of making any changes and the regexp rules differ slightly.
+
+The search is case-sensitive. To make it case-insensitive, search for a regular
+expression that sets the case-insensitive flag, e.g. "(?i)oddmu".
+
+# SECURITY
+
+Consider creating a backup before doing replacements!
+
+The following Bash script creates a copy of the current directory using hard
+links. If you're in a directory called "wiki", it creates a sibling directory
+called "wiki-2023-11-24" (using the current date) full of links. This takes
+little space and time. It works as a backup as long as you don't use an
+application that edits files in place. Most programs overwrite old files by
+creating new files with the same name, so you should be safe.
+
+```
+#!/usr/bin/bash
+d=$(basename $(pwd))
+t=$(date --iso-8601)
+echo Creating a snapshot of $d in ../$d-$t
+rsync --link-dest "../$d" --archive . "../$d-$t/"
+```
+
+The above wouldn't work for database files, for example. There, the database
+changes the file in place thus the file is changed in the backup directory as
+well. For Oddmu and the usual text editors, it works. If you use Emacs, don't
+set _backup-by-copying_, _backup-by-copying-when-linked_ and related variables.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-search_(7)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-search.1

@@ -0,0 +1,92 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-SEARCH" "1" "2025-03-05"
+.PP
+.SH NAME
+.PP
+oddmu-search - search the Oddmu pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu search\fR [-extract] [-page \fIn\fR] \fIterms.\&.\&.\&\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "search" subcommand resursively searches the Markdown files in the current
+directory tree.\& That is, the files in the current directory and all its child
+directories are searched.\&
+.PP
+Be default, this returns a Markdown-formatted list suitable for pasting into
+Oddmu pages.\&
+.PP
+If a directory is provided, only files from the tree starting at that
+subdirectory are listed, and the directory is stripped from the page name.\&
+.PP
+If multiple terms are provided, they are all concatenated into a single,
+space-separated query string.\& That is, searching for the terms A B and the term
+"A B" is equivalent.\&
+.PP
+See \fIoddmu-search\fR(7) for more information of how pages are searched, sorted and
+scored.\&
+.PP
+.SH OPTIONS
+.PP
+\fB-dir\fR \fIstring\fR
+.RS 4
+Limit search to a particular directory.\&
+.RE
+\fB-extract\fR
+.RS 4
+Print search extracts for interactive use
+.RE
+\fB-page\fR \fIn\fR
+.RS 4
+Search results are paginated and by default only the first page is
+shown.\& This option allows you to view other pages.\&
+.RE
+\fB-all\fR
+.RS 4
+Ignore pagination and just print a long list of results.\&
+.PP
+.RE
+.SH EXAMPLES
+.PP
+Search for the two words "Alex" and "Schroeder".\& All of the following are
+equivalent: Alex Schroeder, Schroeder Alex, "Alex Schroeder", "Schroeder Alex".\&
+The ordering of terms does not matter.\&
+.PP
+.nf
+.RS 4
+~/src/oddmu $ oddmu search Alex Schroeder
+Search for Alex Schroeder, page 1: 3 results
+* [Alex Schroeder theme](themes/alexschroeder\&.ch/README)
+* [Oddμ: A minimal wiki](README)
+* [Themes](themes/index)
+.fi
+.RE
+.PP
+Search for the exact phrase "Alex Schroeder".\& In order to pass the quotes to
+Oddmu, a second level of quotes is required.\& All of the following are
+equivalent: '\&"Alex Schroeder"'\&, "'\&Alex Schroeder'\&", \e"Alex\e Schroeder\e",
+\e"Alex Schroeder\e".\&
+.PP
+.nf
+.RS 4
+~/src/oddmu $ oddmu search "\&'Alex Schroeder\&'"
+Search for \&'Alex Schroeder\&', page 1: 1 result
+* [Alex Schroeder theme](themes/alexschroeder\&.ch/README)
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-replace\fR(1), \fIoddmu-search\fR(7)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-search.1.txt

@@ -0,0 +1,73 @@
+ODDMU-SEARCH(1)
+
+# NAME
+
+oddmu-search - search the Oddmu pages
+
+# SYNOPSIS
+
+*oddmu search* [-extract] [-page _n_] _terms..._
+
+# DESCRIPTION
+
+The "search" subcommand resursively searches the Markdown files in the current
+directory tree. That is, the files in the current directory and all its child
+directories are searched.
+
+Be default, this returns a Markdown-formatted list suitable for pasting into
+Oddmu pages.
+
+If a directory is provided, only files from the tree starting at that
+subdirectory are listed, and the directory is stripped from the page name.
+
+If multiple terms are provided, they are all concatenated into a single,
+space-separated query string. That is, searching for the terms A B and the term
+"A B" is equivalent.
+
+See _oddmu-search_(7) for more information of how pages are searched, sorted and
+scored.
+
+# OPTIONS
+
+*-dir* _string_
+	Limit search to a particular directory.
+*-extract*
+	Print search extracts for interactive use
+*-page* _n_
+	Search results are paginated and by default only the first page is
+	shown. This option allows you to view other pages.
+*-all*
+	Ignore pagination and just print a long list of results.
+
+# EXAMPLES
+
+Search for the two words "Alex" and "Schroeder". All of the following are
+equivalent: Alex Schroeder, Schroeder Alex, "Alex Schroeder", "Schroeder Alex".
+The ordering of terms does not matter.
+
+```
+~/src/oddmu $ oddmu search Alex Schroeder
+Search for Alex Schroeder, page 1: 3 results
+* [Alex Schroeder theme](themes/alexschroeder.ch/README)
+* [Oddμ: A minimal wiki](README)
+* [Themes](themes/index)
+```
+
+Search for the exact phrase "Alex Schroeder". In order to pass the quotes to
+Oddmu, a second level of quotes is required. All of the following are
+equivalent: '"Alex Schroeder"', "'Alex Schroeder'", \\"Alex\\ Schroeder\\",
+\\"Alex Schroeder\\".
+
+```
+~/src/oddmu $ oddmu search "'Alex Schroeder'"
+Search for 'Alex Schroeder', page 1: 1 result
+* [Alex Schroeder theme](themes/alexschroeder.ch/README)
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-replace_(1), _oddmu-search_(7)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-search.7

@@ -0,0 +1,107 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-SEARCH" "7" "2025-03-05"
+.PP
+.SH NAME
+.PP
+oddmu-search - understanding the Oddmu search engine
+.PP
+.SH DESCRIPTION
+.PP
+The wiki keeps an index of all the hash tags and page titles in memory.\& Using
+hashtags and predicates in your queries speeds them up because fewer files are
+opened.\&
+.PP
+A hashtag starts with a number sign ('\&#'\&) and contains numbers, letters, and the
+underscore ('\&_'\&).\&
+.PP
+Example: #old_school random encounter
+.PP
+The title predicate filters for pages where the term is contained in the page
+title.\&
+.PP
+Example: title:geo title:cache zürich
+.PP
+The blog predicate filters for pages where the page name begins with an ISO date
+like "2023-09-26" if true, or doesn'\&t begin with an ISO date if false.\&
+.PP
+Example: blog:false fountain
+.PP
+The sorting of all the pages does not depend on the number of matches or any
+kind of score because computing the score is expensive as this requires the page
+to be loaded from disk.\& Therefore, results are sorted by title:
+.PP
+.PD 0
+.IP \(bu 4
+If a page title matches the query string exactly, it gets sorted first.\&
+.IP \(bu 4
+If the page title contains the query string, it gets sorted next.\&
+.IP \(bu 4
+If the page name starts with a number, it is sorted descending.\&
+.IP \(bu 4
+All other pages follow, sorted ascending.\&
+.PD
+.PP
+The effect is that first, the pages with matches in the page title are shown,
+and then all the others.\& Within these two groups, the most recent blog posts are
+shown first.\& This assumes that blog pages start with an ISO date like
+"2023-09-16".\&
+.PP
+When searching for a hashtag, a page name (not the title!\&) matching the hashtag
+exactly (without the leading '\&#'\&) is listed first, even if it doesn'\&t contain
+the hashtag.\& It is assumed that this page offers some kind of introduction to
+people searching for the hashtag.\&
+.PP
+Example: When people click on the hashtag "#Oddμ" and a page named "Oddμ" exists
+(in other words, the file "Oddμ.\&md" exists), it is prepended to the results even
+if it doesn'\&t have the hashtag "#Oddμ" and even if it has a title of "Oddμ, a
+minimal wiki" (which wouldn'\&t be an exact match).\&
+.PP
+The score and highlighting of snippets is used to help visitors decide which
+links to click.\&
+.PP
+Each document found is scored.\& Each of the following increases the score by one
+point:
+.PP
+.PD 0
+.IP \(bu 4
+the entire phrase matches
+.IP \(bu 4
+a word matches
+.IP \(bu 4
+a word matches at the beginning of a word
+.IP \(bu 4
+a word matches at the end of a word
+.IP \(bu 4
+a word matches as a whole word
+.PD
+.PP
+A document with content "This is a test" when searched with the phrase "this
+test" therefore gets a score of 8: the entire phrase does not match but each
+word gets four points.\&
+.PP
+.SH ENVIRONMENT
+.PP
+To exclude subdirectories from searches, use the ODDMU_FILTER environment
+variable.\& Set it to a regular expression matching sub-directories such as
+"^projects/".\& If search starts in a directory matching the regular expression,
+it is limited to the directory tree, as always.\& However, if search starts in a
+directory that doesn'\&t match, subdirectories that do match are skipped.\& See
+\fIoddmu-filter\fR(7).\&
+.PP
+To prevent access to a private directory tree, you must configure the web server
+in addition to setting the ODDMU_FILTER environment variable.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-search\fR(1), \fIoddmu-filter\fR(7), \fIoddmu-apache\fR(5),
+\fIoddmu-nginx\fR(5)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-search.7.txt

@@ -0,0 +1,87 @@
+ODDMU-SEARCH(7)
+
+# NAME
+
+oddmu-search - understanding the Oddmu search engine
+
+# DESCRIPTION
+
+The wiki keeps an index of all the hash tags and page titles in memory. Using
+hashtags and predicates in your queries speeds them up because fewer files are
+opened.
+
+A hashtag starts with a number sign ('#') and contains numbers, letters, and the
+underscore ('\_').
+
+Example: #old_school random encounter
+
+The title predicate filters for pages where the term is contained in the page
+title.
+
+Example: title:geo title:cache zürich
+
+The blog predicate filters for pages where the page name begins with an ISO date
+like "2023-09-26" if true, or doesn't begin with an ISO date if false.
+
+Example: blog:false fountain
+
+The sorting of all the pages does not depend on the number of matches or any
+kind of score because computing the score is expensive as this requires the page
+to be loaded from disk. Therefore, results are sorted by title:
+
+- If a page title matches the query string exactly, it gets sorted first.
+- If the page title contains the query string, it gets sorted next.
+- If the page name starts with a number, it is sorted descending.
+- All other pages follow, sorted ascending.
+
+The effect is that first, the pages with matches in the page title are shown,
+and then all the others. Within these two groups, the most recent blog posts are
+shown first. This assumes that blog pages start with an ISO date like
+"2023-09-16".
+
+When searching for a hashtag, a page name (not the title!) matching the hashtag
+exactly (without the leading '#') is listed first, even if it doesn't contain
+the hashtag. It is assumed that this page offers some kind of introduction to
+people searching for the hashtag.
+
+Example: When people click on the hashtag "#Oddμ" and a page named "Oddμ" exists
+(in other words, the file "Oddμ.md" exists), it is prepended to the results even
+if it doesn't have the hashtag "#Oddμ" and even if it has a title of "Oddμ, a
+minimal wiki" (which wouldn't be an exact match).
+
+The score and highlighting of snippets is used to help visitors decide which
+links to click.
+
+Each document found is scored. Each of the following increases the score by one
+point:
+
+- the entire phrase matches
+- a word matches
+- a word matches at the beginning of a word
+- a word matches at the end of a word
+- a word matches as a whole word
+
+A document with content "This is a test" when searched with the phrase "this
+test" therefore gets a score of 8: the entire phrase does not match but each
+word gets four points.
+
+# ENVIRONMENT
+
+To exclude subdirectories from searches, use the ODDMU_FILTER environment
+variable. Set it to a regular expression matching sub-directories such as
+"^projects/". If search starts in a directory matching the regular expression,
+it is limited to the directory tree, as always. However, if search starts in a
+directory that doesn't match, subdirectories that do match are skipped. See
+_oddmu-filter_(7).
+
+To prevent access to a private directory tree, you must configure the web server
+in addition to setting the ODDMU_FILTER environment variable.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-search_(1), _oddmu-filter_(7), _oddmu-apache_(5),
+_oddmu-nginx_(5)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-static.1

@@ -0,0 +1,96 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-STATIC" "1" "2024-08-29"
+.PP
+.SH NAME
+.PP
+oddmu-static - create a static copy of the site
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu static\fR \fIdir-name\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "static" subcommand generates a static copy of the pages in the current
+directory and saves them in the given destination directory.\& Existing files are
+only overwritten if they are older than the source file.\&
+.PP
+All pages (files with the ".\&md" extension) are turned into HTML files (with the
+".\&html" extension) using the "static.\&html" template.\& Links pointing to existing
+pages get ".\&html" appended.\&
+.PP
+If a page has a name case-insensitively matching a hashtag, a feed file is
+generated (ending with ".\&rss") if any suitable links are found.\& A suitable link
+for a feed item must appear in a bullet list item using an asterisk ("*").\& If
+no feed items are found, no feed is written.\&
+.PP
+Hidden files and directories (starting with a ".\&") and backup files (ending with
+a "~") are skipped.\&
+.PP
+All other files are \fIhard linked\fR.\& This is done to save space: on a typical blog
+the images take a lot more space than the text.\& On my blog in 2023 I had 2.\&62
+GiB of JPG files and 0.\&02 GiB of Markdown files.\& There is no point in copying
+all those images, most of the time.\&
+.PP
+Note, however: Hard links cannot span filesystems.\& A hard link is just an extra
+name for the same file.\& This is why the destination directory for the static
+site has to be on same filesystem as the current directory, if it contains any
+other files besides Markdown files.\&
+.PP
+Furthermore, in-place editing changes the file for all names.\& Avoid editing the
+hard-linked files (anything that'\&s not a HTML file) in the destination
+directory, just to be on the safe side.\& Usually you should be fine, as an editor
+moves the file that'\&s being edited to a backup file and creates a new file.\& But
+then again, who knows.\& A SQLite file, for example, would change in-place, and
+therefore making changes to it in the destination directory would change the
+original, too.\&
+.PP
+.SH EXAMPLES
+.PP
+Generate a static copy of the site, but only loading language detection for
+German and English, significantly reducing the time it takes to generate the
+static site:
+.PP
+.nf
+.RS 4
+env ODDMU_LANGUAGES=de,en oddmu static \&.\&./archive
+.fi
+.RE
+.PP
+.SH LIMITATIONS
+.PP
+There can be nameclashes with generated HTML and RSS files and existing files
+ending in ".\&html" and ".\&rss".\& Instead of overwriting existing files in these
+cases, a warning is printed.\&
+.PP
+Links from files to pages do not get ".\&html" appended.\& This affects existing
+HTML or XML files including SVG files.\&
+.PP
+Links to absolute URLs (starting with "/") are not changed at all.\& It is up to
+you to migrate static folders and applications.\&
+.PP
+.SH ENVIRONMENT
+.PP
+The ODDMU_WEBFINGER environment variable has no effect in this situation.\&
+Fediverse accounts are not linked to their profile pages.\& Since the data isn'\&t
+cached, every run of this command would trigger a webfinger request for every
+fediverse account mentioned.\&
+.PP
+If the site is large, determining the language of a page slows things down.\& Set
+the ODDMU_LANGUAGES environment variable to a comma-separated list of ISO 639-1
+codes, e.\&g.\& "en" or "en,de,fr,pt" to limit the languages loaded and thereby
+speed language determination up.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-templates\fR(5)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-static.1.txt

@@ -0,0 +1,87 @@
+ODDMU-STATIC(1)
+
+# NAME
+
+oddmu-static - create a static copy of the site
+
+# SYNOPSIS
+
+*oddmu static* _dir-name_
+
+# DESCRIPTION
+
+The "static" subcommand generates a static copy of the pages in the current
+directory and saves them in the given destination directory. Existing files are
+only overwritten if they are older than the source file.
+
+All pages (files with the ".md" extension) are turned into HTML files (with the
+".html" extension) using the "static.html" template. Links pointing to existing
+pages get ".html" appended.
+
+If a page has a name case-insensitively matching a hashtag, a feed file is
+generated (ending with ".rss") if any suitable links are found. A suitable link
+for a feed item must appear in a bullet list item using an asterisk ("\*"). If
+no feed items are found, no feed is written.
+
+Hidden files and directories (starting with a ".") and backup files (ending with
+a "~") are skipped.
+
+All other files are _hard linked_. This is done to save space: on a typical blog
+the images take a lot more space than the text. On my blog in 2023 I had 2.62
+GiB of JPG files and 0.02 GiB of Markdown files. There is no point in copying
+all those images, most of the time.
+
+Note, however: Hard links cannot span filesystems. A hard link is just an extra
+name for the same file. This is why the destination directory for the static
+site has to be on same filesystem as the current directory, if it contains any
+other files besides Markdown files.
+
+Furthermore, in-place editing changes the file for all names. Avoid editing the
+hard-linked files (anything that's not a HTML file) in the destination
+directory, just to be on the safe side. Usually you should be fine, as an editor
+moves the file that's being edited to a backup file and creates a new file. But
+then again, who knows. A SQLite file, for example, would change in-place, and
+therefore making changes to it in the destination directory would change the
+original, too.
+
+# EXAMPLES
+
+Generate a static copy of the site, but only loading language detection for
+German and English, significantly reducing the time it takes to generate the
+static site:
+
+```
+env ODDMU_LANGUAGES=de,en oddmu static ../archive
+```
+
+# LIMITATIONS
+
+There can be nameclashes with generated HTML and RSS files and existing files
+ending in ".html" and ".rss". Instead of overwriting existing files in these
+cases, a warning is printed.
+
+Links from files to pages do not get ".html" appended. This affects existing
+HTML or XML files including SVG files.
+
+Links to absolute URLs (starting with "/") are not changed at all. It is up to
+you to migrate static folders and applications.
+
+# ENVIRONMENT
+
+The ODDMU_WEBFINGER environment variable has no effect in this situation.
+Fediverse accounts are not linked to their profile pages. Since the data isn't
+cached, every run of this command would trigger a webfinger request for every
+fediverse account mentioned.
+
+If the site is large, determining the language of a page slows things down. Set
+the ODDMU_LANGUAGES environment variable to a comma-separated list of ISO 639-1
+codes, e.g. "en" or "en,de,fr,pt" to limit the languages loaded and thereby
+speed language determination up.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-templates_(5)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-templates.5

@@ -0,0 +1,351 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-TEMPLATES" "5" "2025-04-26" "File Formats Manual"
+.PP
+.SH NAME
+.PP
+oddmu-templates - how to write the templates
+.PP
+.SH SYNOPSIS
+.PP
+Some HTML files act as templates.\& They contain special placeholders in double
+bracers {{like this}}.\&
+.PP
+.SH DESCRIPTION
+.PP
+Each template receives an object and uses the object'\&s properties to replace the
+placeholders.\&
+.PP
+.PD 0
+.IP \(bu 4
+\fIadd.\&html\fR uses a \fIpage\fR
+.IP \(bu 4
+\fIdiff.\&html\fR uses a \fIpage\fR
+.IP \(bu 4
+\fIedit.\&html\fR uses a \fIpage\fR
+.IP \(bu 4
+\fIfeed.\&html\fR uses a \fIfeed\fR
+.IP \(bu 4
+\fIlist.\&html\fR uses a \fIlist\fR
+.IP \(bu 4
+\fIpreview.\&html\fR uses a \fIpage\fR
+.IP \(bu 4
+\fIsearch.\&html\fR uses a \fIsearch\fR
+.IP \(bu 4
+\fIstatic.\&html\fR uses a \fIpage\fR
+.IP \(bu 4
+\fIupload.\&html\fR uses an \fIupload\fR
+.IP \(bu 4
+\fIview.\&html\fR uses a \fIpage\fR
+.PD
+.PP
+The following property lists always indicate whether the property is
+percent-encoded or not.\& In theory, the html/template package would handle this.\&
+The problem is that the package gives special treatment to the semicolon, comma,
+question-mark and hash-sign as these are potential separators in a URL.\&
+.PP
+Consider the following:
+.PP
+.nf
+.RS 4
+<a href="{{\&.Name}}">{{\&.Name}}</a>
+.fi
+.RE
+.PP
+If \fI.\&Name\fR is "#foo", the html/template package treats it as a URL fragment
+inside the attribute instead of a file path that needs to be escaped to
+"%23foo".\& The same problem arises if \fI.\&Name\fR is "foo?\&" as the questionmark is
+not escaped and therefore treated as the separator between URL path and query
+parameters instead of being part of the name.\&
+.PP
+The consequences for template authors is that the properties that are
+percent-encoded must be used in links where as the regular properties must be
+used outside of links.\&
+.PP
+.SS Page
+.PP
+A page has the following properties:
+.PP
+\fI{{.\&Title}}\fR is the page title.\& If the page doesn'\&t provide its own title, the
+page name is used.\&
+.PP
+\fI{{.\&Name}}\fR is the page name.\& The page name doesn'\&t include the \fI.\&md\fR extension.\&
+.PP
+\fI{{.\&Path}}\fR is the page name, percent-encoded.\&
+.PP
+\fI{{.\&Dir}}\fR is the page directory, percent-encoded.\&
+.PP
+\fI{{.\&Base}}\fR is the basename of the current file (without the directory and
+without the \fI.\&md\fR extension), percent-encoded.\&
+.PP
+\fI{{.\&Language}}\fR is the suspected language of the page.\& This is used to set the
+language on the \fIview.\&html\fR template.\& See "Non-English hyphenation" below.\&
+.PP
+\fI{{.\&Body}}\fR is the raw byte content of the page.\& Use \fI{{printf "%s" .\&Body}}\fR to
+get the Markdown, as a string.\& This is used for the text area of the \fIedit.\&html\fR
+template.\&
+.PP
+\fI{{.\&Hashtags}}\fR is an array of strings.\&
+.PP
+\fI{{.\&Html}}\fR contains some sort of HTML that depends on the template used.\&
+.PP
+.PD 0
+.IP \(bu 4
+For \fIview.\&html\fR, it is the rendered Markdown, as HTML.\&
+.IP \(bu 4
+For \fIsearch.\&html\fR, it is a page summary, with bold matches, as HTML.\&
+.IP \(bu 4
+For \fIfeed.\&html\fR, it is the escaped (!\&) HTML of the feed item.\&
+.PD
+.PP
+\fI{{.\&IsBlog}}\fR says whether the current page has a name starting with an ISO
+date.\&
+.PP
+\fI{{.\&Today}}\fR is the current date, in ISO format.\& This is useful for "new page"
+like links or forms (see \fBEXAMPLE\fR below).\&
+.PP
+\fI{{.\&Parents}}\fR is the array of links to parent pages (see \fBEXAMPLE\fR below).\& To
+refer to them, you need to use a \fI{{range .\&Parents}}\fR … \fI{{end}}\fR construct.\& A
+link has to properties, \fI{{.\&Title}}\fR and \fI{{.\&Url}}\fR.\&
+.PP
+\fI{{.\&Diff}}\fR is the page diff for \fIdiff.\&html\fR.\& It is only computed on demand so
+it can be used in other templates, too.\& It probably doesn'\&t make much sense to
+do so, however.\&
+.PP
+.SS Feed
+.PP
+The feed contains an item for the head of the feed and an array of items.\&
+.PP
+\fI{{.\&Items}}\fR is the array of feed items.\& To refer to them, you need to use a
+\fI{{range .\&Items}}\fR … \fI{{end}}\fR construct.\&
+.PP
+If page A links to pages B and C, the head of the feed is based on page A and
+the list of items contains B and C.\&
+.PP
+An item is a page plus a date.\& All the properties of a page can be used (see
+\fBPage\fR above).\&
+.PP
+\fI{{.\&Date}}\fR is the date of the last update to the page, in RFC 822 format.\&
+.PP
+.SS List
+.PP
+The list contains a directory name and an array of files.\&
+.PP
+\fI{{.\&Dir}}\fR is the directory name that is being listed, percent-encoded.\&
+.PP
+\fI{{.\&Files}}\fR is the array of files.\& To refer to them, you need to use a \fI{{range
+Files}}\fR … \fI{{end}}\fR construct.\&
+.PP
+Each file has the following attributes:
+.PP
+\fI{{.\&Name}}\fR is the filename.\& The ".\&md" suffix for Markdown files is part of the
+name (unlike page names).\&
+.PP
+\fI{{.\&Path}}\fR is the page name, percent-encoded.\&
+.PP
+\fI{{.\&Title}}\fR is the page title, if the file in question is a Markdown file.\&
+.PP
+\fI{{.\&IsDir}}\fR is a boolean used to indicate that this file is a directory.\&
+.PP
+\fI{{.\&IsUp}}\fR is a boolean used to indicate the entry for the parent directory
+(the first file in the array, unless the directory being listed is the top
+directory).\& The filename of this file is ".\&.\&".\&
+.PP
+\fI{{.\&Date}}\fR is the last modification date of the file.\&
+.PP
+.SS Search
+.PP
+\fI{{.\&Query}}\fR is the query string.\&
+.PP
+\fI{{.\&Dir}}\fR is the directory in which the search starts, percent-encoded.\&
+.PP
+\fI{{.\&Previous}}\fR, \fI{{.\&Page}}\fR and \fI{{.\&Next}}\fR are the previous, current and next
+page number in the results since doing arithmetics in templates is hard.\& The
+first page number is 1.\& The last page is expensive to dermine and so that is not
+available.\&
+.PP
+\fI{{.\&More}}\fR indicates if there are any more search results.\&
+.PP
+\fI{{.\&Results}}\fR indicates if there were any search results at all.\&
+.PP
+\fI{{.\&Items}}\fR is an array of results.\& To refer to them, you need to use a
+\fI{{range .\&Items}}\fR … \fI{{end}}\fR construct.\&
+.PP
+A result is a page plus a score and possibly images.\& All the properties of a
+page can be used (see \fBPage\fR above).\&
+.PP
+\fI{{.\&Score}}\fR is a numerical score.\& It is only computed for \fIsearch.\&html\fR.\&
+.PP
+\fI{{.\&Images}}\fR are the images where the alt-text matches at least one of the
+query terms (but not predicates and not hashtags since those apply to the page
+as a whole).\& To refer to them, you need to use a \fI{{range .\&Images}}\fR … \fI{{end}}\fR
+construct.\&
+.PP
+Each image has three properties:
+.PP
+\fI{{.\&Title}}\fR is the alt-text of the image.\& It can never be empty because images
+are only listed if a search term matches.\&
+.PP
+\fI{{.\&Name}}\fR is the file name for use in URLs.\&
+.PP
+\fI{{.\&Html}}\fR the image alt-text with a bold tag used to highlight the first
+search term that matched.\&
+.PP
+.SS Upload
+.PP
+\fI{{.\&Dir}}\fR is the directory where the uploaded file ends up, based on the URL
+path, percent-encoded.\&
+.PP
+\fI{{.\&FileName}}\fR is the \fIfilename\fR query parameter used to suggested a filename.\&
+.PP
+\fI{{.\&FilePath}}\fR is the filename, percent-encoded.\&
+.PP
+\fI{{.\&Name}}\fR is the \fIpagename\fR query parameter used to indicate where to append
+links to the files.\&
+.PP
+\fI{{.\&Path}}\fR is the page name, percent-encoded.\&
+.PP
+\fI{{.\&Title}}\fR is the title of the page, if it exists.\&
+.PP
+\fI{{.\&MaxWidth}}\fR is the \fImaxwidth\fR query parameter, i.\&e.\& the value used for the
+previous image uploaded.\&
+.PP
+\fI{{.\&Quality}}\fR is the \fIquality\fR query parameter, i.\&e.\& the value used for the
+previous image uploaded.\&
+.PP
+\fI{{.\&Today}}\fR is the current date, in ISO format.\&
+.PP
+\fI{{.\&Uploads}}\fR an array of files already uploaded, based on the \fIuploads\fR query
+parameter.\& To refer to them, you need to use a \fI{{range .\&Uploads}}\fR … \fI{{end}}\fR
+construct.\& This is required because the \fIdrop\fR action redirects back to the
+\fIupload\fR action, so after saving one or more files, you can upload even more
+files.\&
+.PP
+Each upload has the following attributes:
+.PP
+\fI{{.\&Name}}\fR is the filename.\&
+.PP
+\fI{{.\&Path}}\fR is the file name, percent-encoded.\&
+.PP
+\fI{{.\&Image}}\fR is a boolean to indicate whether the upload is an image or not
+(such as ending in \fI.\&jpg\fR).\& If so, a thumbnail can be shown by the template, for
+example.\&
+.PP
+.SS Non-English hyphenation
+.PP
+Automatic hyphenation by the browser requires two things: The style sheet must
+indicate "hyphen: auto" for an HTML element such as "body", and that element
+must have a "lang" set (usually a two letter language code such as "de" for
+German).\&
+.PP
+Oddmu attempts to detect the correct language for each page.\& It assumes that
+languages are not mixed on the same page.\& If you know that you'\&re only going to
+use a small number of languages – or just a single language!\& – you can set the
+environment variable ODDMU_LANGUAGES to a comma-separated list of ISO 639-1
+codes, e.\&g.\& "en" or "en,de,fr,pt".\&
+.PP
+"view.\&html" is used to render a single page and so the language detected is
+added to the "html" element.\&
+.PP
+"search.\&html" is the template used to render search results and so "en" is used
+for the "html" element and the language detected for every page in the search
+result is added to the "article" element for each snippet.\&
+.PP
+"edit.\&html" and "add.\&html" are the templates used to edit a page.\& If the page
+already exists, its language is used for the "textarea" element.\& If the page is
+new, no language is used for the "textarea" element.\&
+.PP
+.SH EXAMPLES
+.PP
+The following link in a template takes people to today'\&s page.\& If no such page
+exists, they are redirected to the edit form where it can be created.\&
+.PP
+.nf
+.RS 4
+<a href="/view/{{\&.Today}}" accesskey="t">Today</a>
+.fi
+.RE
+.PP
+The following form allows people to edit the suggested page name.\&
+.PP
+.nf
+.RS 4
+<form role="new" action="/edit/{{\&.Dir}}" method="GET">
+  <label for="id">New page:</label>
+  <input id="id" type="text" spellcheck="false" name="id"
+	  accesskey="g" value="{{\&.Today}}" required>
+  <button>Edit</button>
+</form>
+.fi
+.RE
+.PP
+The following puts the current date into the text area if and only if the page
+itself is a blog page.\& Useful for \fIadd.\&html\fR:
+.PP
+.nf
+.RS 4
+<textarea name="body" rows="20" cols="80" placeholder="Text" lang=""
+	  autofocus required>{{- if \&.IsBlog}}**{{\&.Today}}**\&. {{end}}</textarea>
+.fi
+.RE
+.PP
+The following adds a list of links to parent directories.\& Useful for \fIview.\&html\fR:
+.PP
+.nf
+.RS 4
+<nav>
+{{range \&.Parents}}/ <a href="{{\&.Url}}">{{\&.Title}}</a>{{end}}
+</nav>
+.fi
+.RE
+.PP
+.SH NOTES
+.PP
+The templates are always used as-is, irrespective of the current directory.\&
+Therefore, a link to a specific page must be \fIabsolute\fR or it'\&ll point to a
+different page depending on the current directory.\&
+.PP
+Consider the link to "/view/index".\& No matter what page a visitor is looking,
+this takes visitors to the top "index" page.\& If the link points to "index"
+instead, it takes a visitor to the "index" page of the current directory.\& In
+this case, a visitor looking at "/view/projects/wiki" following a link to
+"index" ends up on "/view/projects/index", not on "/view/index".\&
+.PP
+It'\&s up to you to decide what'\&s best for your site, of course.\&
+.PP
+If you want a link on \fIupload.\&html\fR to point to the current directory'\&s "index"
+page, you need to use "/view/{{.\&Dir}}index" because if you link to "index" the
+result points to "/upload/{{.\&Dir}}index".\&
+.PP
+Templates can be changed by uploading new copies of the template files.\&
+.PP
+Subdirectories can have their own copies of template files.\& One example use for
+this is that they can point to a different CSS file.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+"Structuring the web with HTML"
+https://developer.\&mozilla.\&org/en-US/docs/Learn/HTML
+.PP
+"Learn to style HTML using CSS"
+https://developer.\&mozilla.\&org/en-US/docs/Learn/CSS
+.PP
+The "text/template" library explains how to write templates from a programmer
+perspective.\& https://pkg.\&go.\&dev/text/template
+.PP
+The "html/template" library explains how the templates are made more secure in a
+HTML context.\& https://pkg.\&go.\&dev/html/template
+.PP
+"Lingua" is the library used to detect languages.\&
+https://github.\&com/pemistahl/lingua-go
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-templates.5.txt

@@ -0,0 +1,317 @@
+ODDMU-TEMPLATES(5) "File Formats Manual"
+
+# NAME
+
+oddmu-templates - how to write the templates
+
+# SYNOPSIS
+
+Some HTML files act as templates. They contain special placeholders in double
+bracers {{like this}}.
+
+# DESCRIPTION
+
+Each template receives an object and uses the object's properties to replace the
+placeholders.
+
+- _add.html_ uses a _page_
+- _diff.html_ uses a _page_
+- _edit.html_ uses a _page_
+- _feed.html_ uses a _feed_
+- _list.html_ uses a _list_
+- _preview.html_ uses a _page_
+- _search.html_ uses a _search_
+- _static.html_ uses a _page_
+- _upload.html_ uses an _upload_
+- _view.html_ uses a _page_
+
+The following property lists always indicate whether the property is
+percent-encoded or not. In theory, the html/template package would handle this.
+The problem is that the package gives special treatment to the semicolon, comma,
+question-mark and hash-sign as these are potential separators in a URL.
+
+Consider the following:
+
+```
+<a href="{{.Name}}">{{.Name}}</a>
+```
+
+If _.Name_ is "#foo", the html/template package treats it as a URL fragment
+inside the attribute instead of a file path that needs to be escaped to
+"%23foo". The same problem arises if _.Name_ is "foo?" as the questionmark is
+not escaped and therefore treated as the separator between URL path and query
+parameters instead of being part of the name.
+
+The consequences for template authors is that the properties that are
+percent-encoded must be used in links where as the regular properties must be
+used outside of links.
+
+## Page
+
+A page has the following properties:
+
+_{{.Title}}_ is the page title. If the page doesn't provide its own title, the
+page name is used.
+
+_{{.Name}}_ is the page name. The page name doesn't include the _.md_ extension.
+
+_{{.Path}}_ is the page name, percent-encoded.
+
+_{{.Dir}}_ is the page directory, percent-encoded.
+
+_{{.Base}}_ is the basename of the current file (without the directory and
+without the _.md_ extension), percent-encoded.
+
+_{{.Language}}_ is the suspected language of the page. This is used to set the
+language on the _view.html_ template. See "Non-English hyphenation" below.
+
+_{{.Body}}_ is the raw byte content of the page. Use _{{printf "%s" .Body}}_ to
+get the Markdown, as a string. This is used for the text area of the _edit.html_
+template.
+
+_{{.Hashtags}}_ is an array of strings.
+
+_{{.Html}}_ contains some sort of HTML that depends on the template used.
+
+- For _view.html_, it is the rendered Markdown, as HTML.
+- For _search.html_, it is a page summary, with bold matches, as HTML.
+- For _feed.html_, it is the escaped (!) HTML of the feed item.
+
+_{{.IsBlog}}_ says whether the current page has a name starting with an ISO
+date.
+
+_{{.Today}}_ is the current date, in ISO format. This is useful for "new page"
+like links or forms (see *EXAMPLE* below).
+
+_{{.Parents}}_ is the array of links to parent pages (see *EXAMPLE* below). To
+refer to them, you need to use a _{{range .Parents}}_ … _{{end}}_ construct. A
+link has to properties, _{{.Title}}_ and _{{.Url}}_.
+
+_{{.Diff}}_ is the page diff for _diff.html_. It is only computed on demand so
+it can be used in other templates, too. It probably doesn't make much sense to
+do so, however.
+
+## Feed
+
+The feed contains an item for the head of the feed and an array of items.
+
+_{{.Items}}_ is the array of feed items. To refer to them, you need to use a
+_{{range .Items}}_ … _{{end}}_ construct.
+
+If page A links to pages B and C, the head of the feed is based on page A and
+the list of items contains B and C.
+
+An item is a page plus a date. All the properties of a page can be used (see
+*Page* above).
+
+_{{.Date}}_ is the date of the last update to the page, in RFC 822 format.
+
+## List
+
+The list contains a directory name and an array of files.
+
+_{{.Dir}}_ is the directory name that is being listed, percent-encoded.
+
+_{{.Files}}_ is the array of files. To refer to them, you need to use a _{{range
+.Files}}_ … _{{end}}_ construct.
+
+Each file has the following attributes:
+
+_{{.Name}}_ is the filename. The ".md" suffix for Markdown files is part of the
+name (unlike page names).
+
+_{{.Path}}_ is the page name, percent-encoded.
+
+_{{.Title}}_ is the page title, if the file in question is a Markdown file.
+
+_{{.IsDir}}_ is a boolean used to indicate that this file is a directory.
+
+_{{.IsUp}}_ is a boolean used to indicate the entry for the parent directory
+(the first file in the array, unless the directory being listed is the top
+directory). The filename of this file is "..".
+
+_{{.Date}}_ is the last modification date of the file.
+
+## Search
+
+_{{.Query}}_ is the query string.
+
+_{{.Dir}}_ is the directory in which the search starts, percent-encoded.
+
+_{{.Previous}}_, _{{.Page}}_ and _{{.Next}}_ are the previous, current and next
+page number in the results since doing arithmetics in templates is hard. The
+first page number is 1. The last page is expensive to dermine and so that is not
+available.
+
+_{{.More}}_ indicates if there are any more search results.
+
+_{{.Results}}_ indicates if there were any search results at all.
+
+_{{.Items}}_ is an array of results. To refer to them, you need to use a
+_{{range .Items}}_ … _{{end}}_ construct.
+
+A result is a page plus a score and possibly images. All the properties of a
+page can be used (see *Page* above).
+
+_{{.Score}}_ is a numerical score. It is only computed for _search.html_.
+
+_{{.Images}}_ are the images where the alt-text matches at least one of the
+query terms (but not predicates and not hashtags since those apply to the page
+as a whole). To refer to them, you need to use a _{{range .Images}}_ … _{{end}}_
+construct.
+
+Each image has three properties:
+
+_{{.Title}}_ is the alt-text of the image. It can never be empty because images
+are only listed if a search term matches.
+
+_{{.Name}}_ is the file name for use in URLs.
+
+_{{.Html}}_ the image alt-text with a bold tag used to highlight the first
+search term that matched.
+
+## Upload
+
+_{{.Dir}}_ is the directory where the uploaded file ends up, based on the URL
+path, percent-encoded.
+
+_{{.FileName}}_ is the _filename_ query parameter used to suggested a filename.
+
+_{{.FilePath}}_ is the filename, percent-encoded.
+
+_{{.Name}}_ is the _pagename_ query parameter used to indicate where to append
+links to the files.
+
+_{{.Path}}_ is the page name, percent-encoded.
+
+_{{.Title}}_ is the title of the page, if it exists.
+
+_{{.MaxWidth}}_ is the _maxwidth_ query parameter, i.e. the value used for the
+previous image uploaded.
+
+_{{.Quality}}_ is the _quality_ query parameter, i.e. the value used for the
+previous image uploaded.
+
+_{{.Today}}_ is the current date, in ISO format.
+
+_{{.Uploads}}_ an array of files already uploaded, based on the _uploads_ query
+parameter. To refer to them, you need to use a _{{range .Uploads}}_ … _{{end}}_
+construct. This is required because the _drop_ action redirects back to the
+_upload_ action, so after saving one or more files, you can upload even more
+files.
+
+Each upload has the following attributes:
+
+_{{.Name}}_ is the filename.
+
+_{{.Path}}_ is the file name, percent-encoded.
+
+_{{.Image}}_ is a boolean to indicate whether the upload is an image or not
+(such as ending in _.jpg_). If so, a thumbnail can be shown by the template, for
+example.
+
+## Non-English hyphenation
+
+Automatic hyphenation by the browser requires two things: The style sheet must
+indicate "hyphen: auto" for an HTML element such as "body", and that element
+must have a "lang" set (usually a two letter language code such as "de" for
+German).
+
+Oddmu attempts to detect the correct language for each page. It assumes that
+languages are not mixed on the same page. If you know that you're only going to
+use a small number of languages – or just a single language! – you can set the
+environment variable ODDMU_LANGUAGES to a comma-separated list of ISO 639-1
+codes, e.g. "en" or "en,de,fr,pt".
+
+"view.html" is used to render a single page and so the language detected is
+added to the "html" element.
+
+"search.html" is the template used to render search results and so "en" is used
+for the "html" element and the language detected for every page in the search
+result is added to the "article" element for each snippet.
+
+"edit.html" and "add.html" are the templates used to edit a page. If the page
+already exists, its language is used for the "textarea" element. If the page is
+new, no language is used for the "textarea" element.
+
+# EXAMPLES
+
+The following link in a template takes people to today's page. If no such page
+exists, they are redirected to the edit form where it can be created.
+
+```
+<a href="/view/{{.Today}}" accesskey="t">Today</a>
+```
+
+The following form allows people to edit the suggested page name.
+
+```
+<form role="new" action="/edit/{{.Dir}}" method="GET">
+  <label for="id">New page:</label>
+  <input id="id" type="text" spellcheck="false" name="id"
+	  accesskey="g" value="{{.Today}}" required>
+  <button>Edit</button>
+</form>
+```
+
+The following puts the current date into the text area if and only if the page
+itself is a blog page. Useful for _add.html_:
+
+```
+<textarea name="body" rows="20" cols="80" placeholder="Text" lang=""
+	  autofocus required>{{- if .IsBlog}}**{{.Today}}**. {{end}}</textarea>
+```
+
+The following adds a list of links to parent directories. Useful for _view.html_:
+
+```
+<nav>
+{{range .Parents}}/ <a href="{{.Url}}">{{.Title}}</a>{{end}}
+</nav>
+```
+
+# NOTES
+
+The templates are always used as-is, irrespective of the current directory.
+Therefore, a link to a specific page must be _absolute_ or it'll point to a
+different page depending on the current directory.
+
+Consider the link to "/view/index". No matter what page a visitor is looking,
+this takes visitors to the top "index" page. If the link points to "index"
+instead, it takes a visitor to the "index" page of the current directory. In
+this case, a visitor looking at "/view/projects/wiki" following a link to
+"index" ends up on "/view/projects/index", not on "/view/index".
+
+It's up to you to decide what's best for your site, of course.
+
+If you want a link on _upload.html_ to point to the current directory's "index"
+page, you need to use "/view/{{.Dir}}index" because if you link to "index" the
+result points to "/upload/{{.Dir}}index".
+
+Templates can be changed by uploading new copies of the template files.
+
+Subdirectories can have their own copies of template files. One example use for
+this is that they can point to a different CSS file.
+
+# SEE ALSO
+
+_oddmu_(1)
+
+"Structuring the web with HTML"
+https://developer.mozilla.org/en-US/docs/Learn/HTML
+
+"Learn to style HTML using CSS"
+https://developer.mozilla.org/en-US/docs/Learn/CSS
+
+The "text/template" library explains how to write templates from a programmer
+perspective. https://pkg.go.dev/text/template
+
+The "html/template" library explains how the templates are made more secure in a
+HTML context. https://pkg.go.dev/html/template
+
+"Lingua" is the library used to detect languages.
+https://github.com/pemistahl/lingua-go
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-toc.1

@@ -0,0 +1,32 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-TOC" "1" "2025-04-05"
+.PP
+.SH NAME
+.PP
+oddmu-toc - print the table of contents (toc) for pages
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu toc\fR \fIpage names.\&.\&.\&\fR
+.PP
+.SH DESCRIPTION
+.PP
+The "toc" subcommand prints the table of contents for one or more Markdown
+files.\& Use "-" as the page name if you want to read Markdown from \fBstdin\fR.\&
+.PP
+This can be useful for very long pages that need a table of contents
+at the beginning.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-toc.1.txt

@@ -0,0 +1,25 @@
+ODDMU-TOC(1)
+
+# NAME
+
+oddmu-toc - print the table of contents (toc) for pages
+
+# SYNOPSIS
+
+*oddmu toc* _page names..._
+
+# DESCRIPTION
+
+The "toc" subcommand prints the table of contents for one or more Markdown
+files. Use "-" as the page name if you want to read Markdown from *stdin*.
+
+This can be useful for very long pages that need a table of contents
+at the beginning.
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-version.1

@@ -0,0 +1,38 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-VERSION" "1" "2024-02-23"
+.PP
+.SH NAME
+.PP
+oddmu-version - print build info on the command-line
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu version\fR [-full]
+.PP
+.SH DESCRIPTION
+.PP
+The "version" subcommand prints information related to the version control
+system state when it was built: what remote was used, what commit was checked
+out, whether there were any local changes were made.\&
+.PP
+.SH OPTIONS
+.PP
+\fB-full\fR
+.RS 4
+Print a lot more information, including the versions of dependencies
+used.\& It'\&s the equivalent of running "go version -m oddmu".\&
+.PP
+.RE
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-version.1.txt

@@ -0,0 +1,29 @@
+ODDMU-VERSION(1)
+
+# NAME
+
+oddmu-version - print build info on the command-line
+
+# SYNOPSIS
+
+*oddmu version* [-full]
+
+# DESCRIPTION
+
+The "version" subcommand prints information related to the version control
+system state when it was built: what remote was used, what commit was checked
+out, whether there were any local changes were made.
+
+# OPTIONS
+
+*-full*
+	Print a lot more information, including the versions of dependencies
+	used. It's the equivalent of running "go version -m oddmu".
+
+# SEE ALSO
+
+_oddmu_(1)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu-webdav.5

@@ -0,0 +1,206 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU-WEBDAV" "5" "2025-07-16"
+.PP
+.SH NAME
+.PP
+oddmu-webdav - how to setup Web-DAV using Apache for Oddmu
+.PP
+.SH DESCRIPTION
+.PP
+With the Apache Web-DAV module enabled, users can mount the wiki as a remote
+file system and manage the files using some other tool.\& Using the Apache Web-DAV
+module means that the same user accounts can be used as for the regular wiki.\&
+.PP
+.SH CONFIGURATION
+.PP
+Consider the "campaignwiki.\&org" site in the example below.\& This site offers
+users their own wikis.\& Thus:
+.PP
+"https://campaignwiki.\&org/" is a regular website with static files.\&
+.PP
+"https://campaignwiki.\&org/view/index" is one of the requests that gets passed to
+a Unix domain socket.\& See "Socket Activation" in \fIoddmu\fR(1).\&
+.PP
+Some of these actions are protected by basic authentication.\& A valid user is
+required to make changes to the site.\& Valid users are "admin" and "alex".\&
+.PP
+"data" is the Oddmu working directory.\& WebDAV is turned on for this directory.\& A
+shortcut has been taken, here: The "data" subdirectory requires authentication
+and offers WebDAV access.\& The other paths also require authentication and map to
+Oddmu actions.\& The fact that WebDAV access is "enabled" for the Oddmu actions
+has no effect.\& The only drawback is that "https://campaignwiki.\&org/data/" now
+requires authentication even if only used for reading.\&
+.PP
+"https://campaignwiki.\&org/view/knochentanz/index" is a separate site called
+"knochentanz".\& The only valid user is "knochentanz".\&
+.PP
+Notice how the \fIarchive\fR action is not available at the top level, only for
+subdirectories.\&
+.PP
+.nf
+.RS 4
+MDomain campaignwiki\&.org
+
+<VirtualHost *:80>
+    ServerName campaignwiki\&.org
+    Redirect permanent / https://campaignwiki\&.org/
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerAdmin alex@campaignwiki\&.org
+    ServerName campaignwiki\&.org
+    # Static HTML, CSS, JavaScript files and so on are saved here\&.
+    DocumentRoot /home/alex/campaignwiki\&.org
+    <Directory /home/alex/campaignwiki\&.org>
+        Options Indexes MultiViews SymLinksIfOwnerMatch
+        AllowOverride All
+        Require all granted
+    </Directory>
+    SSLEngine on
+    # Any request to the following paths is passed on to the Unix domain socket\&.
+    ProxyPassMatch 
+      "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive/\&.+)/(\&.*))$" 
+      "unix:/home/oddmu/campaignwiki\&.sock|http://localhost/$1"
+    # /archive only for subdirectories
+    Redirect "/archive/data\&.zip" "/view/archive"
+    # Making changes to the wiki requires authentication\&.
+    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop)/">
+      AuthType Basic
+      AuthName "Password Required"
+      AuthUserFile /home/oddmu/\&.htpasswd
+      Require user admin alex
+      Dav On
+    </LocationMatch>
+    # Making changes to a subdirectory requires different accounts\&.
+    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop|archive)/knochentanz">
+      Require user knochentanz
+    </LocationMatch>
+</VirtualHost>
+.fi
+.RE
+.PP
+In order for this to work, you must enable the mod_dav_fs module.\& This
+automatically enables to the mod_dav module, too.\& Restart the server after
+installing enabling a module.\&
+.PP
+.nf
+.RS 4
+sudo a2enmod mod_dav_fs
+sudo apachectl restart
+.fi
+.RE
+.PP
+Check the permissions for the data directory.\& If the Oddmu service uses the
+"oddmu" user and Apache uses the "www-data" user, you could add the data
+directory to the "www-data" group and give it write permissions:
+.PP
+.nf
+.RS 4
+sudo chown oddmu:www-data /home/alex/campaignwiki\&.org/data/knochentanz
+sudo chmod g+w /home/alex/campaignwiki\&.org/data/knochentanz
+.fi
+.RE
+.PP
+.SH EXAMPLES
+.PP
+Web-DAV clients are often implemented such that they only work with servers that
+exactly match their assumptions.\& If you'\&re trying to use \fIgvfs\fR(7), the Windows
+File Explorer or the macOS Finder to edit Oddmu pages using Web-DAV, you'\&re on
+your own.\& Sometimes it works.\& I'\&ve used Nemo 5.\&6.\&4 to connect to the server and
+edited files using gedit 44.\&2.\& But I'\&ve used other file managers and other
+editors with WebDAV support and they didn'\&t work very well.\&
+.PP
+On Windows, try third party tools like WinSCP.\&
+.PP
+This section has examples sessions using command-line tools that work.\&
+.PP
+.SS cadaver
+.PP
+Here'\&s how to use \fIcadaver\fR(1).\& The "edit" command uses the editor specified in
+the EDITOR environment variable.\& In this example, that'\&s
+"emacsclient --alternate-editor= ".\&
+.PP
+.nf
+.RS 4
+cadaver https://campaignwiki\&.org/data/knochentanz/
+Authentication required for Password Required on server `campaignwiki\&.org\&':
+Username: knochentanz
+Password: 
+dav:/data/knochentanz/> edit index\&.md
+Locking `index\&.md\&': succeeded\&.
+Downloading `/data/knochentanz/index\&.md\&' to /tmp/cadaver-edit-fHTllt\&.md
+Progress: [=============================>] 100\&.0% of 2725 bytes succeeded\&.
+Running editor: `emacsclient --alternate-editor= /tmp/cadaver-edit-fHTllt\&.md\&'\&.\&.\&.
+Waiting for Emacs\&.\&.\&.
+Changes were made\&.
+Uploading changes to `/data/knochentanz/index\&.md\&'
+Progress: [=============================>] 100\&.0% of 2726 bytes succeeded\&.
+Unlocking `index\&.md\&': succeeded\&.
+.fi
+.RE
+.PP
+.SS curl and hdav
+.PP
+Here'\&s how to use \fIcurl\fR(1) to get the file from the public "/view" location and
+how to use \fIhdav\fR(1) to put the file to the protected "/data" location.\& In this
+example, \fIed\fR(1) is used to append the word "test" to the file.\&
+.PP
+.nf
+.RS 4
+alex@melanobombus ~> curl --output index\&.md https://campaignwiki\&.org/view/knochentanz/index\&.md
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100  2726  100  2726    0     0  36662      0 --:--:-- --:--:-- --:--:-- 37861
+alex@melanobombus ~> ed index\&.md 
+2726
+a
+test
+\&.
+w
+2731
+q
+alex@melanobombus ~> hdav put index\&.md https://campaignwiki\&.org/data/knochentanz/index\&.md --username knochentanz
+hDAV version 1\&.3\&.4, Copyright (C) 2012-2016  Clint Adams
+hDAV comes with ABSOLUTELY NO WARRANTY\&.
+This is free software, and you are welcome to redistribute it
+under certain conditions\&.
+
+Password for knochentanz at URL https://campaignwiki\&.org/data/knochentanz/index\&.md: ********
+.fi
+.RE
+.PP
+.SS davfs2
+.PP
+Here'\&s how to use \fIdavfs2\fR(1) using \fImount\fR(1).\& Now the whole wiki is mounted
+and can be edited like local files.\& In this example, \fIecho\fR(1) and redirection
+is used to append the word "test" to a file.\&
+.PP
+.nf
+.RS 4
+alex@melanobombus ~> mkdir knochentanz
+alex@melanobombus ~> sudo mount -t davfs -o username=knochentanz,uid=alex 
+    https://campaignwiki\&.org/data/knochentanz/ knochentanz/
+  Password:  ********
+alex@melanobombus ~> echo test >> knochentanz/index\&.md
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-apache\fR(5)
+.PP
+"Apache Module mod_dav".\&
+https://httpd.\&apache.\&org/docs/current/mod/mod_dav.\&html
+.PP
+"WinSCP"
+https://winscp.\&net/
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu-webdav.5.txt

@@ -0,0 +1,187 @@
+ODDMU-WEBDAV(5)
+
+# NAME
+
+oddmu-webdav - how to setup Web-DAV using Apache for Oddmu
+
+# DESCRIPTION
+
+With the Apache Web-DAV module enabled, users can mount the wiki as a remote
+file system and manage the files using some other tool. Using the Apache Web-DAV
+module means that the same user accounts can be used as for the regular wiki.
+
+# CONFIGURATION
+
+Consider the "campaignwiki.org" site in the example below. This site offers
+users their own wikis. Thus:
+
+"https://campaignwiki.org/" is a regular website with static files.
+
+"https://campaignwiki.org/view/index" is one of the requests that gets passed to
+a Unix domain socket. See "Socket Activation" in _oddmu_(1).
+
+Some of these actions are protected by basic authentication. A valid user is
+required to make changes to the site. Valid users are "admin" and "alex".
+
+"data" is the Oddmu working directory. WebDAV is turned on for this directory. A
+shortcut has been taken, here: The "data" subdirectory requires authentication
+and offers WebDAV access. The other paths also require authentication and map to
+Oddmu actions. The fact that WebDAV access is "enabled" for the Oddmu actions
+has no effect. The only drawback is that "https://campaignwiki.org/data/" now
+requires authentication even if only used for reading.
+
+"https://campaignwiki.org/view/knochentanz/index" is a separate site called
+"knochentanz". The only valid user is "knochentanz".
+
+Notice how the _archive_ action is not available at the top level, only for
+subdirectories.
+
+```
+MDomain campaignwiki.org
+
+<VirtualHost *:80>
+    ServerName campaignwiki.org
+    Redirect permanent / https://campaignwiki.org/
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerAdmin alex@campaignwiki.org
+    ServerName campaignwiki.org
+    # Static HTML, CSS, JavaScript files and so on are saved here.
+    DocumentRoot /home/alex/campaignwiki.org
+    <Directory /home/alex/campaignwiki.org>
+        Options Indexes MultiViews SymLinksIfOwnerMatch
+        AllowOverride All
+        Require all granted
+    </Directory>
+    SSLEngine on
+    # Any request to the following paths is passed on to the Unix domain socket.
+    ProxyPassMatch \
+      "^/((view|preview|diff|edit|save|add|append|upload|drop|search|archive/.+)/(.*))$" \
+      "unix:/home/oddmu/campaignwiki.sock|http://localhost/$1"
+    # /archive only for subdirectories
+    Redirect "/archive/data.zip" "/view/archive"
+    # Making changes to the wiki requires authentication.
+    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop)/">
+      AuthType Basic
+      AuthName "Password Required"
+      AuthUserFile /home/oddmu/.htpasswd
+      Require user admin alex
+      Dav On
+    </LocationMatch>
+    # Making changes to a subdirectory requires different accounts.
+    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop|archive)/knochentanz">
+      Require user knochentanz
+    </LocationMatch>
+</VirtualHost>
+```
+
+In order for this to work, you must enable the mod_dav_fs module. This
+automatically enables to the mod_dav module, too. Restart the server after
+installing enabling a module.
+
+```
+sudo a2enmod mod_dav_fs
+sudo apachectl restart
+```
+
+Check the permissions for the data directory. If the Oddmu service uses the
+"oddmu" user and Apache uses the "www-data" user, you could add the data
+directory to the "www-data" group and give it write permissions:
+
+```
+sudo chown oddmu:www-data /home/alex/campaignwiki.org/data/knochentanz
+sudo chmod g+w /home/alex/campaignwiki.org/data/knochentanz
+```
+
+# EXAMPLES
+
+Web-DAV clients are often implemented such that they only work with servers that
+exactly match their assumptions. If you're trying to use _gvfs_(7), the Windows
+File Explorer or the macOS Finder to edit Oddmu pages using Web-DAV, you're on
+your own. Sometimes it works. I've used Nemo 5.6.4 to connect to the server and
+edited files using gedit 44.2. But I've used other file managers and other
+editors with WebDAV support and they didn't work very well.
+
+On Windows, try third party tools like WinSCP.
+
+This section has examples sessions using command-line tools that work.
+
+## cadaver
+
+Here's how to use _cadaver_(1). The "edit" command uses the editor specified in
+the EDITOR environment variable. In this example, that's
+"emacsclient --alternate-editor= ".
+
+```
+cadaver https://campaignwiki.org/data/knochentanz/
+Authentication required for Password Required on server `campaignwiki.org':
+Username: knochentanz
+Password: 
+dav:/data/knochentanz/> edit index.md
+Locking `index.md': succeeded.
+Downloading `/data/knochentanz/index.md' to /tmp/cadaver-edit-fHTllt.md
+Progress: [=============================>] 100.0% of 2725 bytes succeeded.
+Running editor: `emacsclient --alternate-editor= /tmp/cadaver-edit-fHTllt.md'...
+Waiting for Emacs...
+Changes were made.
+Uploading changes to `/data/knochentanz/index.md'
+Progress: [=============================>] 100.0% of 2726 bytes succeeded.
+Unlocking `index.md': succeeded.
+```
+
+## curl and hdav
+
+Here's how to use _curl_(1) to get the file from the public "/view" location and
+how to use _hdav_(1) to put the file to the protected "/data" location. In this
+example, _ed_(1) is used to append the word "test" to the file.
+
+```
+alex@melanobombus ~> curl --output index.md https://campaignwiki.org/view/knochentanz/index.md
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100  2726  100  2726    0     0  36662      0 --:--:-- --:--:-- --:--:-- 37861
+alex@melanobombus ~> ed index.md 
+2726
+a
+test
+.
+w
+2731
+q
+alex@melanobombus ~> hdav put index.md https://campaignwiki.org/data/knochentanz/index.md --username knochentanz
+hDAV version 1.3.4, Copyright (C) 2012-2016  Clint Adams
+hDAV comes with ABSOLUTELY NO WARRANTY.
+This is free software, and you are welcome to redistribute it
+under certain conditions.
+
+Password for knochentanz at URL https://campaignwiki.org/data/knochentanz/index.md: ********
+```
+
+## davfs2
+
+Here's how to use _davfs2_(1) using _mount_(1). Now the whole wiki is mounted
+and can be edited like local files. In this example, _echo_(1) and redirection
+is used to append the word "test" to a file.
+
+```
+alex@melanobombus ~> mkdir knochentanz
+alex@melanobombus ~> sudo mount -t davfs -o username=knochentanz,uid=alex \
+    https://campaignwiki.org/data/knochentanz/ knochentanz/
+  Password:  ********
+alex@melanobombus ~> echo test >> knochentanz/index.md
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-apache_(5)
+
+"Apache Module mod_dav".
+https://httpd.apache.org/docs/current/mod/mod_dav.html
+
+"WinSCP"
+https://winscp.net/
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu.1

@@ -0,0 +1,419 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU" "1" "2025-08-09"
+.PP
+.SH NAME
+.PP
+oddmu - a wiki server
+.PP
+Oddmu is sometimes written Oddμ because μ is the letter mu.\&
+.PP
+.SH SYNOPSIS
+.PP
+\fBoddmu\fR
+.PP
+\fBoddmu\fR \fIsubcommand\fR [\fIarguments\fR.\&.\&.\&]
+.PP
+.SH DESCRIPTION
+.PP
+Oddmu can be used as a static site generator, turning Markdown files into HTML
+files, or it can be used as a public or a private wiki server.\& If it runs as a
+public wiki server, a regular webserver should be used as reverse proxy.\&
+.PP
+Run Oddmu without any arguments to serve the current working directory as a wiki
+on port 8080.\& Point your browser to http://localhost:8080/ to use it.\& This
+redirects you to http://localhost:8080/view/index – the first page you'\&ll
+create, most likely.\&
+.PP
+See \fIoddmu\fR(5) for details about the page formatting.\&
+.PP
+If you request a page that doesn'\&t exist, Oddmu tries to find a matching
+Markdown file by appending the extension ".\&md" to the page name.\& In the example
+above, the page name requested is "index" and the file name Oddmu tries to read
+is "index.\&md".\& If no such file exists, Oddmu offers you to create the page.\&
+.PP
+If your files don'\&t provide their own title ("# title"), the file name (without
+".\&md") is used for the page title.\&
+.PP
+Every file can be viewed as feed by using the extension ".\&rss".\& The
+feed items are based on links in bullet lists using the asterix
+("*").\&
+.PP
+Subdirectories are created as necessary.\&
+.PP
+The wiki knows the following actions for a given page name and (optional)
+directory:
+.PP
+.PD 0
+.IP \(bu 4
+\fI/\fR redirects to /view/index
+.IP \(bu 4
+\fI/view/dir/\fR redirects to /view/dir/index
+.IP \(bu 4
+\fI/view/dir/name\fR shows a page
+.IP \(bu 4
+\fI/view/dir/name.\&md\fR shows the source text of a page
+.IP \(bu 4
+\fI/view/dir/name.\&rss\fR shows  the RSS feed for the pages linked
+.IP \(bu 4
+\fI/diff/dir/name\fR shows the last change to a page
+.IP \(bu 4
+\fI/edit/dir/name\fR shows a form to edit a page
+.IP \(bu 4
+\fI/preview/dir/name\fR shows a preview of a page edit and the form to edit it
+.IP \(bu 4
+\fI/save/dir/name\fR saves an edit
+.IP \(bu 4
+\fI/add/dir/name\fR shows a form to add to a page
+.IP \(bu 4
+\fI/append/dir/name\fR appends an addition to a page
+.IP \(bu 4
+\fI/upload/dir/name\fR shows a form to upload a file
+.IP \(bu 4
+\fI/drop/dir/name\fR saves an upload
+.IP \(bu 4
+\fI/search/dir/?\&q=term\fR to search for a term
+.IP \(bu 4
+\fI/archive/dir/name.\&zip\fR to download a zip file of a directory
+.PD
+.PP
+When calling the \fIsave\fR and \fIappend\fR action, the page name is taken from the URL
+path and the page content is taken from the \fIbody\fR form parameter.\& To
+illustrate, here'\&s how to edit the "welcome" page using \fIcurl\fR:
+.PP
+.nf
+.RS 4
+curl --form body="Did you bring a towel?" 
+  http://localhost:8080/save/welcome
+.fi
+.RE
+.PP
+When calling the \fIdrop\fR action, the query parameters used are \fIname\fR for the
+target filename and \fIfile\fR for the file to upload.\& If the query parameter
+\fImaxwidth\fR is set, an attempt is made to decode and resize the image.\& JPG, PNG,
+WEBP and HEIC files can be decoded.\& Only JPG and PNG files can be encoded,
+however.\& If the target name ends in \fI.\&jpg\fR, the \fIquality\fR query parameter is
+also taken into account.\& To upload some thumbnails:
+.PP
+.nf
+.RS 4
+for f in *\&.jpg; do
+  curl --form name="$f" --form file=@"$f" --form maxwidth=100 
+    http://localhost:8080/drop/
+done
+.fi
+.RE
+.PP
+When calling the \fIsearch\fR action, the search terms are taken from the query
+parameter \fIq\fR.\&
+.PP
+.nf
+.RS 4
+curl \&'http://localhost:8080/search/?q=towel\&'
+.fi
+.RE
+.PP
+The page name to act upon is optionally taken from the query parameter \fIid\fR.\& In
+this case, the directory must also be part of the query parameter and not of the
+URL path.\&
+.PP
+.nf
+.RS 4
+curl \&'http://localhost:8080/view/?id=man/oddmu\&.1\&.txt\&'
+.fi
+.RE
+.PP
+The base name for the \fIarchive\fR action is used by the browser to save the
+downloaded file.\& For Oddmu, only the directory is important.\& The following zips
+the \fIman\fR directory and saves it as \fIman.\&zip\fR.\&
+.PP
+.nf
+.RS 4
+curl --remote-name \&'http://localhost:8080/archive/man/man\&.zip
+.fi
+.RE
+.PP
+.SH CONFIGURATION
+.PP
+The template files are the HTML files in the working directory.\& Please change
+these templates!\&
+.PP
+The first change you should make is to replace the name and email address in the
+footer of \fIview.\&html\fR.\& Look for "Your Name" and "example.\&org".\&
+.PP
+The second change you should make is to replace the name, email address and
+domain name in "feed.\&html".\& Look for "Your Name" and "example.\&org".\&
+.PP
+See \fIoddmu-templates\fR(5) for more.\&
+.PP
+.SH ENVIRONMENT
+.PP
+You can change the port served by setting the ODDMU_PORT environment variable.\&
+.PP
+You can change the address served by setting the ODDMU_ADDRESS environment
+variable to either an IPv4 address or an IPv6 address.\& If ODDMU_ADDRESS is
+unset, then the program listens on all available unicast addresses, both IPv4
+and IPv6.\& Here are a few example addresses:
+.PP
+.nf
+.RS 4
+ODDMU_ADDRESS=127\&.0\&.0\&.1      # The loopback IPv4 address\&.
+ODDMU_ADDRESS=2001:db8::3:1  # An IPv6 address\&.
+.fi
+.RE
+.PP
+See the Socket Activation section for an alternative method of listening which
+supports Unix-domain sockets.\&
+.PP
+In order to limit language-detection to the languages you actually use, set the
+environment variable ODDMU_LANGUAGES to a comma-separated list of ISO 639-1
+codes, e.\&g.\& "en" or "en,de,fr,pt".\&
+.PP
+You can enable webfinger to link fediverse accounts to their correct profile
+pages by setting ODDMU_WEBFINGER to "1".\& See \fIoddmu\fR(5).\&
+.PP
+If you use secret subdirectories, you cannot rely on the web server to hide
+those pages because some actions such as searching and archiving include
+subdirectories.\& They act upon a whole tree of pages, not just a single page.\& The
+ODDMU_FILTER can be used to exclude subdirectories from such tree actions.\& See
+\fIoddmu-filter\fR(7) and \fIoddmu-apache\fR(5).\&
+.PP
+.SH Socket Activation
+.PP
+Instead of specifying ODDMU_ADDRESS or ODDMU_PORT, you can start the service
+through socket activation.\& The advantage of this method is that you can use a
+Unix-domain socket instead of a TCP socket, and the permissions and ownership of
+the socket are set before the program starts.\& See \fIoddmu.\&service\fR(5),
+\fIoddmu-apache\fR(5) and \fIoddmu-nginx\fR(5) for an example of how to use socket
+activation with a Unix-domain socket under systemd and Apache.\&
+.PP
+.SH SECURITY
+.PP
+If the machine you are running Oddmu on is accessible from the Internet, you
+must secure your installation.\& The best way to do this is use a regular web
+server as a reverse proxy.\& See \fIoddmu-apache\fR(5) and \fIoddmu-nginx\fR(5) for
+example configurations.\&
+.PP
+Oddmu assumes that all the users that can edit pages or upload files are trusted
+users and therefore their content is trusted.\& Oddmu does not perform HTML
+sanitization!\&
+.PP
+For an extra dose of security, consider using a Unix-domain socket.\&
+.PP
+.SH OPTIONS
+.PP
+Oddmu can be run on the command-line using various subcommands.\&
+.PP
+.PD 0
+.IP \(bu 4
+to generate the HTML for a single page, see \fIoddmu-html\fR(1)
+.IP \(bu 4
+to generate the HTML for the entire site, using Oddmu as a static site
+generator, see \fIoddmu-static\fR(1)
+.IP \(bu 4
+to export the HTML for the entire site in one big feed, see \fIoddmu-export\fR(1)
+.IP \(bu 4
+to emulate a search of the files, see \fIoddmu-search\fR(1); to understand how the
+search engine indexes pages and how it sorts and scores results, see
+\fIoddmu-search\fR(7)
+.IP \(bu 4
+to search a regular expression and replace it across all files, see
+\fIoddmu-replace\fR(1)
+.IP \(bu 4
+to learn what the most popular hashtags are, see \fIoddmu-hashtags\fR(1)
+.IP \(bu 4
+to print a table of contents (TOC) for a page, see \fIoddmu-toc\fR(1)
+.IP \(bu 4
+to list the outgoing links for a page, see \fIoddmu-links\fR(1)
+.IP \(bu 4
+to find missing pages (local links that go nowhere), see \fIoddmu-missing\fR(1)
+.IP \(bu 4
+to list all the pages with name and title, see \fIoddmu-list\fR(1)
+.IP \(bu 4
+to add links to changes, index and hashtag pages to pages you created locally,
+see \fIoddmu-notify\fR(1)
+.IP \(bu 4
+to display build information, see \fIoddmu-version\fR(1)
+.PD
+.PP
+.SH EXAMPLES
+.PP
+When saving a page, the page name is take from the URL and the page content is
+taken from the "body" form parameter.\& To illustrate, here'\&s how to edit a page
+using \fIcurl\fR(1):
+.PP
+.nf
+.RS 4
+curl --form body="Did you bring a towel?" 
+  http://localhost:8080/save/welcome
+.fi
+.RE
+.PP
+To compute the space used by your setup, use regular tools:
+.PP
+.nf
+.RS 4
+du --exclude=\&'*/.*\&' --exclude \&'*~\&' --block-size=M
+.fi
+.RE
+.PP
+.SH DESIGN
+.PP
+This is a minimal wiki.\& There is no version history.\& It'\&s well suited as a
+\fIsecondary\fR medium: collaboration and conversation happens elsewhere, in chat,
+on social media.\& The wiki serves as the text repository that results from these
+discussions.\&
+.PP
+The idea is that the webserver handles as many tasks as possible.\& It logs
+requests, does rate limiting, handles encryption, gets the certificates, and so
+on.\& The web server acts as a reverse proxy and the wiki ends up being a content
+management system with almost no structure – or endless malleability, depending
+on your point of view.\& See \fIoddmu-apache\fR(5).\&
+.PP
+.SH NOTES
+.PP
+Page names are filenames with ".\&md" appended.\& If your filesystem cannot handle
+it, it can'\&t be a page name.\& Filenames can contain slashes and Oddmu creates
+subdirectories as necessary.\&
+.PP
+Files may not end with a tilde ('\&~'\&) – these are backup files.\& When saving pages
+and file uploads, the old file is renamed to the backup file unless the backup
+file is less than an hour old, thus collapsing all edits made in an hour into a
+single diff when comparing backup and current version.\& The backup also gets an
+updated timestamp so that subsequent edits don'\&t immediately overwrite it.\&
+.PP
+The \fBindex\fR page is the default page.\& People visiting the "root" of the site are
+redirected to "/view/index".\&
+.PP
+The \fBchanges\fR page is where links to new and changed files are added.\& As an
+author, you can prevent this from happening by deselecting the checkbox "Add
+link to the list of changes.\&" The changes page can be edited like every other
+page, so it'\&s easy to undo mistakes.\&
+.PP
+Links on the changes page are grouped by date.\& When new links are added, the
+current date of the machine Oddmu is running on is used.\& If a link already
+exists on the changes page, it is moved up to the current date.\& If that leaves
+an old date without any links, that date heading is removed.\&
+.PP
+If you want to link to the changes page, you need to do this yourself.\& Add a
+link from the index, for example.\& The "view.\&html" template currently doesn'\&t do
+it.\& See \fIoddmu-templates\fR(5) if you want to add the link to the template.\&
+.PP
+A page whose name starts with an ISO date (YYYY-MM-DD, e.\&g.\& "2023-10-28") is
+called a \fBblog\fR page.\& When creating or editing blog pages, links to it are added
+from other pages.\&
+.PP
+If the blog page name starts with the current year, a link is created from the
+index page back to the blog page being created or edited.\& Again, you can prevent
+this from happening by deselecting the checkbox "Add link to the list of
+changes.\&" The index page can be edited like every other page, so it'\&s easy to
+undo mistakes.\&
+.PP
+For every \fBhashtag\fR used, another link might be created.\& If a page named like
+the hashtag exists, a backlink is added to it, linking to the new or edited blog
+page.\&
+.PP
+If a link to the new or edited blog page already exists but it'\&s title is no
+longer correct, it is updated.\&
+.PP
+New links added for blog pages are added at the top of the first unnumbered list
+using the asterisk ('\&*'\&).\& If no such list exists, a new one is started at the
+bottom of the page.\& This allows you to have a different unnumbered list further
+up on the page, as long as it uses the minus for items ('\&-'\&).\&
+.PP
+Changes made locally do not create any links on the changes page, the index page
+or on any hashtag pages.\& See \fIoddmu-notify\fR(1) for a way to add the necessary
+links to the changes page and possibly to the index and hashtag pages.\&
+.PP
+A hashtag consists of a number sign ('\&#'\&) followed by Unicode letters, numbers
+or the underscore ('\&_'\&).\& Thus, a hashtag ends with punctuation or whitespace.\&
+.PP
+The page names, titles and hashtags are loaded into memory when the server
+starts.\& If you have a lot of pages, this takes a lot of memory.\&
+.PP
+Oddmu watches the working directory and any subdirectories for changes made
+directly.\& Thus, in theory, it'\&s not necessary to restart it after making such
+changes.\&
+.PP
+You cannot edit uploaded files.\& If you upload a file called "hello.\&txt" and
+attempt to edit it by using "/edit/hello.\&txt" you create a page with the name
+"hello.\&txt.\&md" instead.\&
+.PP
+In order to delete uploaded files via the web, create an empty file and upload
+it.\& In order to delete a wiki page, save an empty page.\&
+.PP
+Note that some HTML file names are special: they act as templates.\& See
+\fIoddmu-templates\fR(5) for their names and their use.\&
+.PP
+.SH SEE ALSO
+.PP
+.PD 0
+.IP \(bu 4
+\fIoddmu\fR(5), about the markup syntax and how feeds are generated based on link
+lists
+.IP \(bu 4
+\fIoddmu-releases\fR(7), on what features are part of the latest release
+.IP \(bu 4
+\fIoddmu-filter\fR(7), on how to treat subdirectories as separate sites
+.IP \(bu 4
+\fIoddmu-search\fR(7), on how search works
+.IP \(bu 4
+\fIoddmu-templates\fR(5), on how to write the HTML templates
+.PD
+.PP
+If you run Oddmu as a web server:
+.PP
+.PD 0
+.IP \(bu 4
+\fIoddmu-apache\fR(5), on how to set up Apache as a reverse proxy
+.IP \(bu 4
+\fIoddmu-nginx\fR(5), on how to set up freenginx as a reverse proxy
+.IP \(bu 4
+\fIoddmu-webdav\fR(5), on how to set up Apache as a Web-DAV server
+.IP \(bu 4
+\fIoddmu.\&service\fR(5), on how to run the service under systemd
+.PD
+.PP
+If you run Oddmu as a static site generator or pages offline and sync them with
+Oddmu running as a webserver:
+.PP
+.PD 0
+.IP \(bu 4
+\fIoddmu-hashtags\fR(1), on working with hashtags
+.IP \(bu 4
+\fIoddmu-html\fR(1), on how to render a page
+.IP \(bu 4
+\fIoddmu-list\fR(1), on how to list pages and titles
+.IP \(bu 4
+\fIoddmu-links\fR(1), on how to list the outgoing links for a page
+.IP \(bu 4
+\fIoddmu-missing\fR(1), on how to find broken local links
+.IP \(bu 4
+\fIoddmu-notify\fR(1), on updating index, changes and hashtag pages
+.IP \(bu 4
+\fIoddmu-replace\fR(1), on how to search and replace text
+.IP \(bu 4
+\fIoddmu-search\fR(1), on how to run a search
+.IP \(bu 4
+\fIoddmu-static\fR(1), on generating a static site
+.IP \(bu 4
+\fIoddmu-toc\fR(1), on how to list the table of contents (toc) a page
+.IP \(bu 4
+\fIoddmu-version\fR(1), on how to get all the build information from the binary
+.PD
+.PP
+If you want to stop using Oddmu:
+.PP
+.PD 0
+.IP \(bu 4
+\fIoddmu-export\fR(1), on how to export all the files as one big RSS file
+.PD
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu.1.txt

@@ -0,0 +1,336 @@
+ODDMU(1)
+
+# NAME
+
+oddmu - a wiki server
+
+Oddmu is sometimes written Oddμ because μ is the letter mu.
+
+# SYNOPSIS
+
+*oddmu*
+
+*oddmu* _subcommand_ [_arguments_...]
+
+# DESCRIPTION
+
+Oddmu can be used as a static site generator, turning Markdown files into HTML
+files, or it can be used as a public or a private wiki server. If it runs as a
+public wiki server, a regular webserver should be used as reverse proxy.
+
+Run Oddmu without any arguments to serve the current working directory as a wiki
+on port 8080. Point your browser to http://localhost:8080/ to use it. This
+redirects you to http://localhost:8080/view/index – the first page you'll
+create, most likely.
+
+See _oddmu_(5) for details about the page formatting.
+
+If you request a page that doesn't exist, Oddmu tries to find a matching
+Markdown file by appending the extension ".md" to the page name. In the example
+above, the page name requested is "index" and the file name Oddmu tries to read
+is "index.md". If no such file exists, Oddmu offers you to create the page.
+
+If your files don't provide their own title ("# title"), the file name (without
+".md") is used for the page title.
+
+Every file can be viewed as feed by using the extension ".rss". The
+feed items are based on links in bullet lists using the asterix
+("\*").
+
+Subdirectories are created as necessary.
+
+The wiki knows the following actions for a given page name and (optional)
+directory:
+
+- _/_ redirects to /view/index
+- _/view/dir/_ redirects to /view/dir/index
+- _/view/dir/name_ shows a page
+- _/view/dir/name.md_ shows the source text of a page
+- _/view/dir/name.rss_ shows  the RSS feed for the pages linked
+- _/diff/dir/name_ shows the last change to a page
+- _/edit/dir/name_ shows a form to edit a page
+- _/preview/dir/name_ shows a preview of a page edit and the form to edit it
+- _/save/dir/name_ saves an edit
+- _/add/dir/name_ shows a form to add to a page
+- _/append/dir/name_ appends an addition to a page
+- _/upload/dir/name_ shows a form to upload a file
+- _/drop/dir/name_ saves an upload
+- _/search/dir/?q=term_ to search for a term
+- _/archive/dir/name.zip_ to download a zip file of a directory
+
+When calling the _save_ and _append_ action, the page name is taken from the URL
+path and the page content is taken from the _body_ form parameter. To
+illustrate, here's how to edit the "welcome" page using _curl_:
+
+```
+curl --form body="Did you bring a towel?" \
+  http://localhost:8080/save/welcome
+```
+
+When calling the _drop_ action, the query parameters used are _name_ for the
+target filename and _file_ for the file to upload. If the query parameter
+_maxwidth_ is set, an attempt is made to decode and resize the image. JPG, PNG,
+WEBP and HEIC files can be decoded. Only JPG and PNG files can be encoded,
+however. If the target name ends in _.jpg_, the _quality_ query parameter is
+also taken into account. To upload some thumbnails:
+
+```
+for f in *.jpg; do
+  curl --form name="$f" --form file=@"$f" --form maxwidth=100 \
+    http://localhost:8080/drop/
+done
+```
+
+When calling the _search_ action, the search terms are taken from the query
+parameter _q_.
+
+```
+curl 'http://localhost:8080/search/?q=towel'
+```
+
+The page name to act upon is optionally taken from the query parameter _id_. In
+this case, the directory must also be part of the query parameter and not of the
+URL path.
+
+```
+curl 'http://localhost:8080/view/?id=man/oddmu.1.txt'
+```
+
+The base name for the _archive_ action is used by the browser to save the
+downloaded file. For Oddmu, only the directory is important. The following zips
+the _man_ directory and saves it as _man.zip_.
+
+```
+curl --remote-name 'http://localhost:8080/archive/man/man.zip
+```
+
+# CONFIGURATION
+
+The template files are the HTML files in the working directory. Please change
+these templates!
+
+The first change you should make is to replace the name and email address in the
+footer of _view.html_. Look for "Your Name" and "example.org".
+
+The second change you should make is to replace the name, email address and
+domain name in "feed.html". Look for "Your Name" and "example.org".
+
+See _oddmu-templates_(5) for more.
+
+# ENVIRONMENT
+
+You can change the port served by setting the ODDMU_PORT environment variable.
+
+You can change the address served by setting the ODDMU_ADDRESS environment
+variable to either an IPv4 address or an IPv6 address. If ODDMU_ADDRESS is
+unset, then the program listens on all available unicast addresses, both IPv4
+and IPv6. Here are a few example addresses:
+
+```
+ODDMU_ADDRESS=127.0.0.1      # The loopback IPv4 address.
+ODDMU_ADDRESS=2001:db8::3:1  # An IPv6 address.
+```
+
+See the Socket Activation section for an alternative method of listening which
+supports Unix-domain sockets.
+
+In order to limit language-detection to the languages you actually use, set the
+environment variable ODDMU_LANGUAGES to a comma-separated list of ISO 639-1
+codes, e.g. "en" or "en,de,fr,pt".
+
+You can enable webfinger to link fediverse accounts to their correct profile
+pages by setting ODDMU_WEBFINGER to "1". See _oddmu_(5).
+
+If you use secret subdirectories, you cannot rely on the web server to hide
+those pages because some actions such as searching and archiving include
+subdirectories. They act upon a whole tree of pages, not just a single page. The
+ODDMU_FILTER can be used to exclude subdirectories from such tree actions. See
+_oddmu-filter_(7) and _oddmu-apache_(5).
+
+# Socket Activation
+
+Instead of specifying ODDMU_ADDRESS or ODDMU_PORT, you can start the service
+through socket activation. The advantage of this method is that you can use a
+Unix-domain socket instead of a TCP socket, and the permissions and ownership of
+the socket are set before the program starts. See _oddmu.service_(5),
+_oddmu-apache_(5) and _oddmu-nginx_(5) for an example of how to use socket
+activation with a Unix-domain socket under systemd and Apache.
+
+# SECURITY
+
+If the machine you are running Oddmu on is accessible from the Internet, you
+must secure your installation. The best way to do this is use a regular web
+server as a reverse proxy. See _oddmu-apache_(5) and _oddmu-nginx_(5) for
+example configurations.
+
+Oddmu assumes that all the users that can edit pages or upload files are trusted
+users and therefore their content is trusted. Oddmu does not perform HTML
+sanitization!
+
+For an extra dose of security, consider using a Unix-domain socket.
+
+# OPTIONS
+
+Oddmu can be run on the command-line using various subcommands.
+
+- to generate the HTML for a single page, see _oddmu-html_(1)
+- to generate the HTML for the entire site, using Oddmu as a static site
+  generator, see _oddmu-static_(1)
+- to export the HTML for the entire site in one big feed, see _oddmu-export_(1)
+- to emulate a search of the files, see _oddmu-search_(1); to understand how the
+  search engine indexes pages and how it sorts and scores results, see
+  _oddmu-search_(7)
+- to search a regular expression and replace it across all files, see
+  _oddmu-replace_(1)
+- to learn what the most popular hashtags are, see _oddmu-hashtags_(1)
+- to print a table of contents (TOC) for a page, see _oddmu-toc_(1)
+- to list the outgoing links for a page, see _oddmu-links_(1)
+- to find missing pages (local links that go nowhere), see _oddmu-missing_(1)
+- to list all the pages with name and title, see _oddmu-list_(1)
+- to add links to changes, index and hashtag pages to pages you created locally,
+  see _oddmu-notify_(1)
+- to display build information, see _oddmu-version_(1)
+
+# EXAMPLES
+
+When saving a page, the page name is take from the URL and the page content is
+taken from the "body" form parameter. To illustrate, here's how to edit a page
+using _curl_(1):
+
+```
+curl --form body="Did you bring a towel?" \
+  http://localhost:8080/save/welcome
+```
+
+To compute the space used by your setup, use regular tools:
+
+```
+du --exclude='*/\.*' --exclude '*~' --block-size=M
+```
+
+# DESIGN
+
+This is a minimal wiki. There is no version history. It's well suited as a
+_secondary_ medium: collaboration and conversation happens elsewhere, in chat,
+on social media. The wiki serves as the text repository that results from these
+discussions.
+
+The idea is that the webserver handles as many tasks as possible. It logs
+requests, does rate limiting, handles encryption, gets the certificates, and so
+on. The web server acts as a reverse proxy and the wiki ends up being a content
+management system with almost no structure – or endless malleability, depending
+on your point of view. See _oddmu-apache_(5).
+
+# NOTES
+
+Page names are filenames with ".md" appended. If your filesystem cannot handle
+it, it can't be a page name. Filenames can contain slashes and Oddmu creates
+subdirectories as necessary.
+
+Files may not end with a tilde ('~') – these are backup files. When saving pages
+and file uploads, the old file is renamed to the backup file unless the backup
+file is less than an hour old, thus collapsing all edits made in an hour into a
+single diff when comparing backup and current version. The backup also gets an
+updated timestamp so that subsequent edits don't immediately overwrite it.
+
+The *index* page is the default page. People visiting the "root" of the site are
+redirected to "/view/index".
+
+The *changes* page is where links to new and changed files are added. As an
+author, you can prevent this from happening by deselecting the checkbox "Add
+link to the list of changes." The changes page can be edited like every other
+page, so it's easy to undo mistakes.
+
+Links on the changes page are grouped by date. When new links are added, the
+current date of the machine Oddmu is running on is used. If a link already
+exists on the changes page, it is moved up to the current date. If that leaves
+an old date without any links, that date heading is removed.
+
+If you want to link to the changes page, you need to do this yourself. Add a
+link from the index, for example. The "view.html" template currently doesn't do
+it. See _oddmu-templates_(5) if you want to add the link to the template.
+
+A page whose name starts with an ISO date (YYYY-MM-DD, e.g. "2023-10-28") is
+called a *blog* page. When creating or editing blog pages, links to it are added
+from other pages.
+
+If the blog page name starts with the current year, a link is created from the
+index page back to the blog page being created or edited. Again, you can prevent
+this from happening by deselecting the checkbox "Add link to the list of
+changes." The index page can be edited like every other page, so it's easy to
+undo mistakes.
+
+For every *hashtag* used, another link might be created. If a page named like
+the hashtag exists, a backlink is added to it, linking to the new or edited blog
+page.
+
+If a link to the new or edited blog page already exists but it's title is no
+longer correct, it is updated.
+
+New links added for blog pages are added at the top of the first unnumbered list
+using the asterisk ('\*'). If no such list exists, a new one is started at the
+bottom of the page. This allows you to have a different unnumbered list further
+up on the page, as long as it uses the minus for items ('-').
+
+Changes made locally do not create any links on the changes page, the index page
+or on any hashtag pages. See _oddmu-notify_(1) for a way to add the necessary
+links to the changes page and possibly to the index and hashtag pages.
+
+A hashtag consists of a number sign ('#') followed by Unicode letters, numbers
+or the underscore ('\_'). Thus, a hashtag ends with punctuation or whitespace.
+
+The page names, titles and hashtags are loaded into memory when the server
+starts. If you have a lot of pages, this takes a lot of memory.
+
+Oddmu watches the working directory and any subdirectories for changes made
+directly. Thus, in theory, it's not necessary to restart it after making such
+changes.
+
+You cannot edit uploaded files. If you upload a file called "hello.txt" and
+attempt to edit it by using "/edit/hello.txt" you create a page with the name
+"hello.txt.md" instead.
+
+In order to delete uploaded files via the web, create an empty file and upload
+it. In order to delete a wiki page, save an empty page.
+
+Note that some HTML file names are special: they act as templates. See
+_oddmu-templates_(5) for their names and their use.
+
+# SEE ALSO
+
+- _oddmu_(5), about the markup syntax and how feeds are generated based on link
+  lists
+- _oddmu-releases_(7), on what features are part of the latest release
+- _oddmu-filter_(7), on how to treat subdirectories as separate sites
+- _oddmu-search_(7), on how search works
+- _oddmu-templates_(5), on how to write the HTML templates
+
+If you run Oddmu as a web server:
+
+- _oddmu-apache_(5), on how to set up Apache as a reverse proxy
+- _oddmu-nginx_(5), on how to set up freenginx as a reverse proxy
+- _oddmu-webdav_(5), on how to set up Apache as a Web-DAV server
+- _oddmu.service_(5), on how to run the service under systemd
+
+If you run Oddmu as a static site generator or pages offline and sync them with
+Oddmu running as a webserver:
+
+- _oddmu-hashtags_(1), on working with hashtags
+- _oddmu-html_(1), on how to render a page
+- _oddmu-list_(1), on how to list pages and titles
+- _oddmu-links_(1), on how to list the outgoing links for a page
+- _oddmu-missing_(1), on how to find broken local links
+- _oddmu-notify_(1), on updating index, changes and hashtag pages
+- _oddmu-replace_(1), on how to search and replace text
+- _oddmu-search_(1), on how to run a search
+- _oddmu-static_(1), on generating a static site
+- _oddmu-toc_(1), on how to list the table of contents (toc) a page
+- _oddmu-version_(1), on how to get all the build information from the binary
+
+If you want to stop using Oddmu:
+
+- _oddmu-export_(1), on how to export all the files as one big RSS file
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu.5

@@ -0,0 +1,211 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU" "5" "2025-03-05" "File Formats Manual"
+.PP
+.SH NAME
+.PP
+oddmu - text formatting of wiki pages
+.PP
+.SH SYNTAX
+.PP
+The wiki pages are UTF-8 encoded Markdown files (with the ".\&md" extension).\&
+Oddmu links are regular Markdown links to page names (without the ".\&md"
+extension):
+.PP
+.nf
+.RS 4
+[link text](page-name)
+.fi
+.RE
+.PP
+The page name has to be percent-encoded.\& See the section "Percent Encoding".\&
+.PP
+If you link to the actual Markdown file (with the ".\&md" extension), then Oddmu
+serves the Markdown file!\&
+.PP
+There are three Oddμ-specific extensions: local links, hashtags and fediverse
+account links.\& The Markdown library used features some additional extensions,
+most importantly tables and definition lists.\&
+.PP
+.SS Local links
+.PP
+Local links use double square brackets.\& Oddmu does not treat underscores like
+spaces, so "[[like this]]" and "[[like_this]]" link to different destinations
+and are served by different files: "like this.\&md" and "like_this.\&md".\&
+.PP
+.SS Hashtags
+.PP
+Hashtags are single word links to searches for themselves.\& Use the underscore to
+use hashtags consisting of multiple words.\& Hashtags are distinguished from page
+titles because there is no space after the hash.\&
+.PP
+.nf
+.RS 4
+# Example
+
+Text
+
+#Tag #Another_Tag
+.fi
+.RE
+.PP
+When a page containing hashtags is saved, a link to that page is added to every
+page with the same name as the hashtag, if it exists.\& In the example above, if
+the file "Tag.\&md" or the file "Another_Tag.\&md" exists, a link to the Example
+page is added.\&
+.PP
+.SS Tables
+.PP
+A table with footers and a columnspan:
+.PP
+.nf
+.RS 4
+Name    | Age
+--------|------
+Bob     ||
+Alice   | 23
+========|======
+Total   | 23
+.fi
+.RE
+.PP
+.SS Definition lists:
+.PP
+.nf
+.RS 4
+Cat
+: Fluffy animal everyone likes
+
+Internet
+: Vector of transmission for pictures of cats
+.fi
+.RE
+.PP
+.SS Fediverse account links
+.PP
+Fediverse accounts look a bit like an at sign followed by an email address, e.\&g.\&
+"@alex@alexschroeder.\&ch".\& When rendering a page, these turn into a username
+linked to a profile page.\& In this case, "@alex" would be linked to
+"https://alexschroeder.\&ch/users/alex".\&
+.PP
+In many cases, this works as is.\& In reality, however, the link to the profile
+page needs to be retrieved via webfinger.\& Oddμ does that in the background, and
+as soon as the information is available, the actual profile link is used when
+pages are rendered.\& In the example above, the result would be
+"https://social.\&alexschroeder.\&ch/@alex".\&
+.PP
+As this sort of packground network activity is surprising, it is not enabled by
+default.\& Set the environment variable ODDMU_WEBFINGER to "1" in order to enable
+this.\&
+.PP
+.SS Other extensions
+.PP
+The Markdown processor comes with a few extensions:
+.PP
+.PD 0
+.IP \(bu 4
+emphasis markers inside words are ignored
+.IP \(bu 4
+fenced code blocks are supported
+.IP \(bu 4
+autolinking of "naked" URLs are supported
+.IP \(bu 4
+strikethrough using two tildes is supported (~~like this~~)
+.IP \(bu 4
+a space is required between the last # and the text for headings
+.IP \(bu 4
+you can specify an id for headings ({#id})
+.IP \(bu 4
+trailing backslashes turn into line breaks
+.PD
+.PP
+.SH FEEDS
+.PP
+Every file can be viewed as a feed by using the extension ".\&rss".\& The feed items
+are based on links in bullet lists using the asterix ("*").\& The items must
+point to local pages.\& This is why the link may not contain two forward slashes
+("//").\&
+.PP
+Below is an example index page.\& The feed would be "/view/index.\&rss".\& It would
+contain the pages "Arianism", "Donatism" and "Monophysitism" but it would not
+contain the pages "Feed" and "About" since the list items don'\&t start with an
+asterix.\&
+.PP
+.nf
+.RS 4
+# Main Page
+
+Hello and welcome! Here are some important links:
+
+- [Feed](index\&.rss)
+- [About](about)
+
+Recent posts:
+
+* [Arianism](arianism)
+* [Donatism](donatism)
+* [Monophysitism](monophysitism)
+.fi
+.RE
+.PP
+The feed contains at most 10 items, starting at the top.\& Thus, new items must be
+added at the beginning of the list.\&
+.PP
+.SH PERCENT ENCODING
+.PP
+If you use Markdown links to local pages, you must percent-encode the link
+target.\& Any character that is not an "unreserved character" according to RFC
+3986 might need to be encoded.\& The unreserved characters are a-z, A-Z, 0-9, as
+well as the four characters '\&-'\&, '\&_'\&, '\&.\&'\& and '\&~'\&.\&
+.PP
+Percent-encoding means that each character is converted into one or more bytes,
+and each byte is represented as a percent character followed by a hexadecimal
+representation.\&
+.PP
+Realistically, what probably works best is to use a browser.\& If you type
+"http://example.\&org/Alex Schröder" into the address bar, you'\&ll get sent to the
+example domain.\& If you now copy the address and paste it back into a text
+editor, you'\&ll get "http://example.\&org/Alex%20Schr%C3%B6der" and that'\&s how
+you'\&ll learn that the Space is encoded by %20 and that the character '\&ö'\& is
+encoded by %C3%B6.\& To link to the page "Alex Schröder" you would write something
+like this: "[Alex](Alex%20Schr%C3%B6der)".\&
+.PP
+Another thing that'\&s common is that your page name contains a colon.\&
+This is legal.\& The URL parser might still reject it.\& If you run the
+"missing" subcommand, you'\&ll get to see error: "first path segment in
+URL cannot contain colon".\& The solution is to prepend ".\&/"!\&
+.PP
+Example:
+.PP
+.nf
+.RS 4
+[2021-10-15 Re: Mark It Down](2021-10-15_Re:_Mark_It_Down)
+.fi
+.RE
+.PP
+Fixed:
+.PP
+.nf
+.RS 4
+[2021-10-15 Re: Mark It Down](\&./2021-10-15_Re:_Mark_It_Down)
+.fi
+.RE
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-missing\fR(1)
+.PP
+This wiki uses the Go Markdown library.\&
+https://github.\&com/gomarkdown/markdown
+.PP
+For more about percent-encoding, see Wikipedia.\&
+https://en.\&wikipedia.\&org/wiki/Percent-encoding
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu.5.txt

@@ -0,0 +1,181 @@
+ODDMU(5) "File Formats Manual"
+
+# NAME
+
+oddmu - text formatting of wiki pages
+
+# SYNTAX
+
+The wiki pages are UTF-8 encoded Markdown files (with the ".md" extension).
+Oddmu links are regular Markdown links to page names (without the ".md"
+extension):
+
+```
+[link text](page-name)
+```
+
+The page name has to be percent-encoded. See the section "Percent Encoding".
+
+If you link to the actual Markdown file (with the ".md" extension), then Oddmu
+serves the Markdown file!
+
+There are three Oddμ-specific extensions: local links, hashtags and fediverse
+account links. The Markdown library used features some additional extensions,
+most importantly tables and definition lists.
+
+## Local links
+
+Local links use double square brackets. Oddmu does not treat underscores like
+spaces, so "[[like this]]" and "[[like_this]]" link to different destinations
+and are served by different files: "like this.md" and "like_this.md".
+
+## Hashtags
+
+Hashtags are single word links to searches for themselves. Use the underscore to
+use hashtags consisting of multiple words. Hashtags are distinguished from page
+titles because there is no space after the hash.
+
+```
+# Example
+
+Text
+
+#Tag #Another_Tag
+```
+
+When a page containing hashtags is saved, a link to that page is added to every
+page with the same name as the hashtag, if it exists. In the example above, if
+the file "Tag.md" or the file "Another_Tag.md" exists, a link to the Example
+page is added.
+
+## Tables
+
+A table with footers and a columnspan:
+
+```
+Name    | Age
+--------|------
+Bob     ||
+Alice   | 23
+========|======
+Total   | 23
+```
+
+## Definition lists:
+
+```
+Cat
+: Fluffy animal everyone likes
+
+Internet
+: Vector of transmission for pictures of cats
+```
+
+## Fediverse account links
+
+Fediverse accounts look a bit like an at sign followed by an email address, e.g.
+"\@alex@alexschroeder.ch". When rendering a page, these turn into a username
+linked to a profile page. In this case, "@alex" would be linked to
+"https://alexschroeder.ch/users/alex".
+
+In many cases, this works as is. In reality, however, the link to the profile
+page needs to be retrieved via webfinger. Oddμ does that in the background, and
+as soon as the information is available, the actual profile link is used when
+pages are rendered. In the example above, the result would be
+"https://social.alexschroeder.ch/@alex".
+
+As this sort of packground network activity is surprising, it is not enabled by
+default. Set the environment variable ODDMU_WEBFINGER to "1" in order to enable
+this.
+
+## Other extensions
+
+The Markdown processor comes with a few extensions:
+
+- emphasis markers inside words are ignored
+- fenced code blocks are supported
+- autolinking of "naked" URLs are supported
+- strikethrough using two tildes is supported (~~like this~~)
+- a space is required between the last # and the text for headings
+- you can specify an id for headings ({#id})
+- trailing backslashes turn into line breaks
+
+# FEEDS
+
+Every file can be viewed as a feed by using the extension ".rss". The feed items
+are based on links in bullet lists using the asterix ("\*"). The items must
+point to local pages. This is why the link may not contain two forward slashes
+("//").
+
+Below is an example index page. The feed would be "/view/index.rss". It would
+contain the pages "Arianism", "Donatism" and "Monophysitism" but it would not
+contain the pages "Feed" and "About" since the list items don't start with an
+asterix.
+
+```
+# Main Page
+
+Hello and welcome! Here are some important links:
+
+- [Feed](index.rss)
+- [About](about)
+
+Recent posts:
+
+* [Arianism](arianism)
+* [Donatism](donatism)
+* [Monophysitism](monophysitism)
+```
+
+The feed contains at most 10 items, starting at the top. Thus, new items must be
+added at the beginning of the list.
+
+# PERCENT ENCODING
+
+If you use Markdown links to local pages, you must percent-encode the link
+target. Any character that is not an "unreserved character" according to RFC
+3986 might need to be encoded. The unreserved characters are a-z, A-Z, 0-9, as
+well as the four characters '-', '\_', '.' and '~'.
+
+Percent-encoding means that each character is converted into one or more bytes,
+and each byte is represented as a percent character followed by a hexadecimal
+representation.
+
+Realistically, what probably works best is to use a browser. If you type
+"http://example.org/Alex Schröder" into the address bar, you'll get sent to the
+example domain. If you now copy the address and paste it back into a text
+editor, you'll get "http://example.org/Alex%20Schr%C3%B6der" and that's how
+you'll learn that the Space is encoded by %20 and that the character 'ö' is
+encoded by %C3%B6. To link to the page "Alex Schröder" you would write something
+like this: "[Alex](Alex%20Schr%C3%B6der)".
+
+Another thing that's common is that your page name contains a colon.
+This is legal. The URL parser might still reject it. If you run the
+"missing" subcommand, you'll get to see error: "first path segment in
+URL cannot contain colon". The solution is to prepend "./"!
+
+Example:
+
+```
+[2021-10-15 Re: Mark It Down](2021-10-15_Re:_Mark_It_Down)
+```
+
+Fixed:
+
+```
+[2021-10-15 Re: Mark It Down](./2021-10-15_Re:_Mark_It_Down)
+```
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-missing_(1)
+
+This wiki uses the Go Markdown library.
+https://github.com/gomarkdown/markdown
+
+For more about percent-encoding, see Wikipedia.
+https://en.wikipedia.org/wiki/Percent-encoding
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/oddmu.service.5

@@ -0,0 +1,218 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "ODDMU.SERVICE" "5" "2025-03-14"
+.PP
+.SH NAME
+.PP
+oddmu.\&service - how to setup Oddmu using systemd
+.PP
+.SS DESCRIPTION
+.PP
+Here'\&s how to setup a wiki using systemd such that it starts automatically when
+the system boots and gets restarted automatically when it crashes.\&
+.PP
+First, create a new user called "oddmu" with it'\&s own home directory but without
+a login.\&
+.PP
+.nf
+.RS 4
+adduser --system --home /home/oddmu oddmu
+.fi
+.RE
+.PP
+The directory "/home/oddmu" contains the templates and all the data files.\& Copy
+all the templates files ending in ".\&html" from the source distribution to
+"/home/oddmu".\&
+.PP
+If you want to keep everything in one place, copy the binary "oddmu" and the
+service file "oddmu.\&service" to "/home/oddmu", too.\&
+.PP
+Edit the "oddmu.\&service" file.\& These are the lines you most likely have to take
+care of:
+.PP
+.nf
+.RS 4
+ExecStart=/home/oddmu/oddmu
+WorkingDirectory=/home/oddmu
+ReadWritePaths=/home/oddmu
+Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
+.fi
+.RE
+.PP
+Install the service file and enable it:
+.PP
+.nf
+.RS 4
+sudo systemctl enable --now \&./oddmu\&.service
+.fi
+.RE
+.PP
+You should be able to visit the wiki at http://localhost:8080/.\&
+.PP
+Check the log:
+.PP
+.nf
+.RS 4
+journalctl --unit oddmu
+.fi
+.RE
+.PP
+Follow the log:
+.PP
+.nf
+.RS 4
+journalctl --follow --unit oddmu
+.fi
+.RE
+.PP
+.SH Socket Activation
+.PP
+Alternatively, you can let systemd handle the creation of the listening socket,
+passing it to Oddmu.\& See "oddmu-unix-domain.\&service" and
+"oddmu-unix-domain.\&socket" for a fully worked example of how to do this with a
+Unix domain socket.\& Take note of "Accept=no" in the .\&socket file and
+"StandardInput=socket" in the .\&service file.\& The option "StandardInput=socket"
+tells systemd to pass the socket to the service as its standard input.\&
+"Accept=no" tells systemd to pass a listening socket, rather than to try calling
+Oddmu for each connection.\&
+.PP
+Instead of using "oddmu.\&service", you need to use "oddmu-unix-domain.\&socket" and
+"oddmu-unix-domain.\&service".\&
+.PP
+The unit file for the socket defines a file name.\& You probably need to create
+the directory or change the file name.\&
+.PP
+.nf
+.RS 4
+sudo mkdir /run/oddmu
+.fi
+.RE
+.PP
+The unit file for the service defines where the Oddmu binary is and where the
+data directory is.\& These are the lines you most likely have to take care of:
+.PP
+.nf
+.RS 4
+ExecStart=/home/oddmu/oddmu
+WorkingDirectory=/home/oddmu
+ReadWritePaths=/home/oddmu
+Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
+.fi
+.RE
+.PP
+To install, enable and start both units:
+.PP
+.nf
+.RS 4
+sudo systemctl enable --now \&./oddmu-unix-domain\&.socket
+sudo systemctl enable --now \&./oddmu-unix-domain\&.service
+.fi
+.RE
+.PP
+To test just the unix domain socket, use \fIncat(1)\fR:
+.PP
+.nf
+.RS 4
+echo -e "GET /view/index HTTP/1\&.1rnHost: localhostrnrn" 
+  | ncat --unixsock /run/oddmu/oddmu\&.sock
+.fi
+.RE
+.PP
+Now you need to set up your web browser to use the Unix domain socket.\& See
+\fIoddmu-apache\fR(5) or \fIoddmu-nginx\fR(5) for example configurations.\&
+.PP
+.SS A personal wiki
+.PP
+On a single user machine, it might be useful to have a single wiki for the main
+user available.\& In order to do this, setup a "user" unit using systemd and save
+the following as "user-unix-domain.\&service":
+.PP
+.nf
+.RS 4
+[Unit]
+Description=Oddmu
+After=network\&.target
+[Install]
+WantedBy=default\&.target
+[Service]
+Type=simple
+Restart=always
+StandardOutput=journal
+StandardError=journal
+ExecStart=/home/alex/src/oddmu/oddmu
+WorkingDirectory=/home/alex/wiki
+Environment="ODDMU_LANGUAGES=de,en"
+.fi
+.RE
+.PP
+Make sure to change the "ExecStart" entry so that it points to your copy of the
+Oddmu binary.\&
+.PP
+Since this is a user service, the same user can edit the files using their
+favourite text editor.\&
+.PP
+Install it:
+.PP
+.nf
+.RS 4
+systemctl --user enable --now \&./user-unix-domain\&.service
+.fi
+.RE
+.PP
+To examine the log:
+.PP
+.nf
+.RS 4
+journalctl --user --unit user-unix-domain\&.service
+.fi
+.RE
+.PP
+Note that no sudo is required!\&
+.PP
+.SS Using the priviledged port 80
+.PP
+When running a personal wiki, you can have the oddmu binary listen on port 80,
+the standard HTTP port.\& It is not really worth the effort: It means that you can
+visit "http://localhost/" instead of "http://localhost:8080".\& Nevertheless, if
+you'\&re interested in giving it a try, here'\&s how to do it.\&
+.PP
+The service definition must specify the new port:
+.PP
+Environment="ODDMU_PORT=80"
+.PP
+Since this is a privileged port, the binary needs an extra capability for an
+ordinary user to do this.\&
+.PP
+.nf
+.RS 4
+sudo setcap \&'cap_net_bind_service=+ep\&' oddmu
+.fi
+.RE
+.PP
+Note that as soon as you recompile, the capability is gone again and the above
+must be repeated.\&
+.PP
+.SH SECURITY
+.PP
+Only allow direct access to Oddmu on systems and networks where you'\&re OK with
+every user editing the pages.\& On the open web, this is not true.\& If your server
+is on the open web, always run Oddmu behind a regular web server acting as a
+reverse proxy, limiting regular visitors to read-only access.\& This means that
+the regular web server listens on the regular privileged ports (80 for HTTP,
+443 for HTTPS) and passes requests to Oddmu on some other port.\&
+.PP
+.SH SEE ALSO
+.PP
+\fIoddmu\fR(1), \fIoddmu-apache\fR(5), \fIoddmu-nginx\fR(5), \fIsystemd.\&exec\fR(5),
+\fIsystemd.\&socket\fR(5), \fIcapabilities\fR(7)
+.PP
+.SH AUTHORS
+.PP
+Maintained by Alex Schroeder <alex@gnu.\&org>.\&

man/oddmu.service.5.txt

@@ -0,0 +1,185 @@
+ODDMU.SERVICE(5)
+
+# NAME
+
+oddmu.service - how to setup Oddmu using systemd
+
+## DESCRIPTION
+
+Here's how to setup a wiki using systemd such that it starts automatically when
+the system boots and gets restarted automatically when it crashes.
+
+First, create a new user called "oddmu" with it's own home directory but without
+a login.
+
+```
+adduser --system --home /home/oddmu oddmu
+```
+
+The directory "/home/oddmu" contains the templates and all the data files. Copy
+all the templates files ending in ".html" from the source distribution to
+"/home/oddmu".
+
+If you want to keep everything in one place, copy the binary "oddmu" and the
+service file "oddmu.service" to "/home/oddmu", too.
+
+Edit the "oddmu.service" file. These are the lines you most likely have to take
+care of:
+
+```
+ExecStart=/home/oddmu/oddmu
+WorkingDirectory=/home/oddmu
+ReadWritePaths=/home/oddmu
+Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
+```
+
+Install the service file and enable it:
+
+```
+sudo systemctl enable --now ./oddmu.service
+```
+
+You should be able to visit the wiki at http://localhost:8080/.
+
+Check the log:
+
+```
+journalctl --unit oddmu
+```
+
+Follow the log:
+
+```
+journalctl --follow --unit oddmu
+```
+
+# Socket Activation
+
+Alternatively, you can let systemd handle the creation of the listening socket,
+passing it to Oddmu. See "oddmu-unix-domain.service" and
+"oddmu-unix-domain.socket" for a fully worked example of how to do this with a
+Unix domain socket. Take note of "Accept=no" in the .socket file and
+"StandardInput=socket" in the .service file. The option "StandardInput=socket"
+tells systemd to pass the socket to the service as its standard input.
+"Accept=no" tells systemd to pass a listening socket, rather than to try calling
+Oddmu for each connection.
+
+Instead of using "oddmu.service", you need to use "oddmu-unix-domain.socket" and
+"oddmu-unix-domain.service".
+
+The unit file for the socket defines a file name. You probably need to create
+the directory or change the file name.
+
+```
+sudo mkdir /run/oddmu
+```
+
+The unit file for the service defines where the Oddmu binary is and where the
+data directory is. These are the lines you most likely have to take care of:
+
+```
+ExecStart=/home/oddmu/oddmu
+WorkingDirectory=/home/oddmu
+ReadWritePaths=/home/oddmu
+Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
+```
+
+To install, enable and start both units:
+
+```
+sudo systemctl enable --now ./oddmu-unix-domain.socket
+sudo systemctl enable --now ./oddmu-unix-domain.service
+```
+
+To test just the unix domain socket, use _ncat(1)_:
+
+```
+echo -e "GET /view/index HTTP/1.1\r\nHost: localhost\r\n\r\n" \
+  | ncat --unixsock /run/oddmu/oddmu.sock
+```
+
+Now you need to set up your web browser to use the Unix domain socket. See
+_oddmu-apache_(5) or _oddmu-nginx_(5) for example configurations.
+
+## A personal wiki
+
+On a single user machine, it might be useful to have a single wiki for the main
+user available. In order to do this, setup a "user" unit using systemd and save
+the following as "user-unix-domain.service":
+
+```
+[Unit]
+Description=Oddmu
+After=network.target
+[Install]
+WantedBy=default.target
+[Service]
+Type=simple
+Restart=always
+StandardOutput=journal
+StandardError=journal
+ExecStart=/home/alex/src/oddmu/oddmu
+WorkingDirectory=/home/alex/wiki
+Environment="ODDMU_LANGUAGES=de,en"
+```
+
+Make sure to change the "ExecStart" entry so that it points to your copy of the
+Oddmu binary.
+
+Since this is a user service, the same user can edit the files using their
+favourite text editor.
+
+Install it:
+
+```
+systemctl --user enable --now ./user-unix-domain.service
+```
+
+To examine the log:
+
+```
+journalctl --user --unit user-unix-domain.service
+```
+
+Note that no sudo is required!
+
+## Using the priviledged port 80
+
+When running a personal wiki, you can have the oddmu binary listen on port 80,
+the standard HTTP port. It is not really worth the effort: It means that you can
+visit "http://localhost/" instead of "http://localhost:8080". Nevertheless, if
+you're interested in giving it a try, here's how to do it.
+
+The service definition must specify the new port:
+
+Environment="ODDMU_PORT=80"
+
+Since this is a privileged port, the binary needs an extra capability for an
+ordinary user to do this.
+
+```
+sudo setcap 'cap_net_bind_service=+ep' oddmu
+```
+
+Note that as soon as you recompile, the capability is gone again and the above
+must be repeated.
+
+# SECURITY
+
+Only allow direct access to Oddmu on systems and networks where you're OK with
+every user editing the pages. On the open web, this is not true. If your server
+is on the open web, always run Oddmu behind a regular web server acting as a
+reverse proxy, limiting regular visitors to read-only access. This means that
+the regular web server listens on the regular privileged ports (80 for HTTP,
+443 for HTTPS) and passes requests to Oddmu on some other port.
+
+# SEE ALSO
+
+_oddmu_(1), _oddmu-apache_(5), _oddmu-nginx_(5), _systemd.exec_(5),
+_systemd.socket_(5), _capabilities_(7)
+
+# AUTHORS
+
+Maintained by Alex Schroeder <alex@gnu.org>.

man/scdoc-to-markdown

@@ -0,0 +1,31 @@
+#!/usr/bin/perl
+use strict;
+use warnings;
+my $literal = 0;
+while (<>) {
+  # switch literal style
+  $literal = !$literal if /^```$/;
+  if ($literal) {
+    print;
+    next;
+  }
+  # bold
+  s/\*([^*]+)\*/**$1**/g;
+  # link to oddmu man pages (before italics)
+  s/_(oddmu[a-z.-]*)_\(([1-9])\)/[$1($2)]($1.$2)/g;
+  # italic
+  s/\b_([^_]+)_\b/*$1*/g;
+  # move all H1 headers to H2
+  s/^# (.*)/"## ".ucfirst(lc($1))/e;
+  # the new H1 title
+  s/^([A-Z.-]*\([1-9]\))( ".*")?$/"# ".lc($1)/e;
+  # quoted URLs
+  s/"(http.*?)"/`$1`/g;
+  # quoted wiki links
+  s/"(\[\[[^]]*\]\])"/`$1`/g;
+  # quoted Markdown links
+  s/"(\[.*?\]\(.*?\))"/`$1`/g;
+  # protect hashtags
+  s/#([^ #])/\\#$1/;
+  print;
+}

man_test.go

@@ -0,0 +1,161 @@
+package main
+
+import (
+	"github.com/stretchr/testify/assert"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"sort"
+	"strings"
+	"testing"
+)
+
+// Does oddmu(1) link to all the other man pages?
+func TestManPages(t *testing.T) {
+	b, err := os.ReadFile("man/oddmu.1.txt")
+	main := string(b)
+	assert.NoError(t, err)
+	count := 0
+	filepath.Walk("man", func(fp string, info fs.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if strings.HasSuffix(fp, ".txt") &&
+			fp != "man/oddmu.1.txt" {
+			count++
+			s := strings.TrimPrefix(fp, "man/")
+			s = strings.TrimSuffix(s, ".txt")
+			i := strings.LastIndex(s, ".")
+			ref := "_" + s[:i] + "_(" + s[i+1:] + ")"
+			assert.Contains(t, main, ref, ref)
+		}
+		return nil
+	})
+	assert.Greater(t, count, 0, "no man pages were found")
+}
+
+// Does oddmu-templates(5) mention all the templates?
+func TestManTemplates(t *testing.T) {
+	b, err := os.ReadFile("man/oddmu-templates.5.txt")
+	man := string(b)
+	assert.NoError(t, err)
+	count := 0
+	filepath.Walk(".", func(fp string, info fs.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if strings.HasSuffix(fp, ".html") {
+			count++
+			assert.Contains(t, man, fp, fp)
+		}
+		if fp != "." && info.IsDir() {
+			return filepath.SkipDir
+		}
+		return nil
+	})
+	assert.Greater(t, count, 0, "no templates were found")
+}
+
+// Does oddmu(1) mention all the actions? We're not going to parse the go file and make sure to catch them all. I tried
+// it, and it's convoluted.
+func TestManActions(t *testing.T) {
+	b, err := os.ReadFile("man/oddmu.1.txt")
+	assert.NoError(t, err)
+	main := string(b)
+	b, err = os.ReadFile("wiki.go")
+	assert.NoError(t, err)
+	wiki := string(b)
+	count := 0
+	// this doesn't match the root handler
+	re := regexp.MustCompile(`\.HandleFunc\("(/[a-z]+/)", makeHandler\([a-z]+Handler, (true|false)(, http\.Method(Get|Post))+\)\)`)
+	for _, match := range re.FindAllStringSubmatch(wiki, -1) {
+		count++
+		var path string
+		if match[2] == "true" {
+			path = "_" + match[1] + "dir/name"
+		} else {
+			path = "_" + match[1] + "dir/"
+		}
+		assert.Contains(t, main, path, path)
+	}
+	assert.Greater(t, count, 0, "no handlers were found")
+	// root handler is manual
+	assert.Contains(t, main, "\n- _/_", "root")
+}
+
+// Does the README link to all the man pages and all the Go source files,
+// excluding the command and test files?
+func TestReadme(t *testing.T) {
+	b, err := os.ReadFile("README.md")
+	readme := string(b)
+	assert.NoError(t, err)
+	count := 0
+	filepath.Walk("man", func(fp string, info fs.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if strings.HasSuffix(fp, ".txt") {
+			count++
+			s := strings.TrimPrefix(fp, "man/")
+			s = strings.TrimSuffix(s, ".txt")
+			i := strings.LastIndex(s, ".")
+			ref := "[" + s[:i] + "(" + s[i+1:] + ")]"
+			assert.Contains(t, readme, ref, ref)
+		}
+		return nil
+	})
+	assert.Greater(t, count, 0, "no man pages were found")
+	count = 0
+	filepath.Walk(".", func(fp string, info fs.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if strings.HasSuffix(fp, ".go") &&
+			!strings.HasSuffix(fp, "_test.go") &&
+			!strings.HasSuffix(fp, "_cmd.go") {
+			count++
+			s := strings.TrimPrefix(fp, "./")
+			ref := "`" + s + "`"
+			assert.Contains(t, readme, ref, ref)
+		}
+		return nil
+	})
+	assert.Greater(t, count, 0, "no source pages were found")
+}
+
+// Does the README document all the dependecies, checking all the all the packages with names containing a period?
+func TestDocumentDependencies(t *testing.T) {
+	b, err := os.ReadFile("README.md")
+	readme := string(b)
+	assert.NoError(t, err)
+	fset := token.NewFileSet()
+	pkgs, err := parser.ParseDir(fset, ".", nil, parser.ImportsOnly)
+	assert.NoError(t, err)
+	imports := []string{}
+	for _, pkg := range pkgs {
+		for _, file := range pkg.Files {
+			for _, imp := range file.Imports {
+				name := imp.Path.Value[1 : len(imp.Path.Value)-1]
+				if strings.Contains(name, ".") && !slices.Contains(imports, name) {
+					imports = append(imports, name)
+				}
+			}
+		}
+	}
+	assert.Greater(t, len(imports), 0, "no imports found")
+	sort.Slice(imports, func(i, j int) bool { return len(imports[i]) < len(imports[j]) })
+IMPORT:
+	for _, name := range imports {
+		for _, other := range imports {
+			if strings.HasPrefix(name, other) && name != other {
+				continue IMPORT
+			}
+		}
+		ok := strings.Contains(readme, name)
+		assert.True(t, ok, name)
+	}
+}

missing_cmd.go

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/gomarkdown/markdown"
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/google/subcommands"
+	"io"
+	"net/url"
+	"os"
+	"path"
+	"strings"
+)
+
+type missingCmd struct {
+}
+
+func (*missingCmd) Name() string     { return "missing" }
+func (*missingCmd) Synopsis() string { return "list missing pages" }
+func (*missingCmd) Usage() string {
+	return `missing:
+  Listing pages with links to missing pages. This command does not
+  understand links to directories being redirected to index pages.
+  A link such as [up](..) is reported as a link to a missing page.
+  Rewrite it as [up](../index) for it to work as intended.
+`
+}
+
+func (cmd *missingCmd) SetFlags(f *flag.FlagSet) {
+}
+
+func (cmd *missingCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	return missingCli(os.Stdout, &index)
+}
+
+// missingCli implements the finding of links to missing pages. In order to make testing easier, it takes a Writer and
+// an indexStore. The Writer is important so that test code can provide a buffer instead of os.Stdout; the indexStore is
+// important so that test code can ensure no other test running in parallel can interfere with the list of known pages
+// (by adding or deleting pages).
+func missingCli(w io.Writer, idx *indexStore) subcommands.ExitStatus {
+	found := false
+	for name := range idx.titles {
+		p, err := loadPage(name)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Loading %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		for _, link := range p.links() {
+			u, err := url.Parse(link)
+			if err != nil {
+				fmt.Fprintln(os.Stderr, p.Name, err)
+				return subcommands.ExitFailure
+			}
+			if u.Scheme == "" && u.Path != "" && !strings.HasPrefix(u.Path, "/") {
+				// feeds can work if the matching page works
+				u.Path = strings.TrimSuffix(u.Path, ".rss")
+				// links to the source file can work
+				u.Path = strings.TrimSuffix(u.Path, ".md")
+				// pages containing a colon need the ./ prefix
+				u.Path = strings.TrimPrefix(u.Path, "./")
+				// check whether the destination is a known page
+				destination, err := url.PathUnescape(u.Path)
+				if err != nil {
+					fmt.Fprintf(os.Stderr, "Cannot decode %s: %s\n", link, err)
+					return subcommands.ExitFailure
+				}
+				_, ok := idx.titles[destination]
+				// links to directories can work
+				if !ok {
+					_, ok = idx.titles[path.Join(destination, "index")]
+				}
+				if !ok {
+					if !found {
+						fmt.Fprintln(w, "Page\tMissing")
+						found = true
+					}
+					fmt.Fprintf(w, "%s\t%s\n", p.Name, link)
+				}
+			}
+		}
+	}
+	if !found {
+		fmt.Fprintln(w, "No missing pages found.")
+	}
+	return subcommands.ExitSuccess
+}
+
+// links parses the page content and returns an array of link destinations.
+func (p *Page) links() []string {
+	var links []string
+	parser, _ := wikiParser()
+	doc := markdown.Parse(p.Body, parser)
+	ast.WalkFunc(doc, func(node ast.Node, entering bool) ast.WalkStatus {
+		if entering {
+			switch v := node.(type) {
+			case *ast.Link:
+				link := string(v.Destination)
+				url, err := url.Parse(link)
+				if err != nil {
+					// no error reporting
+					return ast.GoToNext
+				}
+				if url.IsAbs() {
+					links = append(links, link)
+				} else {
+					dir := p.Dir()
+					links = append(links, path.Join(dir, link))
+				}
+			}
+		}
+		return ast.GoToNext
+	})
+	return links
+}

missing_cmd_test.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"bytes"
+	"github.com/google/subcommands"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestMissingCmd(t *testing.T) {
+	b := new(bytes.Buffer)
+	s := missingCli(b, minimalIndex(t))
+	assert.Equal(t, subcommands.ExitSuccess, s)
+	r := `Page	Missing
+index	test
+`
+	assert.Equal(t, r, b.String())
+}

notify_cmd.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"github.com/google/subcommands"
+	"io"
+	"os"
+	"strings"
+)
+
+type notifyCmd struct {
+}
+
+func (*notifyCmd) Name() string     { return "notify" }
+func (*notifyCmd) Synopsis() string { return "add links to changes.md, index.md, and hashtag pages" }
+func (*notifyCmd) Usage() string {
+	return `notify <page name> ...:
+  For each page, add entries to changes.md, index.md, and hashtag pages.
+  This is useful when writing pages offline and replicates the behaviour
+  triggered by the "Add link to the list of changes" checkbox, online.
+`
+}
+
+func (cmd *notifyCmd) SetFlags(f *flag.FlagSet) {
+}
+
+func (cmd *notifyCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
+	return notifyCli(os.Stdout, f.Args())
+}
+
+func notifyCli(w io.Writer, args []string) subcommands.ExitStatus {
+	index.load()
+	for _, name := range args {
+		if !strings.HasSuffix(name, ".md") {
+			fmt.Fprintf(os.Stderr, "%s does not end in '.md'\n", name)
+			return subcommands.ExitFailure
+		}
+		name = name[0:len(name)-3]
+		p, err := loadPage(name)
+		if err != nil {
+			fmt.Fprintf(w, "Loading %s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+		err = p.notify()
+		if err != nil {
+			fmt.Fprintf(w, "%s: %s\n", name, err)
+			return subcommands.ExitFailure
+		}
+	}
+	return subcommands.ExitSuccess
+}

oddmu-unix-domain.service

@@ -0,0 +1,53 @@
+[Unit]
+Description=Oddmu
+After=network.target
+Requires=oddmu-unix-domain.socket
+[Install]
+WantedBy=multi-user.target
+[Service]
+Type=simple
+Restart=always
+StandardInput=socket
+StandardOutput=journal
+StandardError=journal
+DynamicUser=true
+MemoryMax=256M
+MemoryHigh=128M
+ExecStart=/home/oddmu/oddmu
+WorkingDirectory=/home/oddmu
+Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
+
+# (man "systemd.exec")
+ReadWritePaths=/home/oddmu
+ProtectHostname=yes
+RestrictSUIDSGID=yes
+RemoveIPC=yes
+MemoryDenyWriteExecute=yes
+
+# Sandboxing options to harden security
+NoNewPrivileges=yes
+PrivateTmp=yes
+PrivateDevices=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+RestrictNamespaces=yes
+RestrictRealtime=yes
+DevicePolicy=closed
+ProtectSystem=full
+ProtectControlGroups=yes
+ProtectKernelModules=yes
+ProtectKernelTunables=yes
+LockPersonality=yes
+SystemCallFilter=~@clock @debug @module @mount @obsolete @reboot @setuid @swap
+
+# Denying access to capabilities that should not be relevant
+# (man "capabilities")
+CapabilityBoundingSet=~CAP_RAWIO CAP_MKNOD
+CapabilityBoundingSet=~CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE
+CapabilityBoundingSet=~CAP_SYS_BOOT CAP_SYS_TIME CAP_SYS_MODULE CAP_SYS_PACCT
+CapabilityBoundingSet=~CAP_LEASE CAP_LINUX_IMMUTABLE CAP_IPC_LOCK
+CapabilityBoundingSet=~CAP_BLOCK_SUSPEND CAP_WAKE_ALARM
+CapabilityBoundingSet=~CAP_SYS_TTY_CONFIG
+CapabilityBoundingSet=~CAP_MAC_ADMIN CAP_MAC_OVERRIDE
+CapabilityBoundingSet=~CAP_NET_ADMIN CAP_NET_BROADCAST CAP_NET_RAW
+CapabilityBoundingSet=~CAP_SYS_ADMIN CAP_SYS_PTRACE CAP_SYSLOG

oddmu-unix-domain.socket

@@ -0,0 +1,14 @@
+[Unit]
+Description=Oddmu server socket
+
+[Socket]
+ListenStream=/run/oddmu/oddmu.sock
+SocketGroup=www-data
+# Systemd manages the socket, so may as well let it be owned by root.
+SocketUser=root
+# But it needs to be readable and writable by the web server.
+SocketMode=0660
+Accept=no
+
+[Install]
+WantedBy=sockets.target

oddmu.service

@@ -7,22 +7,21 @@ WantedBy=multi-user.target
 Type=simple
 Restart=always
 DynamicUser=true
-MemoryMax=100M
-MemoryHigh=120M
+MemoryMax=120M
+MemoryHigh=100M
 ExecStart=/home/oddmu/oddmu
 WorkingDirectory=/home/oddmu
 Environment="ODDMU_PORT=8080"
+Environment="ODDMU_WEBFINGER=1"
 
 # (man "systemd.exec")
 ReadWritePaths=/home/oddmu
 ProtectHostname=yes
 RestrictSUIDSGID=yes
-UMask=0077
 RemoveIPC=yes
 MemoryDenyWriteExecute=yes
 
 # Sandboxing options to harden security
-# Details for these options: https://www.freedesktop.org/software/systemd/man/systemd.exec.html
 NoNewPrivileges=yes
 PrivateTmp=yes
 PrivateDevices=yes
@@ -38,7 +37,7 @@ LockPersonality=yes
 SystemCallFilter=~@clock @debug @module @mount @obsolete @reboot @setuid @swap
 
 # Denying access to capabilities that should not be relevant
-# Doc: https://man7.org/linux/man-pages/man7/capabilities.7.html
+# (man "capabilities")
 CapabilityBoundingSet=~CAP_RAWIO CAP_MKNOD
 CapabilityBoundingSet=~CAP_AUDIT_CONTROL CAP_AUDIT_READ CAP_AUDIT_WRITE
 CapabilityBoundingSet=~CAP_SYS_BOOT CAP_SYS_TIME CAP_SYS_MODULE CAP_SYS_PACCT

oddmu.svg

@@ -0,0 +1,30 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg"
+    heigh="320" width="320"
+    viewBox="0 0 320 320">
+  <g>
+    <circle  id="hand1" cx="60" cy="190" r="15" fill="white" stroke="black" stroke-width="2"/>
+    <path id="stick" d="M40,40 L60,300 H66 L46,40 Z" fill="white" stroke="black" stroke-width="2"/>
+    <ellipse  id="fingers" cx="50" cy="195" rx="5" ry="15" fill="white" stroke="black" stroke-width="2"/>
+    <path id="thumb" d="M60,180 Q40,180 60,190 Z" fill="white" stroke="black" stroke-width="2"/>
+  </g>
+  <g id="hand2">
+    <circle cx="240" cy="200" r="15" fill="white" stroke="black" stroke-width="2"/>
+  </g>
+  <g id="body">
+    <path d="M60,170 H170 L240,180 V230 L190,220
+             L200,222 L220,290 H120 V215
+             L125,215 H60 V170" fill="white" stroke="black" stroke-width="2"/>
+  </g>
+  <g id="face">
+    <circle cx="150" cy="150" r="30" fill="white" stroke="black" stroke-width="2"/>
+    <circle cx="138" cy="145" r="2" fill="black" stroke="black"/>
+    <circle cx="158" cy="145" r="2" fill="black" stroke="black"/>
+    <path d="M132,158 Q145,175 170,155 " fill="none" stroke="black" stroke-width="2"/>
+  </g>
+  <g id="foot1">
+    <path d="M120,300 C100,270 180,270 160,300 Z" fill="white" stroke="black" stroke-width="2"/>
+  </g>
+  <g id="foot1">
+    <path d="M180,300 V290 H190 C210,270 250,280 240,300 Z" fill="white" stroke="black" stroke-width="2"/>
+  </g>
+</svg>

page.go

@@ -2,94 +2,129 @@ package main
 
 import (
 	"bytes"
-	"fmt"
-	"github.com/gomarkdown/markdown"
-	"github.com/gomarkdown/markdown/ast"
-	"github.com/gomarkdown/markdown/parser"
 	"github.com/microcosm-cc/bluemonday"
-	"github.com/pemistahl/lingua-go"
 	"html/template"
+	"log"
+	"net/url"
 	"os"
+	"path"
 	"path/filepath"
+	"regexp"
 	"strings"
+	"time"
 )
 
-// languages is the list of languages the wiki understands. This is
-// passed along to the template so that it can be added to the
-// template which allows browsers to (maybe) do hyphenation correctly.
-var languages = []lingua.Language{
-	lingua.English,
-	lingua.German,
-}
-
-// detector is built once based on the list languages.
-var detector = lingua.NewLanguageDetectorBuilder().
-	FromLanguages(languages...).
-	WithPreloadedLanguageModels().
-	WithLowAccuracyMode().
-	Build()
-
-// Page is a struct containing information about a single page. Title
-// is the title extracted from the page content using titleRegexp.
-// Name is the filename without extension (so a filename of "foo.md"
-// results in the Name "foo"). Body is the Markdown content of the
-// page and Html is the rendered HTML for that Markdown. Score is a
-// number indicating how well the page matched for a search query.
+// Page is a struct containing information about a single page. Title is the title extracted from the page content using
+// titleRegexp. Name is the path without extension (so a path of "foo.md" results in the Name "foo"). Body is the
+// Markdown content of the page and Html is the rendered HTML for that Markdown.
 type Page struct {
 	Title    string
 	Name     string
-	Language string
 	Body     []byte
 	Html     template.HTML
-	Score    int
+	Hashtags []string
 }
 
-func sanitize(s string) template.HTML {
-	return template.HTML(bluemonday.UGCPolicy().Sanitize(s))
+// Link is a struct containing a title and a name. Name is the path without extension (so a path of "foo.md" results in
+// the Name "foo").
+type Link struct {
+	Title string
+	Url   string
 }
 
-func sanitizeBytes(bytes []byte) template.HTML {
-	return template.HTML(bluemonday.UGCPolicy().SanitizeBytes(bytes))
+// blogRe is a regular expression that matches blog pages. If the filename of a blog page starts with an ISO date
+// (YYYY-MM-DD), then it's a blog page.
+var blogRe = regexp.MustCompile(`^\d\d\d\d-\d\d-\d\d`)
+
+// santizeStrict uses bluemonday to sanitize the HTML away. No elements are allowed except for the b tag because this is
+// used for snippets.
+func sanitizeStrict(s string) template.HTML {
+	policy := bluemonday.StrictPolicy()
+	policy.AllowElements("b")
+	return template.HTML(policy.Sanitize(s))
 }
 
-// save saves a Page. The filename is based on the Page.Name and gets
-// the ".md" extension. Page.Body is saved, without any carriage
-// return characters ("\r"). The file permissions used are readable
-// and writeable for the current user, i.e. u+rw or 0600. Page.Title
-// and Page.Html are not saved no caching. There is no caching.
+// unsafeBytes does not use bluemonday to sanitize the HTML used for pages. This is where you make changes if you want
+// to be more lenient. If you look at the git repository, there are older versions containing the function sanitizeBytes
+// which would do elaborate checking.
+func unsafeBytes(bytes []byte) template.HTML {
+	return template.HTML(bytes)
+}
+
+// nameEscape returns the page name safe for use in URLs. That is, percent escaping is used except for the slashes.
+func nameEscape(s string) string {
+	parts := strings.Split(s, "/")
+	for i, part := range parts {
+		parts[i] = url.PathEscape(part)
+	}
+	return strings.Join(parts, "/")
+}
+
+// save saves a Page. The path is based on the Page.Name and gets the ".md" extension. Page.Body is saved, without any
+// carriage return characters ("\r"). Page.Title and Page.Html are not saved. There is no caching. Before removing or
+// writing a file, the old copy is renamed to a backup, appending "~". Errors are not logged but returned.
 func (p *Page) save() error {
-	filename := p.Name + ".md"
+	fp := filepath.FromSlash(p.Name) + ".md"
+	watches.ignore(fp)
 	s := bytes.ReplaceAll(p.Body, []byte{'\r'}, []byte{})
+	if len(s) == 0 {
+		log.Println("Delete", p.Name)
+		index.remove(p)
+		return os.Rename(fp, fp+"~")
+	}
 	p.Body = s
-	p.updateIndex()
-	d := filepath.Dir(filename)
+	index.update(p)
+	d := filepath.Dir(fp)
 	if d != "." {
-		err := os.MkdirAll(d, 0700)
+		err := os.MkdirAll(d, 0755)
 		if err != nil {
-			fmt.Printf("Creating directory %s failed", d)
 			return err
 		}
 	}
-	return os.WriteFile(filename, s, 0600)
+	err := backup(fp)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(fp, s, 0644)
 }
 
-// loadPage loads a Page given a name. The filename loaded is that
-// Page.Name with the ".md" extension. The Page.Title is set to the
-// Page.Name (and possibly changed, later). The Page.Body is set to
-// the file content. The Page.Html remains undefined (there is no
-// caching).
+// backup a file by renaming it unless the existing backup is less than an hour old. A backup gets a tilde appended to
+// it ("~"). This is true even if the file refers to a binary file like "image.png" and most applications don't know
+// what to do with a file called "image.png~". This expects a filepath. The backup file gets its modification time set
+// to now so that subsequent edits don't immediately overwrite it again.
+func backup(fp string) error {
+	_, err := os.Stat(fp)
+	if err != nil {
+		return nil
+	}
+	bp := fp + "~"
+	fi, err := os.Stat(bp)
+	if err != nil || time.Since(fi.ModTime()).Minutes() >= 60 {
+		err = os.Rename(fp, bp)
+		if err != nil {
+			return err
+		}
+		ts := time.Now()
+		return os.Chtimes(bp, ts, ts)
+	}
+	return nil
+}
+
+// loadPage loads a Page given a name. The path loaded is that Page.Name with the ".md" extension. The Page.Title is set
+// to the Page.Name (and possibly changed, later). The Page.Body is set to the file content. The Page.Html remains
+// undefined (there is no caching).
 func loadPage(name string) (*Page, error) {
-	filename := name + ".md"
-	body, err := os.ReadFile(filename)
+	name = strings.TrimPrefix(name, "./") // result of a path.TreeWalk starting with "."
+	body, err := os.ReadFile(filepath.FromSlash(name) + ".md")
 	if err != nil {
 		return nil, err
 	}
-	return &Page{Title: name, Name: name, Body: body, Language: ""}, nil
+	return &Page{Title: name, Name: name, Body: body}, nil
 }
 
-// handleTitle extracts the title from a Page and sets Page.Title, if
-// any. If replace is true, the page title is also removed from
-// Page.Body. Make sure not to save this! This is only for rendering.
+// handleTitle extracts the title from a Page and sets Page.Title, if any. If replace is true, the page title is also
+// removed from Page.Body. Make sure not to save this! This is only for rendering. In a template, the title is a
+// separate attribute and is not repeated in the HTML.
 func (p *Page) handleTitle(replace bool) {
 	s := string(p.Body)
 	m := titleRegexp.FindStringSubmatch(s)
@@ -101,52 +136,96 @@ func (p *Page) handleTitle(replace bool) {
 	}
 }
 
-// renderHtml renders the Page.Body to HTML and sets Page.Html.
-func (p *Page) renderHtml() {
-	maybeUnsafeHTML := markdown.ToHTML(p.Body, nil, nil)
-	p.Html = sanitizeBytes(maybeUnsafeHTML)
-	p.Language = language(p.plainText())
-}
-
-// plainText renders the Page.Body to plain text and returns it,
-// ignoring all the Markdown and all the newlines. The result is one
-// long single line of text.
-func (p *Page) plainText() string {
-	parser := parser.New()
-	doc := markdown.Parse(p.Body, parser)
-	text := []byte("")
-	ast.WalkFunc(doc, func(node ast.Node, entering bool) ast.WalkStatus {
-		if entering && node.AsLeaf() != nil {
-			text = append(text, node.AsLeaf().Literal...)
-			text = append(text, []byte(" ")...)
-		}
-		return ast.GoToNext
-	})
-	// Some Markdown still contains newlines
-	for i, c := range text {
-		if c == '\n' {
-			text[i] = ' '
-		}
-	}
-	// Remove trailing space
-	for len(text) > 0 && text[len(text)-1] == ' ' {
-		text = text[0 : len(text)-1]
-	}
-	return string(text)
-}
-
-// summarize for query string q sets Page.Html to an extract.
+// summarize sets Page.Html to an extract.
 func (p *Page) summarize(q string) {
-	p.handleTitle(true)
-	p.Score = score(q, string(p.Body)) + score(q, p.Title)
 	t := p.plainText()
-	p.Html = sanitize(snippets(q, t))
-	p.Language = language(t)
+	p.Html = sanitizeStrict(snippets(q, t))
 }
 
-func language(s string) string {
-	if language, ok := detector.DetectLanguageOf(s); ok {
-		return strings.ToLower(language.IsoCode639_1().String())
-	}
-	return ""
+// IsBlog returns true if the page name starts with an ISO date
+func (p *Page) IsBlog() bool {
+	name := path.Base(p.Name)
+	return blogRe.MatchString(name)
+}
+
+const upperhex = "0123456789ABCDEF"
+
+// Path returns the Page.Name with some characters escaped because html/template doesn't escape those. This is suitable
+// for use in HTML templates.
+func (p *Page) Path() string {
+	return pathEncode(p.Name)
+}
+
+// pathEncode returns the page name with some characters escaped because html/template doesn't escape those. This is
+// suitable for use in HTML templates.
+func pathEncode(s string) string {
+	n := strings.Count(s, ";") + strings.Count(s, ",") + strings.Count(s, "?") + strings.Count(s, "#")
+	if n == 0 {
+		return s
+	}
+	t := make([]byte, len(s) + 2*n)
+	j := 0
+	for i := 0; i < len(s); i++ {
+		switch s[i] {
+		case ';', ',', '?', '#':
+			t[j] = '%'
+			t[j+1] = upperhex[s[i]>>4]
+			t[j+2] = upperhex[s[i]&15]
+			j += 3
+		default:
+			t[j] = s[i]
+			j++
+		}
+	}
+	return string(t)
+}
+
+// Dir returns the directory part of the page name, percent-escaped except for the slashes. It's either the empty string
+// if the page is in the Oddmu working directory, or it ends in a slash. This is used to create the upload link in
+// "view.html", for example.
+func (p *Page) Dir() string {
+	d := path.Dir(p.Name)
+	if d == "." {
+		return ""
+	}
+	return pathEncode(d) + "/"
+}
+
+// Base returns the  basename of the page  name: no directory, percent-escaped except  for the slashes. This  is used to
+// create the upload link in "view.html", for example.
+func (p *Page) Base() string {
+	n := path.Base(p.Name)
+	if n == "." {
+		return ""
+	}
+	return n
+}
+
+// Today returns the date, as a string, for use in templates.
+func (p *Page) Today() string {
+	return time.Now().Format(time.DateOnly)
+}
+
+// Parents returns a Link array to parent pages, up the directory structure.
+func (p *Page) Parents() []*Link {
+	links := make([]*Link, 0)
+	index.RLock()
+	defer index.RUnlock()
+	// foo/bar/baz ⇒ index, foo/index
+	elems := strings.Split(p.Name, "/")
+	if len(elems) == 1 {
+		return links
+	}
+	s := ""
+	for i := 0; i < len(elems)-1; i++ {
+		name := s + "index"
+		title, ok := index.titles[name]
+		if !ok {
+			title = "…"
+		}
+		link := &Link{Title: title, Url: strings.Repeat("../", len(elems)-i-1) + "index"}
+		links = append(links, link)
+		s += elems[i] + "/"
+	}
+	return links
 }