README.md: improve documentation

1 files changed, 43 insertions, 1 deletions

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"