From 7d4e7ef4cbafce6a979535af4ceab1cfebda633d Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
Date: Sat, 16 Oct 2021 09:11:43 -0400
Subject: README.md: improve documentation

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e6e8106..7451f56 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,31 @@
 pablotron.org
 =============
 
+Overview
+--------
+[Hugo][] backend for [pablotron.org][].
+
+Content is divided into three [sections][]:
+
+|Section Type|Description|Permalinks|
+|------------|-----------|---------|
+|`posts`|Blog entries.|`/YYYY/MM/DD/SLUG/`|
+|`articles`|Long-form articles.|`/articles/SLUG/`|
+|`projects`|Programming projects.|`/SLUG/`|
+
+The 10 most recent `posts` are shown on the home page in reverse
+chronological order.  A list of all `posts`, grouped by year, is shown
+on the [archive][] page in reverse chronological order.
+
+`articles` are long-form content that doesn't fit nicely as blog posts.
+
+`projects` have a repository link and a brief description.  Eventually I
+may add more information (release history, signatures, etc).
+
+Usage
+-----
+The `bin/new` script allows you (me) to easily create new content:
+
 Add a new post:
 
     # easy version
@@ -17,4 +42,21 @@ Add a new project:
     # longer version
     hugo new --editor $EDITOR  projects/some-slug.md
 
-Add a new menu entry: Edit `data/menu.yaml`.
+Add a new navbar menu entry:
+
+    # edit navbar menu entries
+    vim data/menu.yaml
+
+Theme
+-----
+The current theme is `hugo-pt2021` and is stored in `themes/hugo-pt2021`
+which is included in this repository.
+
+[hugo]: https://gohugo.io/
+  "hugo static site generator"
+[sections]: https://gohugo.io/content-management/sections/
+  "content sections"
+[pablotron.org]: https://pablotron.org/
+  "the hottest site on the net"
+[archive]: https://pablotron.org/archive/
+  "post archive"
-- 
cgit v1.2.3