shithub: docs.9front.org

ref: 23520cdd0314a2ea171ce8a7c1047fbd805a7e83
dir: /this.md/

View raw version
About this
==========

Other than the git content repository—at the moment hosted on
sourcehut—the docs system runs and is hosted by 9front software
on a 9front machine.

This page intends to document how this is done.

The software
------------

Ori's [git9](https://github.com/oridb/git9) is used for
pulling content updates from the repository.

kvik's [ugh!](http://src.a-b.xyz/ugh) site generator
renders the content, mainly the HTML pages.

ugh! depends on [discount](https://github.com/Orc/discount)
markdown processor by default.

cinap's [tcp80](http://felloff.net/tcp80.tgz) which has been
slightly [modified](http://src.a-b.xyz/tcp80) serves the web clients.

kvik's [unionfs](http://src.a-b.xyz/unionfs) serves the 9p clients.

The setup
---------

The rest is a glue provided through standard 9front mechanisms.

### Starting off

	; git/clone git://src.a-b.xyz/ugh /usr/doc
	; git/clone https://git.sr.ht/~kvik/docs.9front.org /usr/doc/data
	; mkdir /usr/web

### Updates

Checking for updates and triggering page regeneration is done by a
custom script running once per minute through cron.

	0-59 * * * * local /usr/doc/bin/update

### Serving 9p

9p clients are served by unionfs, spawned by system network listener.

`/cfg/$sysname/service/tcp909`

	#!/bin/rc
	# Runs as 'none'.
	exec /bin/unionfs -i /usr/doc/public

### Serving HTTP

Web clients are served by tcp80, spawned by system network listener.

`/cfg/$sysname/service/tcp80`

	#!/bin/rc
	exec /bin/tcp80 -n /usr/doc/cfg/webns

The namespace file `/usr/doc/cfg/` simply binds the `public/` directory
to the web root:

	bind /usr/doc/public /usr/web

Work-in-Progress
----------------

### Quick-linking

### Categories

Not a priority, considering the currently small amount of content.

The benefit of organizing content in categories mostly seems to be the
ability to generate hierarchical sitemaps.

A probable implementation is allowing arbitrary hierarchy in the source
page directory, letting each directory denote a (sub)-category.