From 4edb4ad4cfba321751cf39941a2889bdac98f955 Mon Sep 17 00:00:00 2001
From: eudoxia <uplink@distress.network>
Date: Thu, 7 Apr 2022 11:39:30 -0400
Subject: doc: backend syncing with distress.network

---
 doc/usage.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 readme.md    |   2 +-
 2 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 doc/usage.md
 mode change 100644 => 100755 readme.md

diff --git a/doc/usage.md b/doc/usage.md
new file mode 100644
index 0000000..47bfd62
--- /dev/null
+++ b/doc/usage.md
@@ -0,0 +1,122 @@
+title: Website Maintenance Tools
+leading: A collection of tools for the maintenance of this website.
+opts: ch
+
+# Overview
+
+These scripts must be executed from within their residing directory only, and depend on adjacent files within it in order to function. For convenience it is recommended to create symlinks within this directory to all website directories under maintenance.
+
+# md.sh
+
+`md.sh` is a static site generator from Markdown files.
+
+The script may be executed with a single argument corresponding to the webpage directory containing the input Markdown file, which should be named `src.md`. The output HTML file, named `index.html`, will be located in the same directory.
+
+```
+./md.sh <target directory>
+```
+
+Alternatively, the script may be given two arguments consisting of the input and output file paths respectively.
+
+```
+./md.sh <input md> <output html>
+```
+
+## Dependencies
+
+- [lowdown](https://kristaps.bsd.lv/lowdown)
+
+## Document Metadata
+
+The input file may begin with metadata key-value declarations, as specified by [lowdown(5)](https://kristaps.bsd.lv/lowdown/lowdown.5.html#Metadata). `md.sh` recognizes and formats the following:
+
+- `title`, for the HTML page title;
+- `bomber`, for the header splash text;
+- `leading`, for the page's leading phrase;
+- `opts`, for further configuration options described below.
+
+Page options are denoted by any combination of the following characters:
+
+- `c`, to generate a table of contents;
+- `f`, to suppress generation of the page footer;
+- `h`, to suppress generation of the page header,
+- `m`, to enable math rendering (see below).
+
+The table of contents may produce erroneous links if two headers within the page have identical names.
+
+## Math Rendering
+
+The rendering of LaTeX math mode expressions given within input files may be enabled by adding the `m` option. This depends on an installation of [KaTeX](https://katex.org) via `npm`.
+
+Block expressions are declared as follows:
+
+```
+![...](%tex)
+```
+
+Inline expressions are declared as follows:
+
+```
+![...](%itex)
+```
+
+where `...` is the LaTeX expression.
+
+# plain.sh
+
+`plain.sh` converts plain text files to HTML documents.
+
+```
+./plain.sh <input txt> <output html>
+```
+
+## Page Title
+
+The HTML page title may be specified within the input document using the following declaration:
+
+```
+<!--title: ... -->
+```
+where `...` is the page title.
+
+# Other Tools
+
+## front.sh
+
+`front.sh` generates the [front page](/).
+
+```
+./front.sh <output html>
+```
+
+## nav.sh
+
+`nav.sh` generates the sitemap navigation pane. Installation of [tree](http://mama.indstate.edu/users/ice/tree/) is required.
+
+```
+./nav.sh <source dir> <output file>
+```
+
+## reload.sh
+
+`reload.sh` is a meta-script which updates the website's front page, navigation listings, and XML sitemap, and can optionally regenerate all of the webpages at once.
+
+```
+./reload.sh [-r]
+```
+
+## sitemap.sh
+
+`sitemap.sh` generates the website's [XML sitemap](/sitemap.xml), as specified by [sitemaps.org](https://www.sitemaps.org/protocol.html).
+
+```
+./sitemap.sh <target dir> <output xml>
+```
+
+## urlencode
+
+`urlencode` is a small C program which converts a string into a URL-encoded format.
+
+```
+echo "<string>" | ./urlencode
+```
diff --git a/readme.md b/readme.md
old mode 100644
new mode 100755
index e798f59..32b28ac
--- a/readme.md
+++ b/readme.md
@@ -1,2 +1,2 @@
 This repository contains a collection of tools for the maintenance of the [DistressNetwork°](https://distress.network) website.
-For further information, see <https://distress.network/software/web>.
+For further information, see the documentation at <https://distress.network/software/web>, or offline at `doc/usage.md`.
-- 
cgit v1.2.3