all changes

lisp/recently-updated.el

@@ -1,115 +1,101 @@
-;;; recently-updated.el --- Generate recently-updated.org  -*- lexical-binding: t; -*-
+;;; recently-updated.el --- Generate recently-updated.org -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Generates home/recently-updated.org listing the N most recently touched
+;; Org files in the site tree.
+;;
+;; Sort order: #+DATE if parseable, otherwise file modification time.
+;; This means intentionally dated pages float correctly, while undated
+;; pages fall back to when they were last touched on disk.
+;;
+;; NOTE: Do NOT define `site-root' here.  build-site.el owns that definition.
+
+;;; Code:
 
 (require 'cl-lib)
 (require 'org)
-(defvar site-root
-  (file-name-directory
-   (or load-file-name buffer-file-name)))
 
-(defvar z-org-root
-  (file-name-as-directory site-root)
-  "Root directory of the Org source files.")
+;; ── Omit predicate ────────────────────────────────────────────────────────────
+
+(defconst z/recent-omit-names
+  '("sitemap.org"
+    "categories.org"
+    "recently-updated.org"
+    "wip.org")
+  "Org files that are always excluded from the recently-updated list.")
 
-;; Which Org files should be skipped for Recently Updated
 (defun z/recent-omit-org-p (rel-org)
-  "Return non-nil if REL-ORG (relative to `z-org-root`) should not be listed."
-  (let* ((name (file-name-nondirectory rel-org)))
+  "Return non-nil if REL-ORG (relative to site root) should be excluded."
+  (let ((name (file-name-nondirectory rel-org)))
     (or
-     ;; assets-ish / tags
+     ;; Static asset directories
      (string-prefix-p "assets/" rel-org)
-     (string-match-p "/assets/" rel-org)
+     (string-match-p  "/assets/" rel-org)
+     ;; Tag pages
      (string-prefix-p "tags/" rel-org)
-     (string-match-p "/tags/" rel-org)
-
-     ;; generated/meta orgs
-     (member name '("sitemap.org"
-                    "categories.org"
-                    "recently-updated.org"
-		    "wip.org"
-		    ))
-
-     ;; any *-list.org sitemaps (posts-list.org, blogs-list.org, etc.)
+     (string-match-p  "/tags/" rel-org)
+     ;; Known generated files
+     (member name z/recent-omit-names)
+     ;; Any *-list.org sitemaps
      (string-match-p "-list\\.org\\'" name))))
 
-(defun z/read-org-title+mtime (file)
-  "Return (TITLE . MTIME) for Org FILE.
+;; ── Metadata reader ───────────────────────────────────────────────────────────
 
-TITLE from #+TITLE or file name.
-MTIME is the file's modification time (real 'last updated')."
-  (with-temp-buffer
-    (insert-file-contents file)
-    (org-mode)
-    (let* ((props (org-collect-keywords '("TITLE")))
-           (title-cell (assoc "TITLE" props))
-           (title (or (and title-cell
-                           (car (cdr title-cell)))
-                      (file-name-base file)))
-           (mtime (nth 5 (file-attributes file))))
-      (cons title mtime))))
-
-
-(defun z/read-org-title+date (file)
+(defun z/read-org-meta (file)
   "Return (TITLE . TIME) for Org FILE.
 
-TITLE:
-- from #+TITLE, or file-name if missing.
-
-TIME:
-- from #+DATE if parseable as an org time string,
-- otherwise from file's modification time."
+TITLE: from #+TITLE, or file-name-base when absent.
+TIME : from #+DATE (parsed as an Org time string) when present and
+       parseable; otherwise falls back to the file's modification time.
+       Using #+DATE ensures intentionally-dated content sorts by its
+       canonical publication date rather than an accidental disk mtime."
   (with-temp-buffer
     (insert-file-contents file)
     (org-mode)
-    (let* ((props (org-collect-keywords '("TITLE" "DATE")))
-           ;; TITLE
-           (title-cell (assoc "TITLE" props))
-           (title (or (and title-cell
-                           (car (cdr title-cell)))
-                      (file-name-base file)))
-           ;; DATE
-           (date-cell (assoc "DATE" props))
-           (date-str (and date-cell
-                          (car (cdr date-cell))))
-           (time (or (and date-str
-                          (ignore-errors
-                            (org-time-string-to-time date-str)))
-                     (nth 5 (file-attributes file)))))
+    (let* ((props      (org-collect-keywords '("TITLE" "DATE")))
+           (title      (or (cadr (assoc "TITLE" props))
+                           (file-name-base file)))
+           (date-str   (cadr (assoc "DATE" props)))
+           (time       (or (and date-str
+                                (ignore-errors
+                                  (org-time-string-to-time date-str)))
+                           (file-attribute-modification-time
+                            (file-attributes file)))))
       (cons title time))))
 
-(defun z/generate-recently-updated-org (&optional n)
-  "Generate recently-updated.org in `z-org-root`.
+;; ── Generator ────────────────────────────────────────────────────────────────
 
-Lists top N most recently updated Org pages
-(excluding tags, sitemaps, *-list.org, etc).
-Defaults to N=30."
-  (let* ((count (or n 30))
-         (org-files (directory-files-recursively z-org-root "\\.org\\'"))
-         (items '()))
-    ;; Collect (REL PATH, TITLE, TIME)
-    (dolist (full org-files)
-      (let ((rel (file-relative-name full z-org-root)))
+(defun z/generate-recently-updated-org (&optional n)
+  "Write home/recently-updated.org listing the top N recently updated files.
+N defaults to 30.  Returns the number of entries written."
+  (let* ((count     (or n 30))
+         (org-root  (file-name-as-directory z/site-root))
+         (all-files (directory-files-recursively org-root "\\.org\\'"))
+         (items     '()))
+    ;; Collect (REL TITLE TIME)
+    (dolist (full all-files)
+      (let ((rel (file-relative-name full org-root)))
         (unless (z/recent-omit-org-p rel)
-          (pcase-let* ((`(,title . ,time) (z/read-org-title+mtime full)))
+          (pcase-let ((`(,title . ,time) (z/read-org-meta full)))
             (push (list rel title time) items)))))
-    ;; Sort newest first by TIME
-    (setq items
-          (sort items
-                (lambda (a b)
-                  (time-less-p (nth 2 b) (nth 2 a)))))
-    ;; Trim
+    ;; Sort newest first
+    (setq items (sort items (lambda (a b) (time-less-p (nth 2 b) (nth 2 a)))))
+    ;; Trim to N
     (setq items (cl-subseq items 0 (min count (length items))))
-    ;; Write Org file
+    ;; Write Org
     (with-temp-file (site-path "home/recently-updated.org")
       (insert "#+TITLE: Recently Updated\n"
               "#+OPTIONS: toc:nil num:nil\n\n"
-              "* Recently Updated (top 26 files - per lima's request)\n")
+              (format "* Recently Updated (top %d files)\n" (length items)))
       (dolist (it items)
-        (let* ((rel   (nth 0 it))
-               (title (nth 1 it))
-               (time  (nth 2 it))
+        (let* ((rel     (nth 0 it))
+               (title   (nth 1 it))
+               (time    (nth 2 it))
                (datestr (format-time-string "%Y-%m-%d %H:%M" time)))
           (insert (format "- [[file:%s][%s]] @@html:<span class=\"post-date\">%s</span>@@\n"
-                          rel title datestr))))))
-  (message "Wrote recently-updated.org"))
+                          rel title datestr)))))
+    (length items)))
 
 (provide 'recently-updated)
+
+;;; recently-updated.el ends here

lisp/sidenotes.el

@@ -1,26 +1,40 @@
+;;; sidenotes.el --- Sidenote / no-sidenotes helpers -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Predicates for deciding whether a page should render with sidenotes.
+;; Loaded by build-site.el via (require 'sidenotes).
+;;
+;; NOTE: Do NOT define `site-root' here.  build-site.el owns that definition.
+
+;;; Code:
+
 (defun z/no-sidenotes-file-p (file)
   "Return non-nil if FILE should be rendered without sidenotes.
 
-A file is no-sidenotes if:
-  - It has a #+NO_SIDENOTES: keyword, or
-  - Its FILETAGS contain :NO_SIDENOTES: or :KANBAN:, or
-  - Any top-level heading contains \"KANBAN\"."
+A file suppresses sidenotes when any of the following is true:
+  - It has a #+NO_SIDENOTES: keyword with a non-empty value.
+  - Its FILETAGS contain :NO_SIDENOTES: or :KANBAN:.
+  - Any top-level heading contains the word \"KANBAN\" (case-insensitive)."
   (when (file-exists-p file)
     (with-temp-buffer
       (insert-file-contents file)
       (org-mode)
       (let* ((case-fold-search t)
-             (keywords (org-collect-keywords
-                        '("NO_SIDENOTES" "FILETAGS")))
+             (keywords (org-collect-keywords '("NO_SIDENOTES" "FILETAGS")))
              (flag     (cadr (assoc "NO_SIDENOTES" keywords)))
-             (filetags (cadr (assoc "FILETAGS" keywords))))
+             (filetags (cadr (assoc "FILETAGS"     keywords))))
         (or
+         ;; Explicit keyword present with any non-whitespace value
          (and flag (string-match-p "\\S-" flag))
+         ;; Tag-based suppression
          (and filetags
-              (string-match-p
-               ":\\(NO_SIDENOTES\\|KANBAN\\):"
-               (concat ":" filetags ":")))
+              (string-match-p ":\\(NO_SIDENOTES\\|KANBAN\\):"
+                              (concat ":" filetags ":")))
+         ;; Heading-based suppression
          (save-excursion
            (goto-char (point-min))
            (re-search-forward "^\\*+ .*KANBAN.*" nil t)))))))
+
 (provide 'sidenotes)
+
+;;; sidenotes.el ends here

lisp/sitemaps.el

@@ -1,473 +1,310 @@
-(defvar site-root
-  (file-name-directory
-   (or load-file-name buffer-file-name)))
+;;; sitemaps.el --- Sitemap generators for org-publish -*- lexical-binding: t; -*-
 
-(defun site-path (path)
-  (expand-file-name path site-root))
+;;; Commentary:
+;; Custom :sitemap-function implementations for each publishing project.
+;;
+;; NOTE: Do NOT define `site-root' here.  build-site.el owns that definition.
+
+;;; Code:
+
+(require 'cl-lib)
+(require 'org)
+
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Internal helpers
+;; ─────────────────────────────────────────────────────────────────────────────
+
+(defun z/sitemap--tag-html (tags-raw)
+  "Convert a raw FILETAGS string into an Org-mode HTML inline tag list.
+Returns an empty string when TAGS-RAW is nil or blank."
+  (if (and tags-raw (string-match-p "\\S-" tags-raw))
+      (mapconcat
+       (lambda (tag)
+         (format "@@html:<a href=\"/tags/%s.html\"><span class=\"post-tag\">%s</span></a>@@"
+                 tag tag))
+       (split-string tags-raw ":" t)
+       " ")
+    ""))
+
+(defun z/sitemap--entry-data (link base-dir)
+  "Extract (FULL-PATH DATE-STR TAGS-STR) for a sitemap ENTRY under BASE-DIR.
+LINK is the raw [[file:...][...]] string produced by org-publish."
+  (let* ((filename  (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
+                        (match-string 1 link)
+                      link))
+         (full-path (expand-file-name filename base-dir))
+         (date      (and (file-exists-p full-path)
+                         (org-publish-find-date full-path org-publish-project-alist)))
+         (date-str  (if date (format-time-string "%d-%m-%Y %H:%M" date) "no date"))
+         (tags-raw  (and (file-exists-p full-path)
+                         (with-temp-buffer
+                           (insert-file-contents full-path)
+                           (org-mode)
+                           (cadr (assoc "FILETAGS"
+                                        (org-collect-keywords '("FILETAGS"))))))))
+    (list full-path date-str (z/sitemap--tag-html tags-raw) date)))
+
+(defun z/sitemap--flat-list (title list base-dir section-title categories-rel)
+  "Render a flat bullet-point sitemap.
+TITLE          — org-publish title string
+LIST           — the raw list from org-publish (car is root node)
+BASE-DIR       — absolute path to the project's :base-directory
+SECTION-TITLE  — heading text, e.g. \"Posts\"
+CATEGORIES-REL — relative path to categories.html from this project root"
+  (concat
+   "#+TITLE: " title "\n"
+   "#+OPTIONS: toc:nil num:nil\n\n"
+   (format "See the categories: @@html:<a href=\"%s\">Categories</a>@@\n\n" categories-rel)
+   "* " section-title "\n"
+   (mapconcat
+    (lambda (entry)
+      (when (consp entry)
+        (let* ((link (car entry))
+               (data (z/sitemap--entry-data link base-dir))
+               (date-str (nth 1 data))
+               (tags-str (nth 2 data)))
+          (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s"
+                  link date-str tags-str))))
+    (cdr list)
+    "\n")))
+
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Posts
+;; ─────────────────────────────────────────────────────────────────────────────
 
 (defun z/posts-sitemap (title list)
-  "sitemap that lists post links as bullet points with dates and tags."
-  (concat
-   "#+TITLE: " title "\n"
-   "#+OPTIONS: toc:nil num:nil \n\n"
-   "See the categories: @@html:<a href=\"../home/categories.html\">Categories</a>@@\n\n"
-   "* Posts:\n"
-   (mapconcat
-    (lambda (entry)
-      (let* ((link (car entry))
-             ;; extract relative file name from the link
-             (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                           (match-string 1 link)
-                         link))
-             (full-path (expand-file-name filename (site-path "posts/")))
-             (date-str "no date")
-             (tags-str ""))
-        ;; Get publish date
-        (let ((date (org-publish-find-date full-path org-publish-project-alist)))
-          (when date
-            (setq date-str (format-time-string "%d-%m-%Y %H:%M" date))))
-        ;; Get FILETAGS from file buffer
-        (when (file-exists-p full-path)
-          (with-temp-buffer
-            (insert-file-contents full-path)
-            (org-mode)
-            (let* ((tags (cadr (assoc "FILETAGS" (org-collect-keywords '("FILETAGS"))))))
-              (when tags
-                (setq tags-str (mapconcat (lambda (tag)
-					    (format "@@html:<a href=\"/tags/%s.html\"> <span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                                          (split-string tags ":" t)  ;; <- Splits by ":" and removes empty strings
-                                          " "))))))
-        ;; Final line output
-        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s" link date-str tags-str)))
-    (cdr list)
-    "\n")))
+  "Flat sitemap for org-posts."
+  (z/sitemap--flat-list title list
+                         (site-path "posts/")
+                         "Posts:"
+                         "../home/categories.html"))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Blogs — flat (kept for compatibility, not used as default)
+;; ─────────────────────────────────────────────────────────────────────────────
 
 (defun z/blogs-sitemap (title list)
-  "sitemap that lists blog links as bullet points with dates and tags."
-  (concat
-   "#+TITLE: " title "\n"
-   "#+OPTIONS: toc:nil num:nil \n\n"
-   "See the categories: @@html:<a href=\"../home/categories.html\">Categories</a>@@\n\n"
-   "* Blogs:\n"
-   (mapconcat
-    (lambda (entry)
-      (let* ((link (car entry))
-             ;; extract relative file name from the link
-             (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                           (match-string 1 link)
-                         link))
-             (full-path (expand-file-name filename (site-path "blogs/")))
-             (date-str "no date")
-             (tags-str ""))
-        ;; Get publish date
-        (let ((date (org-publish-find-date full-path org-publish-project-alist)))
-          (when date
-            (setq date-str (format-time-string "%d-%m-%Y %H:%M" date))))
-        ;; Get FILETAGS from file buffer
-        (when (file-exists-p full-path)
-          (with-temp-buffer
-            (insert-file-contents full-path)
-            (org-mode)
-            (let* ((tags (cadr (assoc "FILETAGS" (org-collect-keywords '("FILETAGS"))))))
-              (when tags
-                (setq tags-str (mapconcat (lambda (tag)
-                                            (format "@@html:<a href=\"/tags/%s.html\"> <span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                                          (split-string tags ":" t)  ;; <- Splits by ":" and removes empty strings
-                                          " "))))))
-        ;; Final line output
-        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s" link date-str tags-str)))
-    (cdr list)
-    "\n")))
-
+  "Flat sitemap for org-blogs (use z/blogs-grouped-sitemap for the default)."
+  (z/sitemap--flat-list title list
+                         (site-path "blogs/")
+                         "Blogs:"
+                         "../home/categories.html"))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Blogs — grouped by year → month
+;; ─────────────────────────────────────────────────────────────────────────────
 
 (defun z/blogs-grouped-sitemap (title list)
-  "Sitemap grouped by year and month with dates and FILETAGS."
+  "Sitemap for org-blogs grouped by year and month, newest first."
   (let ((data (make-hash-table :test 'equal)))
 
-    ;; STEP 1: Collect entries into (year -> month -> entries)
+    ;; Collect into  year-key → month-key → list of (link date-str tags-str time)
     (dolist (entry (cdr list))
       (when (consp entry)
-        (let* ((link (car entry))
-               (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                             (match-string 1 link)
-                           link))
-               (full-path (expand-file-name filename (site-path "blogs/")))
-               (date (when (file-exists-p full-path)
-                       (org-publish-find-date full-path org-publish-project-alist))))
+        (let* ((link      (car entry))
+               (ed        (z/sitemap--entry-data link (site-path "blogs/")))
+               (full-path (nth 0 ed))
+               (date-str  (nth 1 ed))
+               (tags-str  (nth 2 ed))
+               (time      (nth 3 ed)))
+          (when time
+            (let* ((year  (format-time-string "%Y"    time))
+                   (month (format-time-string "%B %Y" time))
+                   (year-table (or (gethash year data)
+                                   (puthash year (make-hash-table :test 'equal) data))))
+              (puthash month
+                       (cons (list link date-str tags-str time)
+                             (gethash month year-table))
+                       year-table))))))
 
-          (when date
-            (let* ((year (format-time-string "%Y" date))
-                   (month (format-time-string "%B %Y" date))
-                   (date-str (format-time-string "%d-%m-%Y %H:%M" date))
-                   (tags-str ""))
-
-              ;; Get tags
-              (when (file-exists-p full-path)
-                (with-temp-buffer
-                  (insert-file-contents full-path)
-                  (org-mode)
-                  (let ((tags (cadr (assoc "FILETAGS"
-                                           (org-collect-keywords '("FILETAGS"))))))
-                    (when tags
-                      (setq tags-str
-                            (mapconcat
-                             (lambda (tag)
-                               (format "@@html:<a href=\"/tags/%s.html\"> \
-<span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                             (split-string tags ":" t)
-                             " "))))))
-
-              ;; Insert into hash table
-              (let ((year-table (or (gethash year data)
-                                    (puthash year (make-hash-table :test 'equal) data))))
-                (let ((month-list (gethash month year-table)))
-                  (puthash month
-                           (cons (list link date-str tags-str date)
-                                 month-list)
-                           year-table))))))))
-
-    ;; STEP 2: Render output
-    (let ((output (concat
-                   "#+TITLE: " title "\n"
-                   "#+OPTIONS: toc:nil num:nil \n\n"
-                   "See the categories: @@html:<a href=\"../home/categories.html\">Categories</a>@@\n\n")))
-
-      ;; Sort years descending
+    ;; Render
+    (let ((output (concat "#+TITLE: " title "\n"
+                          "#+OPTIONS: toc:nil num:nil\n\n"
+                          "See the categories: @@html:<a href=\"../home/categories.html\">Categories</a>@@\n\n")))
       (dolist (year (sort (hash-table-keys data) #'string>))
         (setq output (concat output "* " year "\n"))
-
         (let ((year-table (gethash year data)))
-
-          ;; Sort months by actual date (descending)
-          (dolist (month
-                   (sort (hash-table-keys year-table)
-                         (lambda (a b)
-                           (time-less-p
-                            (date-to-time (concat "01 " b))
-                            (date-to-time (concat "01 " a))))))
-
+          (dolist (month (sort (hash-table-keys year-table)
+                               (lambda (a b)
+                                 (time-less-p
+                                  (date-to-time (concat "01 " b))
+                                  (date-to-time (concat "01 " a))))))
             (setq output (concat output "\n** " month "\n"))
-
-            ;; Sort entries by date descending
-            (dolist (entry
-                     (sort (gethash month year-table)
-                           (lambda (a b)
-                             (time-less-p (nth 3 b) (nth 3 a)))))
-
-              (let ((link (nth 0 entry))
-                    (date-str (nth 1 entry))
-                    (tags-str (nth 2 entry)))
-
-                (setq output
-                      (concat output
-                              (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
-                                      link date-str tags-str))))))))
-
+            (dolist (entry (sort (gethash month year-table)
+                                 (lambda (a b)
+                                   (time-less-p (nth 3 b) (nth 3 a)))))
+              (setq output
+                    (concat output
+                            (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
+                                    (nth 0 entry)
+                                    (nth 1 entry)
+                                    (nth 2 entry))))))))
       output)))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Books
+;; ─────────────────────────────────────────────────────────────────────────────
+
 (defun z/books-sitemap (title list)
-  "sitemap that lists books."
-  (concat
-   "#+TITLE: " title "\n"
-   "#+OPTIONS: toc:nil num:nil \n\n"
-   "See the categories: @@html:<a href=\"../home/categories.html\">Categories</a>@@\n\n"
-   "* Book Notes:\n"
-   (mapconcat
-    (lambda (entry)
-      (let* ((link (car entry))
-             ;; extract relative file name from the link
-             (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                           (match-string 1 link)
-                         link))
-             (full-path (expand-file-name filename (site-path "books/")))
-             (date-str "no date")
-             (tags-str ""))
-        ;; Get publish date
-        (let ((date (org-publish-find-date full-path org-publish-project-alist)))
-          (when date
-            (setq date-str (format-time-string "%d-%m-%Y %H:%M" date))))
-        ;; Get FILETAGS from file buffer
-        (when (file-exists-p full-path)
-          (with-temp-buffer
-            (insert-file-contents full-path)
-            (org-mode)
-            (let* ((tags (cadr (assoc "FILETAGS" (org-collect-keywords '("FILETAGS"))))))
-              (when tags
-                (setq tags-str (mapconcat (lambda (tag)
-                                            (format "@@html:<a href=\"/tags/%s.html\"> <span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                                          (split-string tags ":" t)  ;; <- Splits by ":" and removes empty strings
-                                          " "))))))
-        ;; Final line output
-        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s" link date-str tags-str)))
-    (cdr list)
-    "\n")))
+  "Flat sitemap for org-books."
+  (z/sitemap--flat-list title list
+                         (site-path "books/")
+                         "Book Notes:"
+                         "../home/categories.html"))
+
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Year-scoped sitemaps (generic helper)
+;; ─────────────────────────────────────────────────────────────────────────────
+
+(defun z/year-grouped-sitemap (title list year base-dir categories-rel)
+  "Generic year-scoped, month-grouped sitemap.
+YEAR is a string like \"2025\".  BASE-DIR is the project root.
+CATEGORIES-REL is the relative href to categories.html."
+  (let ((output (concat "#+TITLE: " title "\n"
+                        "#+OPTIONS: toc:nil num:nil\n\n"
+                        (format "See the categories: @@html:<a href=\"%s\">Categories</a>@@\n\n"
+                                categories-rel)
+                        "* " year "\n"))
+        (current-month nil))
+    (dolist (entry (cdr list))
+      (when (consp entry)
+        (let* ((link      (car entry))
+               (ed        (z/sitemap--entry-data link base-dir))
+               (date-str  (nth 1 ed))
+               (tags-str  (nth 2 ed))
+               (time      (nth 3 ed))
+               (month-str (if time (format-time-string "%B %Y" time) "No date")))
+          (unless (equal month-str current-month)
+            (setq current-month month-str)
+            (setq output (concat output "\n** " month-str "\n")))
+          (setq output
+                (concat output
+                        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
+                                link date-str tags-str))))))
+    output))
 
 (defun z/2025-sitemap (title list)
-  "Sitemap that lists 2025 posts grouped by month, with dates and FILETAGS."
-  (let ((output (concat
-                 "#+TITLE: " title "\n"
-                 "#+OPTIONS: toc:nil num:nil \n\n"
-                 "See the categories: @@html:<a href=\"../../home/categories.html\">Categories</a>@@\n\n"
-                 "* 2025\n"))
-        (current-month nil))
-
-    ;; `list` is what org-publish passes in; we skip its car (top-level title node)
-    (dolist (entry (cdr list))
-      ;; In this setup each ENTRY is usually (LINK . OTHER-STUFF)
-      (when (consp entry)
-        (let* ((link (car entry))
-               ;; Extract relative filename from the [[file:...][...]] link
-               (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                             (match-string 1 link)
-                           link))
-               (full-path (expand-file-name filename (site-path "blogs/2025/")))
-               (date (when (file-exists-p full-path)
-                       (org-publish-find-date full-path org-publish-project-alist)))
-               (date-str (if date
-                             (format-time-string "%d-%m-%Y %H:%M" date)
-                           "no date"))
-               (month-str (if date
-                              (format-time-string "%B %Y" date) ; e.g. "August 2025"
-                            "No date"))
-               (tags-str ""))
-
-          ;; Collect FILETAGS from the file
-          (when (file-exists-p full-path)
-            (with-temp-buffer
-              (insert-file-contents full-path)
-              (org-mode)
-              (let ((tags (cadr (assoc "FILETAGS"
-                                       (org-collect-keywords '("FILETAGS"))))))
-                (when tags
-                  (setq tags-str
-                        (mapconcat
-                         (lambda (tag)
-                           (format "@@html:<a href=\"/tags/%s.html\"> \
-<span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                         (split-string tags ":" t)
-                         " "))))))
-
-          ;; Insert month heading whenever month changes
-          (unless (equal month-str current-month)
-            (setq current-month month-str)
-            (setq output (concat output "\n** " month-str "\n")))
-
-          ;; Insert the actual entry
-          (setq output
-                (concat output
-                        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
-                                link date-str tags-str))))))
-
-    output))
+  "Sitemap for blogs/2025/ grouped by month."
+  (z/year-grouped-sitemap title list "2025"
+                           (site-path "blogs/2025/")
+                           "../../home/categories.html"))
 
 (defun z/2026-sitemap (title list)
-  "Sitemap that lists 2026 blogs grouped by month, with dates and FILETAGS."
-  (let ((output (concat
-                 "#+TITLE: " title "\n"
-                 "#+OPTIONS: toc:nil num:nil \n\n"
-                 "See the categories: @@html:<a href=\"../../home/categories.html\">Categories</a>@@\n\n"
-                 "* 2026\n"))
-        (current-month nil))
-
-    (dolist (entry (cdr list))
-      (when (consp entry)
-        (let* ((link (car entry))
-               (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                             (match-string 1 link)
-                           link))
-               (full-path (expand-file-name filename (site-path "blogs/2026/")))
-               (date (when (file-exists-p full-path)
-                       (org-publish-find-date full-path org-publish-project-alist)))
-               (date-str (if date
-                             (format-time-string "%d-%m-%Y %H:%M" date)
-                           "no date"))
-               (month-str (if date
-                              (format-time-string "%B %Y" date)
-                            "No date"))
-               (tags-str ""))
-
-          (when (file-exists-p full-path)
-            (with-temp-buffer
-              (insert-file-contents full-path)
-              (org-mode)
-              (let ((tags (cadr (assoc "FILETAGS"
-                                       (org-collect-keywords '("FILETAGS"))))))
-                (when tags
-                  (setq tags-str
-                        (mapconcat
-                         (lambda (tag)
-                           (format "@@html:<a href=\"/tags/%s.html\"> \
-<span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                         (split-string tags ":" t)
-                         " "))))))
-
-          (unless (equal month-str current-month)
-            (setq current-month month-str)
-            (setq output (concat output "\n** " month-str "\n")))
-
-          (setq output
-                (concat output
-                        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
-                                link date-str tags-str))))))
-
-    output))
-
+  "Sitemap for blogs/2026/ grouped by month."
+  (z/year-grouped-sitemap title list "2026"
+                           (site-path "blogs/2026/")
+                           "../../home/categories.html"))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Career
+;; ─────────────────────────────────────────────────────────────────────────────
 
 (defun z/career-sitemap (title list)
-  "Sitemap that lists careers posts grouped by month, with dates and FILETAGS."
-  (let ((output (concat
-                 "#+TITLE: " title "\n"
-                 "#+OPTIONS: toc:nil num:nil \n\n"
-                 "See the categories: @@html:<a href=\"../../home/categories.html\">Categories</a>@@\n\n"
-		 "See the following page for more details: @@html:<a href=\"./career-intro.html\">Career Intro</a>@@\n"
-		 ))
-        (current-month nil))
-
-    (dolist (entry (cdr list))
-      (when (consp entry)
-        (let* ((link (car entry))
-               (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                             (match-string 1 link)
-                           link))
-               (full-path (expand-file-name filename (site-path "posts/career/")))
-               (date (when (file-exists-p full-path)
-                       (org-publish-find-date full-path org-publish-project-alist)))
-               (date-str (if date
-                             (format-time-string "%d-%m-%Y %H:%M" date)
-                           "no date"))
-               (month-str (if date
-                              (format-time-string "%B %Y" date) ; e.g. "August 2025"
-                            "No date"))
-               (tags-str ""))
-
-          (when (file-exists-p full-path)
-            (with-temp-buffer
-              (insert-file-contents full-path)
-              (org-mode)
-              (let ((tags (cadr (assoc "FILETAGS"
-                                       (org-collect-keywords '("FILETAGS"))))))
-                (when tags
-                  (setq tags-str
-                        (mapconcat
-                         (lambda (tag)
-                           (format "@@html:<a href=\"/tags/%s.html\"> \
-<span class=\"post-tag\">%s</span> </a>@@" tag tag))
-                         (split-string tags ":" t)
-                         " "))))))
-
-          ;; Insert month heading whenever month changes
-          (unless (equal month-str current-month)
-            (setq current-month month-str)
-            (setq output (concat output "\n** " month-str "\n")))
-
-          (setq output
-                (concat output
-                        (format "- %s @@html:<span class=\"post-date\">%s</span>@@ %s\n"
-                                link date-str tags-str))))))
-
-    output))
-
+  "Sitemap for posts/career/ grouped by month."
+  (concat
+   (z/year-grouped-sitemap title list ""
+                            (site-path "posts/career/")
+                            "../../home/categories.html")
+   "\nSee the following page for more details: @@html:<a href=\"./career-intro.html\">Career Intro</a>@@\n"))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; Categories
+;; ─────────────────────────────────────────────────────────────────────────────
 
 (defun z/categories-sitemap (title _list)
-  "Generate a categories page by scanning tags across org-posts and org-blogs."
+  "Generate a categories overview by scanning tags across posts and blogs."
   (let* ((expanded (org-publish-expand-projects org-publish-project-alist))
          (posts    (assoc "org-posts" expanded))
          (blogs    (assoc "org-blogs" expanded))
-         ;; DO NOT set :exclude to "" — it excludes everything
-         (files (cl-remove-duplicates
-                 (append (and posts (org-publish-get-base-files posts))
-                         (and blogs (org-publish-get-base-files blogs)))
-                 :test #'file-equal-p))
-         ;; optional: drop the generated sitemaps
-         (files (cl-remove-if
-                 (lambda (f)
-                   (member (file-name-nondirectory f)
-                           '("posts-list.org" "blogs-list.org" "sitemap.org" "categories.org")))
-                 files))
-         (counts (make-hash-table :test 'equal)))
-    ;;(message "files I will scan: %S" files)
+         (files    (cl-remove-if
+                    (lambda (f)
+                      (member (file-name-nondirectory f)
+                              '("posts-list.org" "blogs-list.org"
+                                "sitemap.org"    "categories.org")))
+                    (cl-remove-duplicates
+                     (append (and posts (org-publish-get-base-files posts))
+                             (and blogs (org-publish-get-base-files blogs)))
+                     :test #'file-equal-p)))
+         (counts   (make-hash-table :test 'equal)))
     (dolist (f files)
       (when (file-readable-p f)
         (with-temp-buffer
           (insert-file-contents f)
           (org-mode)
-          (let* ((kw (org-collect-keywords '("FILETAGS" "TAGS")))
-                 (raw (car (or (cdr (assoc "FILETAGS" kw))
-                               (cdr (assoc "TAGS" kw))))))
+          (let* ((kw  (org-collect-keywords '("FILETAGS" "TAGS")))
+                 (raw (cadr (or (assoc "FILETAGS" kw)
+                                (assoc "TAGS"     kw)))))
             (when raw
               (dolist (tag (split-string raw ":" t))
                 (puthash tag (1+ (gethash tag counts 0)) counts)))))))
-
     (let (tags)
       (maphash (lambda (k _) (push k tags)) counts)
       (setq tags (sort tags #'string-lessp))
       (concat
-       "#+TITLE: " title "\n#+OPTIONS: toc:nil num:nil title:nil\n\n* Categories (Includes both blogs and posts)\n"
+       "#+TITLE: " title "\n#+OPTIONS: toc:nil num:nil title:nil\n\n"
+       "* Categories (Includes both blogs and posts)\n"
        (if tags
-	   (mapconcat
-	    (lambda (tag)
-	      (format "- [[file:../tags/%s.org][@@html:<span class=\"post-tag\">%s</span>@@]] (%d)"
-		      (z/tag-slug tag) tag (gethash tag counts))
-	      )
-	    tags
-	    "\n")
+           (mapconcat
+            (lambda (tag)
+              (format "- [[file:../tags/%s.org][@@html:<span class=\"post-tag\">%s</span>@@]] (%d)"
+                      (z/tag-slug tag) tag (gethash tag counts)))
+            tags
+            "\n")
          "_No tags found yet._")))))
 
+;; ─────────────────────────────────────────────────────────────────────────────
+;; WIP sitemap
+;; ─────────────────────────────────────────────────────────────────────────────
+
 (defun z/wip-file-p (file)
-  "Return non-nil if FILE should be treated as WIP.
-A file is WIP if:
-  - It has a #+WIP: keyword with any non-empty value, or
-  - Its FILETAGS contain :WIP:, or
-  - Any top-level heading contains the string \"WIP\" (case-insensitive)."
+  "Return non-nil if FILE is marked as work-in-progress.
+
+A file is WIP when any of the following is true:
+  - It has a #+WIP: keyword with a non-empty value.
+  - Its FILETAGS contain :WIP:.
+  - Any top-level heading contains \"WIP\" (case-insensitive)."
   (when (file-exists-p file)
     (with-temp-buffer
       (insert-file-contents file)
       (org-mode)
       (let* ((case-fold-search t)
              (keywords (org-collect-keywords '("WIP" "FILETAGS")))
-             (wip      (cadr (assoc "WIP" keywords)))
+             (wip      (cadr (assoc "WIP"      keywords)))
              (filetags (cadr (assoc "FILETAGS" keywords))))
         (or
          (and wip (string-match-p "\\S-" wip))
-         (and filetags
-              (string-match-p ":WIP:" (concat ":" filetags ":")))
+         (and filetags (string-match-p ":WIP:" (concat ":" filetags ":")))
          (save-excursion
            (goto-char (point-min))
            (re-search-forward "^\\*+ .*WIP.*" nil t)))))))
 
-
 (defun z/wip-sitemap (title list)
-  "Sitemap that lists only entries whose source files are WIP."
-  (let* ((items
-          (delq
-           nil
-           (mapcar
-            (lambda (entry)
-              (when (consp entry)
-                (let* ((link (car entry))
-                       (filename (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
-                                     (match-string 1 link)
-                                   link))
-                       (full-path (expand-file-name filename site-root)))
-                  (when (z/wip-file-p full-path)
-                    (let* ((date (org-publish-find-date full-path org-publish-project-alist))
-                           (date-str (if date
-                                         (format-time-string "%d-%m-%Y %H:%M" date)
-                                       "")))
-                      (format "- %s @@html:<span class=\"post-date\">%s</span>@@"
-                              link date-str))))))
-            (cdr list)))))   ;; skip sitemap root
-    (concat
-     "#+TITLE: " title "\n"
-     "#+OPTIONS: toc:nil num:nil\n\n"
-     "* Work in progress\n"
-     (if items
-         (mapconcat #'identity items "\n")
-       "No items currently marked as WIP.\n"))))
-
+  "Sitemap listing only entries whose source files are marked WIP."
+  (let ((items
+         (delq nil
+               (mapcar
+                (lambda (entry)
+                  (when (consp entry)
+                    (let* ((link      (car entry))
+                           (filename  (if (string-match "\\[\\[file:\\([^]]+\\)\\]" link)
+                                          (match-string 1 link)
+                                        link))
+                           (full-path (expand-file-name filename z/site-root)))
+                      (when (z/wip-file-p full-path)
+                        (let* ((date     (org-publish-find-date full-path org-publish-project-alist))
+                               (date-str (if date
+                                             (format-time-string "%d-%m-%Y %H:%M" date)
+                                           "")))
+                          (format "- %s @@html:<span class=\"post-date\">%s</span>@@"
+                                  link date-str))))))
+                (cdr list)))))
+    (concat "#+TITLE: " title "\n"
+            "#+OPTIONS: toc:nil num:nil\n\n"
+            "* Work in progress\n"
+            (if items
+                (mapconcat #'identity items "\n")
+              "No items currently marked as WIP.\n"))))
 
 (provide 'sitemaps)
+
+;;; sitemaps.el ends here

lisp/tags.el

@@ -1,10 +1,26 @@
+;;; tags.el --- Tag index and HTML helpers -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Collects FILETAGS from posts/blogs, generates tags/*.org pages, and
+;; injects tag HTML into exported pages.
+;;
+;; NOTE: Do NOT define `site-root' here.  build-site.el owns that definition.
+
+;;; Code:
+
+(require 'cl-lib)
+(require 'org)
+
+;; ── Slug ─────────────────────────────────────────────────────────────────────
+
 (defun z/tag-slug (s)
-  "Turn a tag into a safe filename."
-  (let ((down (downcase s)))
-    (replace-regexp-in-string "[^a-z0-9]+" "-" down)))
+  "Return a URL-safe filename slug for tag S."
+  (replace-regexp-in-string "[^a-z0-9]+" "-" (downcase s)))
+
+;; ── File collection ───────────────────────────────────────────────────────────
 
 (defun z/collect-post-files ()
-  "Return all .org files from org-posts and org-blogs."
+  "Return all .org source files from the org-posts and org-blogs projects."
   (let* ((expanded (org-publish-expand-projects org-publish-project-alist))
          (posts    (assoc "org-posts" expanded))
          (blogs    (assoc "org-blogs" expanded)))
@@ -13,66 +29,79 @@
              (and blogs (org-publish-get-base-files blogs)))
      :test #'file-equal-p)))
 
+;; ── Tag index ─────────────────────────────────────────────────────────────────
+
+(defconst z/generated-org-names
+  '("posts-list.org" "blogs-list.org" "sitemap.org" "categories.org"
+    "recently-updated.org" "wip.org")
+  "Generated Org files that should never be indexed for tags.")
+
 (defun z/gather-tag-index ()
-  "Return hash: tag -> list of (FILE TITLE DATE-ISO)."
+  "Return a hash-table mapping tag -> list of (FILE TITLE DATE-ISO)."
   (let ((idx (make-hash-table :test 'equal)))
     (dolist (f (z/collect-post-files))
       (when (and (string-match-p "\\.org\\'" f)
                  (file-readable-p f)
-                 ;; ignore generated lists
                  (not (member (file-name-nondirectory f)
-                              '("posts-list.org" "blogs-list.org" "sitemap.org" "categories.org"))))
+                              z/generated-org-names)))
         (with-temp-buffer
           (insert-file-contents f)
           (org-mode)
-          (let* ((kw (org-collect-keywords '("TITLE" "FILETAGS" "TAGS" "DATE")))
-                 (title (or (car (cdr (assoc "TITLE" kw)))
-                            (file-name-base f)))
-                 (date  (or (car (cdr (assoc "DATE" kw))) "")) ;; optional
-                 (raw   (car (or (cdr (assoc "FILETAGS" kw))
-                                 (cdr (assoc "TAGS" kw))))))
+          (let* ((kw    (org-collect-keywords '("TITLE" "FILETAGS" "TAGS" "DATE")))
+                 (title (or (cadr (assoc "TITLE" kw)) (file-name-base f)))
+                 (date  (or (cadr (assoc "DATE"  kw)) ""))
+                 (raw   (cadr (or (assoc "FILETAGS" kw)
+                                  (assoc "TAGS"     kw)))))
             (when raw
               (dolist (tag (split-string raw ":" t))
                 (push (list f title date) (gethash tag idx))))))))
     idx))
 
+;; ── Tag page writer ───────────────────────────────────────────────────────────
+
 (defun z/write-tag-pages ()
-  "Generate tags/*.org pages listing posts for each tag."
-  (let* ((site-root (expand-file-name "~/master-folder/org_files/org_web/"))
-         (tags-dir  (expand-file-name "tags" site-root)))
+  "Generate tags/*.org pages, one per tag.
+Returns the number of tag pages written."
+  (let* ((tags-dir (site-path "tags/"))
+         (idx      (z/gather-tag-index))
+         (count    0))
     (unless (file-directory-p tags-dir)
       (make-directory tags-dir t))
-    (let ((idx (z/gather-tag-index)))
-      (maphash
-       (lambda (tag items)
-         (let* ((slug (z/tag-slug tag))
-                (outfile (expand-file-name (format "%s.org" slug) tags-dir)))
-           (with-temp-file outfile
-             (insert (format "#+TITLE: Tag: %s\n#+OPTIONS: toc:nil num:nil title:nil \n\n* Posts tagged %s\n"
-                             tag tag))
-             ;; sort newest first if DATE present
-             (setq items (sort items (lambda (a b) (string> (nth 2 a) (nth 2 b)))))
-             (dolist (it items)
-               (let* ((file (nth 0 it))
-                      (title (nth 1 it))
-                      (rel   (file-relative-name file tags-dir)))
-                 ;; link to the source .org; org-publish will rewrite to the .html
-                 (insert (format "- [[file:%s][%s]]\n" rel title)))))))
-       idx)
-      )))
+    (maphash
+     (lambda (tag items)
+       (let* ((slug    (z/tag-slug tag))
+              (outfile (expand-file-name (format "%s.org" slug) tags-dir)))
+         (with-temp-file outfile
+           (insert (format "#+TITLE: Tag: %s\n#+OPTIONS: toc:nil num:nil title:nil\n\n* Posts tagged %s\n"
+                           tag tag))
+           ;; Sort newest first
+           (setq items (sort items (lambda (a b) (string> (nth 2 a) (nth 2 b)))))
+           (dolist (it items)
+             (let* ((file  (nth 0 it))
+                    (title (nth 1 it))
+                    (rel   (file-relative-name file tags-dir)))
+               (insert (format "- [[file:%s][%s]]\n" rel title)))))
+         (cl-incf count)))
+     idx)
+    count))
+
+;; ── HTML tag rendering ────────────────────────────────────────────────────────
 
 (defun z/filetags-html (info)
-  "Return an HTML snippet for FILETAGS from INFO, or nil if none."
+  "Return an HTML <div class=\"filetags\"> snippet from export INFO, or nil."
   (let ((tags (plist-get info :filetags)))
     (when tags
       (format
        "<div class=\"filetags\">%s</div>\n"
-       (mapconcat (lambda (tag)
-                    (format "<a href=\"/home/categories.html\"> <span class=\"post-tag\">%s</span> </a>" tag))
-                  tags " ")))))
+       (mapconcat
+        (lambda (tag)
+          (format "<a href=\"/home/categories.html\"><span class=\"post-tag\">%s</span></a>"
+                  tag))
+        tags
+        " ")))))
 
 (defun z/insert-filetags-after-title (output backend info)
-  "Insert FILETAGS after the first <h1 class=\"title\"> in OUTPUT."
+  "Insert FILETAGS HTML after the first <h1 class=\"title\"> in OUTPUT."
   (if (org-export-derived-backend-p backend 'html)
       (let ((block (z/filetags-html info)))
         (if (and block
@@ -81,5 +110,6 @@
           output))
     output))
 
-
 (provide 'tags)
+
+;;; tags.el ends here