From ba106a04778a8500e233e7496975912e5affa457 Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
Date: Sat, 16 Oct 2021 09:29:10 -0400
Subject: README.md: add theme information, clean up usage section

---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 53 insertions(+), 19 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 7451f56..7d8b7eb 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,7 @@
-pablotron.org
-=============
+# pablotron.org
+
+## Overview
 
-Overview
---------
 [Hugo][] backend for [pablotron.org][].
 
 Content is divided into three [sections][]:
@@ -13,7 +12,7 @@ Content is divided into three [sections][]:
 |`articles`|Long-form articles.|`/articles/SLUG/`|
 |`projects`|Programming projects.|`/SLUG/`|
 
-The 10 most recent `posts` are shown on the home page in reverse
+The 10 most recent `posts` are shown on the home page blog in reverse
 chronological order.  A list of all `posts`, grouped by year, is shown
 on the [archive][] page in reverse chronological order.
 
@@ -22,35 +21,64 @@ 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).
 
-Usage
------
-The `bin/new` script allows you (me) to easily create new content:
+## Usage
+
+The `bin/new` script allows you (me) to quickly create new content by:
+
+1. Expanding a section template ([Hugo][] calls these templates
+   "archetypes") draft content.
+2. Opening the draft content in your editor.
+
+## Add Post
+
+To add a new post:
+
+    # easy version
+    bin/new post some-blog-post
+
+    # longer version
+    hugo new --editor $EDITOR  posts/$(date +%Y-%m-%d)-some-blog-post.md
+
+## Add Article
 
-Add a new post:
+To add a new article:
 
     # easy version
-    bin/new post some-slug
+    bin/new article some-article
 
     # longer version
-    hugo new --editor $EDITOR  posts/$(date +%Y-%m-%d)-some-slug.md
+    hugo new --editor $EDITOR  articles/some-article.md
 
-Add a new project:
+## Add Project
+
+To add a new project:
 
     # easy version
-    bin/new project some-slug
+    bin/new project great-project
 
     # longer version
-    hugo new --editor $EDITOR  projects/some-slug.md
+    hugo new --editor $EDITOR  projects/great-project.md
+
+## Edit Navbar Menu
 
-Add a new navbar menu entry:
+To add or edit navbar menu entries:
 
     # 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.
+# Theme
+
+The current theme is `hugo-pt2021` and is stored in this repository as
+`themes/hugo-pt2021`.
+
+`hugo-pt2021` is depends on the following:
+
+* [Bulma 0.9.3][bulma]: CSS framework.
+* Several icons from [Feather Icons][feathericons].
+
+The [Bulma][] CSS is customized and minified using [Hugo
+Pipes][hugo-pipes].  See `themes/hugo-pt2021/assets/style.sass` for
+details.
 
 [hugo]: https://gohugo.io/
   "hugo static site generator"
@@ -60,3 +88,9 @@ which is included in this repository.
   "the hottest site on the net"
 [archive]: https://pablotron.org/archive/
   "post archive"
+[bulma]: https://bulma.io/
+  "modern CSS framework"
+[feathericons]: https://github.com/feathericons/feather
+  "beautiful open source icons"
+[hugo-pipes]: https://gohugo.io/hugo-pipes/
+  "hugo asset processing pipeline"
-- 
cgit v1.2.3