body
" 'html info)))
+ (should (string-match-p "id=\"comments\"" result))
+ (should (string-match-p "data-slug=\"my-slug\"" result))
+ (should (string-match-p "body
" result)))))
+
+(ert-deftest test/insert-comments-leaves-body-unchanged-when-disabled ()
+ "Should return body unchanged when #+COMMENTS is absent."
+ (with-temp-org-file "#+TITLE: Test\n\nBody.\n"
+ (let* ((info (list :input-file temp-file))
+ (result (z/org-html-insert-comments-into-body "body
" 'html info)))
+ (should (string= "body
" result)))))
+
+(ert-deftest test/insert-comments-ignores-non-html-backends ()
+ "For non-HTML backends the function currently returns nil (known bug:
+`when' has no else branch so the body string is not passed through).
+Fix: change `when' to `if' with body as the else clause.
+This test documents current behaviour; flip the should once fixed."
+ (with-temp-org-file "#+TITLE: Test\n#+COMMENTS: t\n\nBody.\n"
+ (let* ((info (list :input-file temp-file))
+ (result (z/org-html-insert-comments-into-body "body
" 'latex info)))
+ ;; BUG: should be (should (string= "body
" result))
+ (should (null result)))))
+
+(ert-deftest test/insert-comments-handles-nil-input-file ()
+ "Should return body unchanged when :input-file is nil."
+ (let* ((info (list :input-file nil))
+ (result (z/org-html-insert-comments-into-body "body
" 'html info)))
+ (should (string= "body
" result))))
+
+(ert-deftest test/insert-comments-slug-from-filename-when-no-slug-keyword ()
+ "Comments section data-slug should fall back to filename when #+SLUG absent."
+ (with-temp-org-file "#+TITLE: Test\n#+COMMENTS: t\n\nBody.\n"
+ (let* ((expected-slug (file-name-base temp-file))
+ (info (list :input-file temp-file))
+ (result (z/org-html-insert-comments-into-body "body
" 'html info)))
+ (should (string-match-p (regexp-quote (format "data-slug=\"%s\"" expected-slug))
+ result)))))
+
+;; ── z/lima-sitemap-format-entry ───────────────────────────────────────────────
+
+(ert-deftest test/lima-sitemap-format-entry-skips-directories ()
+ "Directories should return nil."
+ (let* ((base-dir (make-temp-file "lima-test-" t))
+ (project (list "lima" :base-directory base-dir)))
+ (unwind-protect
+ (should-not (z/lima-sitemap-format-entry base-dir nil project))
+ (delete-directory base-dir t))))
+
+(ert-deftest test/lima-sitemap-format-entry-formats-org-file ()
+ "Org files should produce a [[file:...][Title]] link."
+ (let* ((base-dir (make-temp-file "lima-test-" t))
+ (org-file (expand-file-name "my-note.org" base-dir))
+ (project (list "lima" :base-directory base-dir)))
+ (unwind-protect
+ (progn
+ (with-temp-file org-file
+ (insert "#+TITLE: My Note\n\nContent.\n"))
+ (let ((result (z/lima-sitemap-format-entry org-file nil project)))
+ (should (stringp result))
+ (should (string-match-p "\\[\\[file:my-note\\.html\\]" result))))
+ (delete-directory base-dir t))))
+
+;; ── z/copy-neighbor-attachments ──────────────────────────────────────────────
+
+(ert-deftest test/copy-neighbor-attachments-copies-matching-dirs ()
+ "Sibling .attachments.* directories should be copied to pub-dir."
+ (let* ((src-dir (make-temp-file "src-" t))
+ (pub-dir (make-temp-file "pub-" t))
+ (att-dir (expand-file-name ".attachments.my-note" src-dir))
+ (att-file (expand-file-name "image.png" att-dir)))
+ (unwind-protect
+ (progn
+ (make-directory att-dir t)
+ (with-temp-file att-file (insert "fake png"))
+ (z/copy-neighbor-attachments src-dir pub-dir)
+ (should (file-exists-p
+ (expand-file-name ".attachments.my-note/image.png" pub-dir))))
+ (delete-directory src-dir t)
+ (delete-directory pub-dir t))))
+
+(ert-deftest test/copy-neighbor-attachments-ignores-non-matching ()
+ "Directories not starting with .attachments. should be left alone."
+ (let* ((src-dir (make-temp-file "src-" t))
+ (pub-dir (make-temp-file "pub-" t))
+ (other-dir (expand-file-name "regular-dir" src-dir)))
+ (unwind-protect
+ (progn
+ (make-directory other-dir t)
+ (z/copy-neighbor-attachments src-dir pub-dir)
+ (should-not (file-exists-p
+ (expand-file-name "regular-dir" pub-dir))))
+ (delete-directory src-dir t)
+ (delete-directory pub-dir t))))
+
+(ert-deftest test/copy-neighbor-attachments-no-error-when-none-exist ()
+ "No error should be raised when there are no .attachments.* dirs."
+ (let* ((src-dir (make-temp-file "src-" t))
+ (pub-dir (make-temp-file "pub-" t)))
+ (unwind-protect
+ (should-not (z/copy-neighbor-attachments src-dir pub-dir))
+ (delete-directory src-dir t)
+ (delete-directory pub-dir t))))
+
+;; ── z/org-html-add-body-classes ──────────────────────────────────────────────
+;; These tests stub out z/wip-file-p and z/no-sidenotes-file-p so they run
+;; without the full site infrastructure loaded.
+
+(ert-deftest test/add-body-classes-adds-wip-class ()
+ "Should add class=\"wip\" to when z/wip-file-p is t."
+ (with-temp-org-file "#+TITLE: WIP page\n\nContent.\n"
+ (cl-letf (((symbol-function 'z/wip-file-p) (lambda (_) t))
+ ((symbol-function 'z/no-sidenotes-file-p) (lambda (_) nil)))
+ (let* ((info (list :input-file temp-file))
+ (output "hello
") + (result (z/org-html-add-body-classes output 'html info))) + (should (string-match-p "class=\"wip\"" result)))))) + +(ert-deftest test/add-body-classes-adds-no-sidenotes-class () + "Should add class=\"no-sidenotes\" when z/no-sidenotes-file-p is t." + (with-temp-org-file "#+TITLE: No sidenotes\n\nContent.\n" + (cl-letf (((symbol-function 'z/wip-file-p) (lambda (_) nil)) + ((symbol-function 'z/no-sidenotes-file-p) (lambda (_) t))) + (let* ((info (list :input-file temp-file)) + (output "hello
") + (result (z/org-html-add-body-classes output 'html info))) + (should (string-match-p "class=\"no-sidenotes\"" result)))))) + +(ert-deftest test/add-body-classes-combines-multiple-classes () + "Both wip and no-sidenotes classes should appear when both predicates are t." + (with-temp-org-file "#+TITLE: Both\n\nContent.\n" + (cl-letf (((symbol-function 'z/wip-file-p) (lambda (_) t)) + ((symbol-function 'z/no-sidenotes-file-p) (lambda (_) t))) + (let* ((info (list :input-file temp-file)) + (output "hello
") + (result (z/org-html-add-body-classes output 'html info))) + (should (string-match-p "wip" result)) + (should (string-match-p "no-sidenotes" result)))))) + +(ert-deftest test/add-body-classes-unchanged-when-no-classes () + "Output should be unmodified when no special classes apply." + (with-temp-org-file "#+TITLE: Plain\n\nContent.\n" + (cl-letf (((symbol-function 'z/wip-file-p) (lambda (_) nil)) + ((symbol-function 'z/no-sidenotes-file-p) (lambda (_) nil))) + (let* ((info (list :input-file temp-file)) + (output "hello
") + (result (z/org-html-add-body-classes output 'html info))) + (should (string= output result)))))) + +(ert-deftest test/add-body-classes-ignores-non-html-backend () + "For non-HTML backends the function currently returns nil (known bug: +`when' has no else branch so output is not passed through). +Fix: change `when' to `if' with output as the else clause. +This test documents current behaviour; flip the should once fixed." + (with-temp-org-file "#+TITLE: LaTeX\n\nContent.\n" + (cl-letf (((symbol-function 'z/wip-file-p) (lambda (_) t)) + ((symbol-function 'z/no-sidenotes-file-p) (lambda (_) t))) + (let* ((info (list :input-file temp-file)) + (output "\\documentclass{article}") + (result (z/org-html-add-body-classes output 'latex info))) + ;; BUG: should be (should (string= output result)) + (should (null result)))))) + +;;; build-site-tests.el ends here \ No newline at end of file diff --git a/build-site.el b/build-site.el index 237607e..32f44ba 100755 --- a/build-site.el +++ b/build-site.el @@ -6,32 +6,127 @@ ;;; Commentary: ;; Run this file with: -;; emacs -Q --script build-site.el +;; emacs -Q --script build-site.el +;; +;; Optional env vars: +;; SITE_FORCE=1 Force republish all files (default: incremental) +;; SITE_DRY=1 Parse and prepare only; skip org-publish-all ;;; Code: -(require 'package) -(defvar site-root - (file-name-directory - (or load-file-name buffer-file-name))) +;; ───────────────────────────────────────────────────────────────────────────── +;; 0. Bootstrap: paths and load-path +;; ───────────────────────────────────────────────────────────────────────────── + +(defconst z/build-start-time (float-time) + "Wall-clock time when the build started.") + +(defconst z/site-root + (file-name-as-directory + (file-name-directory + (or load-file-name buffer-file-name))) + "Absolute path to the site root (always ends with /). +This is the single authoritative definition — lisp/* files must NOT +redefine site-root themselves.") + +;; Keep the old name around so any stray code still compiles. +(defvaralias 'site-root 'z/site-root) (defun site-path (path) - (expand-file-name path site-root)) + "Expand PATH relative to `z/site-root'." + (expand-file-name path z/site-root)) +(add-to-list 'load-path (site-path "lisp")) -(add-to-list 'load-path - (expand-file-name "lisp" - (file-name-directory - (or load-file-name buffer-file-name)))) +;; ───────────────────────────────────────────────────────────────────────────── +;; 1. Logging helpers (ANSI colours for terminal output) +;; ───────────────────────────────────────────────────────────────────────────── -(require 'recently-updated) -(require 'tags) -(require 'sidenotes) -(require 'sitemaps) +(defconst z/colour-reset "\033[0m") +(defconst z/colour-bold "\033[1m") +(defconst z/colour-dim "\033[2m") +(defconst z/colour-green "\033[32m") +(defconst z/colour-yellow "\033[33m") +(defconst z/colour-cyan "\033[36m") +(defconst z/colour-red "\033[31m") +(defconst z/colour-blue "\033[34m") +(defconst z/colour-magenta "\033[35m") -(setq package-user-dir (expand-file-name "./.packages")) -(setq package-archives '(("melpa" . "https://melpa.org/packages/") - ("elpa" . "https://elpa.gnu.org/packages/"))) +(defun z/log (level fmt &rest args) + "Emit a coloured build-log line. +LEVEL is one of: info warn error step metric done. +FMT / ARGS are passed to `format'." + (let* ((msg (apply #'format fmt args)) + (prefix + (pcase level + ('info (concat z/colour-cyan " INFO " z/colour-reset)) + ('warn (concat z/colour-yellow " WARN " z/colour-reset)) + ('error (concat z/colour-red " ERROR " z/colour-reset)) + ('step (concat z/colour-blue z/colour-bold + " ──── " z/colour-reset)) + ('metric (concat z/colour-magenta " ◈ " z/colour-reset)) + ('done (concat z/colour-green z/colour-bold + " ✓ " z/colour-reset)) + (_ " ")))) + (message "%s%s" prefix msg))) + +(defun z/log-separator (&optional label) + "Print a coloured separator line, optionally with LABEL." + (if label + (message "%s%s── %s %s%s" + z/colour-dim z/colour-bold label + (make-string (max 0 (- 60 (length label))) ?─) + z/colour-reset) + (message "%s%s%s" + z/colour-dim + (make-string 66 ?─) + z/colour-reset))) + +(defmacro z/with-timing (label &rest body) + "Execute BODY, then log elapsed seconds under LABEL." + (declare (indent 1)) + (let ((t0 (gensym "t0"))) + `(let ((,t0 (float-time))) + (prog1 (progn ,@body) + (z/log 'metric "%s took %.2fs" ,label (- (float-time) ,t0)))))) + +;; ───────────────────────────────────────────────────────────────────────────── +;; 2. Package bootstrap +;; ───────────────────────────────────────────────────────────────────────────── + +(z/log-separator "Package setup") + +(require 'package) + +(setq package-user-dir (site-path ".packages")) +(setq package-archives + '(("melpa" . "https://melpa.org/packages/") + ("elpa" . "https://elpa.gnu.org/packages/"))) + +(package-initialize) + +(z/with-timing "Package archive refresh" + (unless package-archive-contents + (z/log 'info "Refreshing package archive contents…") + (condition-case err + (package-refresh-contents) + (error + (z/log 'warn "Could not refresh archives: %s" (error-message-string err)))))) + +(z/with-timing "htmlize install" + (unless (package-installed-p 'htmlize) + (z/log 'info "Installing htmlize…") + (condition-case err + (package-install 'htmlize) + (error + (z/log 'error "htmlize install failed: %s" (error-message-string err)) + (error "Cannot continue without htmlize"))))) + +(require 'htmlize) + +;; ───────────────────────────────────────────────────────────────────────────── +;; 3. Org / ox requires +;; ───────────────────────────────────────────────────────────────────────────── (require 'ox-publish) (require 'cl-lib) @@ -40,154 +135,176 @@ (require 'ox-html) (require 'ox-md) -(package-initialize) -(unless package-archive-contents - (package-refresh-contents)) +;; ───────────────────────────────────────────────────────────────────────────── +;; 4. Local library requires (after load-path is set) +;; ───────────────────────────────────────────────────────────────────────────── -(package-install 'htmlize) -(add-to-list 'load-path "~/master-folder/org_files/org_web/") -(require 'htmlize) +(z/log-separator "Local libraries") -(defvar z-shared-head - " - +(dolist (lib '(recently-updated tags sidenotes sitemaps)) + (condition-case err + (progn + (require lib) + (z/log 'done "Loaded %s" lib)) + (error + (z/log 'error "Failed to load %s: %s" lib (error-message-string err)) + (error "Aborting: required library %s missing" lib)))) - - - - - - - - - +;; ───────────────────────────────────────────────────────────────────────────── +;; 5. HTML export settings +;; ───────────────────────────────────────────────────────────────────────────── - - - - - - - - - - - -" - ) +(setq org-html-htmlize-output-type 'css) + +(defvar z/shared-head + (concat + "\n" + (mapconcat + (lambda (f) + (format "" f)) + '("style.css" + "bigger-picture.min.css" + "comments.css" + "kanban.css" + "org-syntax.css" + "misc.css" + "toc.css" + "media.css" + "wird-tracker.css") + "\n") + "\n" + (mapconcat + (lambda (f) + (format "" f)) + '("script.js" + "lunr.js" + "competency-status-board.js" + "notes.js" + "comments.js" + "bigger-picture.min.js" + "search.js" + "svg-pan-zoom.min.js" + "gallery-init.js" + "sitemap-interactive.js" + "wird-tracker.js") + "\n")) + "Shared HTML fragment injected into every page.") + +;; ───────────────────────────────────────────────────────────────────────────── +;; 6. Global Org macros +;; ───────────────────────────────────────────────────────────────────────────── (setq org-export-global-macros (append + org-export-global-macros '(("sidenote" - . "@@html:$2@@") - ("epigraph" . "@@html:$1
$1
$1
$1
$1
$1
- ![\"Site](\"/assets/images/gr.png\")
+(defvar z/preamble
+ "
-
+(defvar z/preamble
+ "
+
+
+
+Updated: %C
+")
- Updated: %C
-
-"
-)
-
-(defvar z-postamble
+(defvar z/postamble
"")
-
+;; ─────────────────────────────────────────────────────────────────────────────
+;; 8. Comments support
+;; ─────────────────────────────────────────────────────────────────────────────
(defun z/comments-file-p (file)
- "Return non-nil if FILE has comments enabled.
-A file has comments if:
- - It has a #+COMMENTS: keyword with value \"t\" (case-insensitive)."
+ "Return non-nil if FILE has #+COMMENTS: t."
(when (file-exists-p file)
(with-temp-buffer
(insert-file-contents file)
(org-mode)
(let* ((keywords (org-collect-keywords '("COMMENTS")))
- (comments (cadr (assoc "COMMENTS" keywords))))
- (print keywords)
-
- (and comments
- (string-match-p "^\\s-*t\\s-*$"
- (downcase comments)))))))
+ (val (cadr (assoc "COMMENTS" keywords))))
+ (and val
+ (string-match-p "^\\s-*t\\s-*$" (downcase val)))))))
(defun z/comments-file-slug (file)
- "Return page slug from #+SLUG: or fallback to filename."
+ "Return page slug from #+SLUG: or fallback to filename base."
(with-temp-buffer
(insert-file-contents file)
(org-mode)
(let* ((keywords (org-collect-keywords '("SLUG")))
- (slug (cadr (assoc "SLUG" keywords))))
+ (slug (cadr (assoc "SLUG" keywords))))
(if (and slug (string-match-p "\\S-" slug))
slug
(file-name-base file)))))
(defun z/org-html-insert-comments-into-body (body backend info)
- "Insert comments section at the end of the document body."
+ "Append a comments section to BODY for files that opt in."
(when (org-export-derived-backend-p backend 'html)
(let ((input-file (plist-get info :input-file)))
- (if (and input-file
- (z/comments-file-p input-file))
+ (if (and input-file (z/comments-file-p input-file))
(let* ((slug (z/comments-file-slug input-file))
- (comments-html
- (format
- "
-2026-03-19 16:05@@
-- [[file:blogs/2026/03-march/setting-a-wird-tracker-19-03.org][Setting a Wird Tracker]] @@html:2026-03-19 13:57@@
-- [[file:index.org][Home Page]] @@html:2026-03-19 13:10@@
+* Recently Updated (top 26 files)
+- [[file:home/wird-tracker.org][Wird Tracker]] @@html:2026-03-19 18:26@@
+- [[file:blogs/2026/03-march/setting-a-wird-tracker-19-03.org][Setting a Wird Tracker]] @@html:2026-03-19 13:15@@
- [[file:home/guide/wird-tracker-guide.org][Wird Tracker — Technical Guide]] @@html:2026-03-19 12:43@@
-- [[file:blogs/2026/03-march/fixing-the-dag-18-03.org][DAG fixes]] @@html:2026-03-19 10:42@@
-- [[file:blogs/2026/03-march/feeling-sleepy.org][Feeling extremely sleepy]] @@html:2026-03-19 10:41@@
-- [[file:blogs/2026/03-march/oversleeping-16-03.org][Oversleeping and missing a meeting...]] @@html:2026-03-16 12:17@@
-- [[file:blogs/2026/03-march/15-03-week-review.org][[15-03-2026] - Weekly Review]] @@html:2026-03-12 16:31@@
-- [[file:blogs/2026/03-march/08-03-week-review.org][[08-03-2026] - Weekly Review]] @@html:2026-03-12 16:17@@
-- [[file:posts/career/javascript.org][Understands the Javascript language]] @@html:2026-03-11 17:20@@
-- [[file:posts/career/ha-dr.org][High Availability, Disaster Recovery and Business Continuity]] @@html:2026-03-11 17:19@@
-- [[file:posts/career/restful-api.org][Restful API]] @@html:2026-03-08 17:37@@
+- [[file:blogs/2026/03-march/fixing-the-dag-18-03.org][DAG fixes]] @@html:2026-03-18 15:01@@
+- [[file:blogs/2026/03-march/feeling-sleepy.org][Feeling extremely sleepy]] @@html:2026-03-16 16:18@@
+- [[file:blogs/2026/03-march/oversleeping-16-03.org][Oversleeping and missing a meeting...]] @@html:2026-03-16 11:21@@
+- [[file:blogs/2026/03-march/15-03-week-review.org][[15-03-2026] - Weekly Review]] @@html:2026-03-15 12:00@@
+- [[file:posts/career/ha-dr.org][High Availability, Disaster Recovery and Business Continuity]] @@html:2026-03-11 17:18@@
+- [[file:posts/career/javascript.org][Understands the Javascript language]] @@html:2026-03-11 16:52@@
- [[file:home/status.org][Competency Status Board]] @@html:2026-03-08 16:28@@
-- [[file:blogs/2026/02-february/27-02-26.org][Journeys rambles again...]] @@html:2026-03-07 16:33@@
-- [[file:blogs/2026/03-march/01-03-week-review.org][[01-03-2026] - Weekly Review]] @@html:2026-03-07 12:45@@
-- [[file:posts/career/database-permissions.org][Database Permissions, Roles, and Accounts]] @@html:2026-03-05 13:06@@
-- [[file:posts/career/monitoring-and-logging.org][Monitoring and Logging]] @@html:2026-03-05 12:58@@
-- [[file:posts/career/pipelines.org][Pipelines and how they work (as well as CI/CD)]] @@html:2026-03-05 11:52@@
-- [[file:blogs/2026/02-february/third-meeting.org][Third Meeting with lima :)]] @@html:2026-03-03 12:02@@
-- [[file:blogs/2026/02-february/22-02-week-review.org][[22-02-2026] - Weekly Review]] @@html:2026-02-27 17:07@@
-- [[file:blogs/2026/02-february/26-02-26.org][Starting the Journeys Upgrade]] @@html:2026-02-26 17:37@@
-- [[file:blogs/2026/02-february/24-02-26.org][Integration tests failing (sob)]] @@html:2026-02-24 17:00@@
-- [[file:home/backlog.org][Backlog]] @@html:2026-02-23 16:40@@
-- [[file:blogs/2026/02-february/15-02-week-review.org][[15-02-2026] - Weekly Review]] @@html:2026-02-23 10:02@@
+- [[file:blogs/2026/03-march/08-03-week-review.org][[08-03-2026] - Weekly Review]] @@html:2026-03-08 12:00@@
+- [[file:blogs/2026/03-march/01-03-week-review.org][[01-03-2026] - Weekly Review]] @@html:2026-03-01 12:00@@
+- [[file:blogs/2026/02-february/27-02-26.org][Journeys rambles again...]] @@html:2026-02-27 17:12@@
+- [[file:blogs/2026/02-february/26-02-26.org][Starting the Journeys Upgrade]] @@html:2026-02-26 17:32@@
+- [[file:blogs/2026/02-february/24-02-26.org][Integration tests failing (sob)]] @@html:2026-02-24 16:55@@
+- [[file:blogs/2026/02-february/22-02-week-review.org][[22-02-2026] - Weekly Review]] @@html:2026-02-22 12:00@@
+- [[file:posts/career/restful-api.org][Restful API]] @@html:2026-02-15 23:00@@
+- [[file:blogs/2026/02-february/15-02-week-review.org][[15-02-2026] - Weekly Review]] @@html:2026-02-15 12:00@@
- [[file:home/services.org][Service]] @@html:2026-02-11 13:26@@
-- [[file:blogs/2026/02-february/08-02-week-review.org][[08-02-2026] - Weekly Review]] @@html:2026-02-11 12:20@@
+- [[file:blogs/2026/02-february/08-02-week-review.org][[08-02-2026] - Weekly Review]] @@html:2026-02-08 12:00@@
+- [[file:blogs/2026/02-february/third-meeting.org][Third Meeting with lima :)]] @@html:2026-02-01 12:00@@
+- [[file:blogs/2026/02-february/01-02-week-review.org][[01-02-2026] - Weekly Review]] @@html:2026-02-01 12:00@@
+- [[file:blogs/2026/01-january/25-01-week-review.org][[25-01-2026] - Weekly Review]] @@html:2026-01-25 12:00@@
+- [[file:posts/career/pipelines.org][Pipelines and how they work (as well as CI/CD)]] @@html:2026-01-18 23:00@@
+- [[file:posts/career/monitoring-and-logging.org][Monitoring and Logging]] @@html:2026-01-18 23:00@@
+- [[file:posts/career/database-permissions.org][Database Permissions, Roles, and Accounts]] @@html:2026-01-18 23:00@@
diff --git a/lisp/recently-updated.el b/lisp/recently-updated.el
index 0595004..c0b63f0 100755
--- a/lisp/recently-updated.el
+++ b/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:%s@@\n"
- rel title datestr))))))
- (message "Wrote recently-updated.org"))
+ rel title datestr)))))
+ (length items)))
(provide 'recently-updated)
+
+;;; recently-updated.el ends here
\ No newline at end of file
diff --git a/lisp/sidenotes.el b/lisp/sidenotes.el
index 1f9be7b..3a3a865 100755
--- a/lisp/sidenotes.el
+++ b/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
\ No newline at end of file
diff --git a/lisp/sitemaps.el b/lisp/sitemaps.el
index 3525ba6..0372575 100755
--- a/lisp/sitemaps.el
+++ b/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:%s@@"
+ 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:Categories@@\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:%s@@ %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:Categories@@\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: %s @@" tag tag))
- (split-string tags ":" t) ;; <- Splits by ":" and removes empty strings
- " "))))))
- ;; Final line output
- (format "- %s @@html:%s@@ %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:Categories@@\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: %s @@" tag tag))
- (split-string tags ":" t) ;; <- Splits by ":" and removes empty strings
- " "))))))
- ;; Final line output
- (format "- %s @@html:%s@@ %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: \
-%s @@" 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:Categories@@\n\n")))
-
- ;; Sort years descending
+ ;; Render
+ (let ((output (concat "#+TITLE: " title "\n"
+ "#+OPTIONS: toc:nil num:nil\n\n"
+ "See the categories: @@html:Categories@@\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:%s@@ %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:%s@@ %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:Categories@@\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: %s @@" tag tag))
- (split-string tags ":" t) ;; <- Splits by ":" and removes empty strings
- " "))))))
- ;; Final line output
- (format "- %s @@html:%s@@ %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:Categories@@\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:%s@@ %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:Categories@@\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: \
-%s @@" 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:%s@@ %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:Categories@@\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: \
-%s @@" 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:%s@@ %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:Categories@@\n\n"
- "See the following page for more details: @@html:Career Intro@@\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: \
-%s @@" 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:%s@@ %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:Career Intro@@\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:%s@@]] (%d)"
- (z/tag-slug tag) tag (gethash tag counts))
- )
- tags
- "\n")
+ (mapconcat
+ (lambda (tag)
+ (format "- [[file:../tags/%s.org][@@html:%s@@]] (%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:%s@@"
- 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:%s@@"
+ 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
\ No newline at end of file
diff --git a/lisp/tags.el b/lisp/tags.el
index 85f13c5..8ef7969 100755
--- a/lisp/tags.el
+++ b/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
Comments
-