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