From 3d2e1624ce0abc3f9c8148140ec2be3428001dc7 Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
Date: Thu, 18 Nov 2021 10:40:11 -0500
Subject: README.md: update documentation

---
 README.md | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 3e43060..6a2c53a 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,14 @@ on the [archive][] page in reverse chronological order.
 `projects` have a repository link and a brief description.  Eventually I
 may add more information (release history, signatures, etc).
 
+Put assets (images, files, etc) for articles and posts in
+`static/files/{articles|posts}/$SLUG`.  Use the built-in `figure`
+shortcode to reference images in content, because it supports more
+attributes and is responsive (grep existing content for examples).
+
+Use [mathyd][] to generate [SVGs][svg] for math posts and articles,
+rather than pulling in [MathJax][].
+
 ## Usage
 
 The `bin/new` script allows you (me) to quickly create new content by:
@@ -51,13 +59,7 @@ To add a new article:
 
 ## Add Project
 
-To add a new project:
-
-    # easy version
-    bin/new project great-project
-
-    # longer version
-    hugo new --editor $EDITOR  projects/great-project.md
+Update `data/projects.yaml` and then run `bin/gen-projects.rb`.
 
 ## Edit Navbar Menu
 
@@ -71,9 +73,10 @@ To add or edit navbar menu entries:
 To serve this site locally:
 
     # serve hugo locally on port 1313
-    hugo serve --minify --disableFastRender
+    hugo serve -D --minify --disableFastRender
 
 **Notes:**
+* `-D` shows draft content,
 * `--minify` generates minified HTML, and
   [`html/template`][html-template] is aware of `<pre>` and `<code>` so
   inline code blocks work correctly.
@@ -96,17 +99,27 @@ Then:
 * push to upstream repo
 
 The push will trigger a hook which runs
-`/data/www/pablotron.org/data/bin/deploy.sh`, which will:
+`/data/www/pablotron.org/data/bin/hook/deploy.rb`, which will:
 
 1. Pull the latest changes from the git repository
 2. Run [Hugo][] to rebuild the site.
-3. Update the `htdocs` symlink
+3. Update the `htdocs` symlink for the live site.
+4. Remove stale site builds.
+5. Log the time taken for each step.
+
+See `bin/hook/` for additional information.
 
 # Theme
 
 The current theme is `hugo-pt2021` and is stored in this repository as
 `themes/hugo-pt2021`.
 
+Includes the following shortcodes:
+
+* `table`: Enhanced [CSS][]-only table shortcode.  See
+  [hugo-shortcode-table][].
+* `sup`: Superscript.
+
 `hugo-pt2021` is depends on the following:
 
 * [Bulma 0.9.3][bulma]: CSS framework.
@@ -143,3 +156,11 @@ The [Bulma][] [SASS][] is:
   "Go programming language"
 [html-template]: https://pkg.go.dev/html/template
   "Go's built-in HTML template renderer"
+[mathyd]: https://github.com/pablotron/mathyd
+  "TeX to SVG rendering daemon and docker image."
+[mathjax]: https://mathjax.org/
+  "JavaScript LaTeX renderer."
+[svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
+  "Scalable Vector Graphics"
+[hugo-shortcode-table]: https://github.com/pablotron/hugo-shortcode-table
+  "CSS-only table shortcode for Hugo."
-- 
cgit v1.2.3