AlBasmala:
Blogging with Emacs & Org-mode (•̀ᴗ•́)و

3.1.1. standalone (the default)

3.1.2. multiple (container files)

#+title: My Life Posts
#+article_style: multiple

* A Walk in the Park                       :life:
:PROPERTIES:
:DATE:        <2026-05-03>
:DESCRIPTION: An evening walk with the kids.
:IMAGE:       park.png 350 350
:END:

** Abstract :ignore:
An evening walk with the kids --- the light was perfect.

** The Walk
...

* Quick Emacs Tip: visual-line-mode        :emacs:draft:
:PROPERTIES:
:DATE:        <2026-05-04>
:DESCRIPTION: One line, no scroll bar.
:SLUG:        emacs-tip-visual-line-mode
:END:
...

* Private scratch                          :noexport:
...

3.1.3. How the export pipeline connects the two styles

3.1.4. Slug derivation, write-back, and global uniqueness

3.1.5. Functions introduced for the multiple style

master branch                      gh-pages branch
──────────────────────────────     ─────────────────────────────────
foo.org         (source)      ──►  foo.html     (alhassy.com/foo)
AlBasmala.org   (source)   CI      index.html
resources/                    ──►  resources/
AlBasmala.el                       (NO .html files here)
(NO .html files here)

(defvar blog-title "Life & Computing Science"
  "Title of the blog.")

(defvar blog-url "https://alhassy.com"
  "URL of the blog.")

(defvar blog-publish-directory "~/blog/public/"
  "Directory containing published HTML files.

HTML is a build artefact; the .org sources in ~/blog/ are first-class.
On master we keep only sources; CI exports everything to public/ and deploys
public/'s contents to the gh-pages branch that GitHub Pages serves.
That gives flat URLs (alhassy.com/foo) while the master working tree stays clean.")

(defvar blog-posts-directory "~/blog"
  "Directory containing source Org files.

All article .org files — including AlBasmala.org itself — live here alongside
resources/.  blog--compute-posts-and-pages collects every .org file with #+date:
as a post and every file with #+site_nav: as a nav page; files with neither
(e.g. MathJaxPreamble.org) are silently skipped.
See blog-make-index-page and blog-publish-directory.")

 1: (defun blog-new-article ()
 2: "Make a new article for my blog; prompting for the necessary ingredients.
 3: 
 4: If the filename entered already exists, we simply write to it.
 5: The user notices this and picks a new name.
 6: 
 7: This sets up a new article based on existing tags and posts.
 8: + Use C-SPC to select multiple tag items
 9: 
10: Moreover it also enables org-preview-html-mode so that on every alteration,
11: followed by a save, C-x C-s, will result in a live preview of the blog article,
12: nearly instantaneously."
13:   (interactive)
14:   (let (file desc)
15: 
16:     (thread-last blog-posts-directory
17:       f-entries
18:       (mapcar #'f-filename)
19:       (completing-read "Filename (Above are existing): ")
20:       (concat blog-posts-directory)
21:       (setq file))
22: 
23:     ;; For some reason, 'find-file' in the thread above
24:     ;; wont let the completing-read display the possible completions.
25:     (find-file file)
26: 
27:     (insert "#+title: " (read-string "Title: ")
28:             "\n#+author: " user-full-name
29:             "\n#+email: "  user-mail-address
30:             "\n#+modified: " (format-time-string "%Y-%m-%d")
31:             "\n#+filetags: " (s-join " " (helm-comp-read "Tags: "
32:                                                          blog-tags
33:                                                          :marked-candidates t))
34:             "\n#+fileimage: emacs-birthday-present.png"
35:             ;; "\n#+fileimage: " (completing-read
36:             ;;                    "Image: "
37:             ;;                    (mapcar #'f-filename (f-entries "~/blog/resources/")))
38:             ;; "\n#+include: ../MathJaxPreamble.org" ;; TODO. Is this someting I actually want here? If so, then consider tangling it from AlBasmala! (and add the whitespace-MathJax setup from above!)
39:             "\n#+description: "
40:                (setq desc (read-string "Article Purpose: "))
41:             "\n\n* Abstract :ignore: \n" desc
42:             "\n\n* ???")
43:     (save-buffer)
44:     (blog-preview)))

(defun blog-new-post ()
  "Insert a new article skeleton at point in a multiple-style container file.

Prompts for title, description, and (optionally) tags.  The image is
selected automatically from blog-tag-image-alist based on the tags entered
-- no image prompt required.  It can be overridden afterwards by editing the
:IMAGE: property in the drawer.

The :draft: heading tag is added automatically so the article is treated as
a draft until you remove it before publishing."
  (interactive)
  (unless (blog--multiple-style-p)
    (user-error "Not a multiple-style file; use blog-new-article for standalone posts"))
  (let* ((title       (read-string "Article title: "))
         (description (read-string "One-line description: "))
         (tags-input  (read-string "Tags (space-separated, optional): "))
         (tags        (s-split " " tags-input t))
         (image       (blog--image-for-tags tags))
         (tag-suffix  (if tags (concat ":" (s-join ":" tags) ":") ""))
         (today       (format-time-string "%Y-%m-%d")))
    (unless (bolp) (newline))
    (insert
     "* " title " :draft:" tag-suffix "\n"
     ":PROPERTIES:\n"
     ":MODIFIED:    " today "\n"
     ":DESCRIPTION: " description "\n"
     ":IMAGE:       " image "\n"
     ":END:\n"
     "\n"
     "** Abstract :ignore:\n"
     description "\n"
     "\n"
     "** ???\n")
    ;; Enable preview for this container if not already active.
    (unless (member #'blog-preview-subtree after-save-hook)
      (blog-preview))))

;; Convenient accessor methods: Given a JSON hashmap, get the specified key values.
;; Later, we redefine these, for example `@image' will actually produces the HTML for the image.
;; Example usage: (@title (seq-elt posts 0))  ⇒  "Java CheatSheet"

;; Extract the '#+title:' from POST-FILENAME.
(defun @title       (json) (map-elt json "title"))

(defun blog--title-html (title)
  "Strip Org export-snippet markers from TITLE so embedded HTML renders.

Titles like 'AlBasmala: @@html: <br>@@ …' carry Org export snippets that
`#+begin_export html' blocks and raw format strings ship verbatim --- so the
`@@html:' / `@@' markers leak into the output.  Axe them, keeping the payload
(here, the literal `<br>') so HTML contexts render it as intended.  RSS feeds
should keep calling (esc (@title post)) and avoid this helper: `<br>' would
then escape to '&lt;br&gt;' and be shown as text."
  (thread-last title
               (string-replace "@@html:" "")
               (string-replace "@@" "")))

;; TODO: Consider using: (format-time-string "%d %b %Y" ⋯) to have the same format across all articles.
(defun @date (json)
  "Extract the #+modified: field from JSON."
  (map-elt json "date"))

(defun @file        (json) (map-elt json "file"))
(defun @slug        (json) (map-elt json "slug"))
(defun @description (json) (map-elt json "description"))
(defun @abstract    (json) (map-elt json "abstract"))

;; Returns absolute URL to the published POST-FILENAME.
;;
;; This function concatenates publish URL and generated custom filepath to the
;; published HTML version of the post.
;;
(defun @url                  (json) (map-elt json "url"))

;; For container sub-articles, the synthetic #+htmlized_source_url: keyword
;; carries the URL of the per-article colourised source view.
;; Returns nil for ordinary standalone articles (blog--footer falls back to blog--htmlize-file).
(defun @htmlized_source_url  (json) (map-elt json "htmlized_source_url"))

(defun @history (json)
  "Get an HTML badge that points to the Github history of a given file name, in my blog."
  (concat
   "<a class=\"tooltip\" title=\"See the various edits to this article over time\" href=\""
   (map-elt json "history")
   "\"><img src=\"https://img.shields.io/badge/-History-informational?logo=github\"></a>"))

(defun blog--tag-slug (tag)
  "Convert an internal TAG name (underscores, Org-compatible) to a kebab-case slug.

Org forbids dashes in tag names — we use underscores internally and replace them
with dashes for display and URLs so the reader sees kebab-case everywhere:
  programming_language  →  programming-language
  tag-programming_language.html  →  tag-programming-language.html"
  (s-replace "_" "-" (downcase tag)))

(defun @tags (json)
  "Get an HTML listing of tags, as shields.io badges, associated with the given file.

Tag names are stored with underscores (Org syntax requirement) but rendered with
dashes everywhere — display label, URL slug — so readers see kebab-case.

Example use:  (@tags (seq-elt blog-posts 0))
"
  (concat
  ;; Badges implementation
   (concat
    (format "<a href=\"https://alhassy.github.io/tags.html\"> %s </a>"
            (org-link/octoicon "tag" nil 'html))
    (s-join " "
            (--map  (let ((slug (blog--tag-slug it)))
                      (org-link/badge
                       (format "|%s|grey|%stag-%s.html"
                               slug "https://alhassy.com/" slug)
                       nil 'html))
                    (s-split " " (map-elt json "tags")))))))

(cl-defun @image (json &optional explicit-image-path-prefix)
  "Assemble the value of '#+fileimage: image width height border?' as an HTML form.

By default, the image should be located in the top-level resources/ directory.
If the image is located elsewhere, or is a URL, is dictated by the presence of a `/'
in the image path.

Example use:  (@image (seq-elt blog-posts 0))

Here are 4 example uses:

#+fileimage: emacs-birthday-present.png
#+fileimage: ../resources/emacs-birthday-present.png
#+fileimage: https://upload.wikimedia.org/wikipedia/en/6/64/Dora_and_Boots.jpg 350 300
#+fileimage: https://unsplash.com/photos/Vc2dD4l57og

+ Notice that the second indicates explicit width and height.
+ (To make the first approach work with local previews,
   we need the variable EXPLICIT-IMAGE-PATH-PREFIX which is used for local previews in my/blog--style-setup. This requires a slash at the end.)
+ The unsplash approach is specific: It shows the *main* image in the provided URL, and links to the provided URL.
"
  (-let [(image width height no-border?) (s-split " " (map-elt json "image"))]
    (setq width (or width 350))
    (setq height (or height 350))
    (setq no-border? (if no-border? "" "style=\"border: 2px solid black;\""))
    (cond
     ((s-contains? "/" image) t) ;; It's a URL, or explicit path, do nothing to it.
     (explicit-image-path-prefix (setq image (format "%s%s"  explicit-image-path-prefix image)))
     ((not (s-contains? "/" image)) (setq image (format "resources/%s" image))))
    (-let [unsplash (cl-second (s-match ".*unsplash.com/photos/\\(.*\\)" image))]
      (setq href (if unsplash (concat "https://unsplash.com/photos/" unsplash) image))
      (setq title (format "Image credit %s" (if unsplash (concat "https://unsplash.com/photos/" unsplash) image)))
      (setq src (if unsplash (format "https://source.unsplash.com/%s/%sx%s" unsplash width height) image))
      (s-collapse-whitespace
       (format "<center class=\"post-image\"><a href=\"%s\" class=\"tooltip\" title=\"%s\"><img src=\"%s\" alt=\"Article image\"
             %s width=\"%s\" height=\"%s\" align=\"top\"/></a></center>"
              href title src no-border? width height)))))

(defun blog--info (post-filename)
  "Extract the `#+BLOG_KEYWORD: VALUE` pairs from POST-FILENAME.

Example use: (blog--info \"~/blog/HeytingAlgebra.org\")

For container sub-articles, the temp file may carry synthetic keywords:
  #+history_url:         — overrides the auto-computed GitHub history URL
  #+htmlized_source_url: — URL for the per-article colourised source badge
These are ignored for ordinary standalone files (regex yields nil, fallback applies)."
  (let ((case-fold-search t))
    (with-temp-buffer
      (insert-file-contents post-filename)
      (delay-mode-hooks (org-mode))
      (let* ((keyword-pairs
              (cl-loop for (prop.name prop.regex prop.default) on
                    `("title"                "^\\#\\+title:[ ]*\\(.+\\)$"                ,post-filename
                      "date"                 "^\\#\\+modified:[ ]*\\([0-9][-0-9 a-zA-Z:]+\\)$" ,(format-time-string "%Y-%m-%d")
                      "image"                "^\\#\\+fileimage: \\(.*\\)"                "emacs-birthday-present.png 350 350"
                      "description"          "^\\#\\+description:[ ]*\\(.+\\)$"          "I learned something neat, and wanted to share!"
                      "tags"                 "^\\#\\+filetags:[ ]*\\(.+\\)$"             "" ;; String; Space-separated
                      "history_url"          "^\\#\\+history_url:[ ]*\\(.+\\)$"          nil
                      "htmlized_source_url"  "^\\#\\+htmlized_source_url:[ ]*\\(.+\\)$"  nil
                      "site_nav"             "^\\#\\+site_nav:[ ]*\\(.+\\)$"             nil
                      "modified"             "^\\#\\+modified:[ ]*\\(.+\\)$"             nil
                      )
                  by 'cdddr
                  ;; See: https://stackoverflow.com/questions/19774603/convert-alist-to-from-regular-list-in-elisp
                  do (goto-char (point-min))
                  collect (cons prop.name
                                (if (search-forward-regexp prop.regex nil t)
                                    (match-string 1)
                                  prop.default)))))
        (-snoc
         (cons
          (cons "file" (f-base post-filename))
          keyword-pairs)
         (cons "url" (concat "https://alhassy.com/" (f-base post-filename)))
         ;; Prefer an explicit #+history_url: (injected for container sub-articles)
         ;; over the auto-derived URL based on the file basename.
         (cons "history"
               (or (cdr (assoc "history_url" keyword-pairs))
                   (format "https://github.com/alhassy/alhassy.github.io/commits/master/%s.org"
                           (f-base post-filename))))
         (cons "abstract" (progn
                    (goto-char (point-min))
                    (when (re-search-forward "^\* Abstract" nil t)
                      (beginning-of-line)
                      (-let [start (point)]
                        (org-narrow-to-subtree)
                        (org-fold-show-entry)
                        (re-search-forward "^ *:END:" nil t) ;; Ignore :PROPERTIES: drawer, if any.
                        (forward-line)
                        (buffer-substring-no-properties (point) (point-max)))))))))))

1. Tag-based image selection: blog--image-for-tags
   

   Picking an image for every post is friction we can eliminate. blog--image-for-tags maps a list of Org heading tags to a default image, checked in priority order — first match wins, falling back to emacs-birthday-present.png if nothing matches.

   This is used in two places:

   1. blog--info-subtree — when a heading has no :IMAGE: property, the image is derived from its tags automatically.
   2. blog-new-post — the skeleton :IMAGE: line is pre-populated from the tags the user typed, so it is immediately visible and editable without being a required prompt.

   To extend the map, add entries to blog-tag-image-alist — pairs of (tag . "image-spec") where the image spec is anything #+fileimage: accepts (filename, URL, filename w h).

   (defvar blog-tag-image-alist
     '(("emacs"    . "./resources/emacs-birthday-present.png 350 350")
       ("lisp"     . "./resources/emacs-birthday-present.png 350 350")
       ("org"      . "./resources/org_logo.png 350 350")
       ("haskell"  . "./resources/haskell-logo.png 350 350")
       ("java"     . "./resources/modern-java.png 350 350")
       ("arabic"   . "./resources/arabic-irab.png 350 350")
       ("life"     . "./resources/musa_pink.jpg 350 350")
       ("family"   . "./resources/family-tree.png 350 350")
       ("karate"   . "./resources/fukyu-kata.png 350 350"))
     "Alist mapping Org heading tags to default image specs for blog posts.
   First match wins.  The image spec is anything #+fileimage: accepts.
   Used by blog--image-for-tags to avoid requiring an explicit :IMAGE: property
   on every container sub-article.")
   
   (defun blog--image-for-tags (tags)
     "Return a default image spec for the given list of TAGS (strings, lowercased).
   Checks blog-tag-image-alist in order; returns the first match.
   Falls back to the global default image when no tag matches."
     (or (cdr (seq-find (lambda (pair) (member (car pair) tags))
                        blog-tag-image-alist))
         "./resources/emacs-birthday-present.png 350 350"))
   

   (defun blog--file-keyword (file-or-nil key &optional default)
     "Return the value of `#+KEY:' as a trimmed string.
   
   If FILE-OR-NIL is nil, scan the current buffer; otherwise read FILE-OR-NIL
   into a temp buffer first.  Returns DEFAULT when the keyword is absent.
   Case-insensitive on the key.  KEY omits the leading `#+' and trailing `:'."
     (let ((case-fold-search t)
           (rx (concat "^#\\+" (regexp-quote key) ":[ ]*\\(.*\\)$")))
       (cl-flet ((scan ()
                   (save-excursion
                     (goto-char (point-min))
                     (if (re-search-forward rx nil t) (s-trim (match-string 1)) default))))
         (if (null file-or-nil)
             (scan)
           (with-temp-buffer
             (insert-file-contents file-or-nil)
             (scan))))))
   
   (defun blog--article-style (&optional filename)
     "Return the #+article_style keyword for FILENAME (default: current buffer file).
   Returns \"multiple\" or \"standalone\" (the default when the keyword is absent)."
     (let ((file (or filename (buffer-file-name))))
       (if (not file)
           "standalone"
         (blog--file-keyword file "article_style" "standalone"))))
   
   (defun blog--make-slug (title)
     "Convert TITLE to a URL-safe kebab-case slug.
   
   Lowercases, strips non-alphanumeric characters (keeping spaces and existing
   dashes), then collapses runs of spaces/dashes into a single dash."
     (thread-last title
       downcase
       (replace-regexp-in-string "[^[:alnum:][:space:]-]" "")
       (replace-regexp-in-string "[[:space:]]+" "-")
       (replace-regexp-in-string "-+" "-")
       (replace-regexp-in-string "^-\\|-$" "")))
   
   (defun blog--make-slugs-for-headings (titles)
     "Return a list of unique slugs for TITLES in the same order.
   
   Collisions within the list are resolved by appending -2, -3, ... to the
   base slug.  This is a two-pass approach: first derive base slugs, then
   detect and fix collisions."
     (let ((seen (make-hash-table :test #'equal)))
       (mapcar (lambda (title)
                 (let* ((base  (blog--make-slug title))
                        (count (gethash base seen 0))
                        (slug  (if (= count 0) base (format "%s-%d" base (1+ count)))))
                   (puthash base (1+ count) seen)
                   slug))
               titles)))
   

   blog--info-subtree, blog--info-multiple: Extract metadata from container headings

   These are the multiple-style analogue of blog--info. Where blog--info extracts metadata from file-level #+keyword: lines via regex, blog--info-subtree reads it from a heading's :PROPERTIES: drawer and Org heading tags via org-element — the right tool since we are navigating a tree, not scanning a flat file.

   blog--info-multiple parses the container once (one org-element-parse-buffer call) and returns a list of alists — one per publishable top-level heading — each with the same keys as blog--info plus "slug" and "container". Parsing once and reusing the tree is deliberate: calling org-element-parse-buffer per heading would be quadratic for large containers.

   The abstract resolution priority — :DESCRIPTION: property, then ** Abstract :ignore: child heading, then first paragraph — mirrors what standalone articles do in practice: most have an explicit * Abstract section, but we want a sensible fallback for quick personal posts that skip the formality.

   (defun blog--info-subtree-abstract (headline-node)
     "Return the abstract text for HEADLINE-NODE, or nil.
   
   Priority:
   1. :ABSTRACT: property on the headline.
   2. A child heading whose title matches /abstract/i (e.g. ** Abstract :ignore:).
   3. The first paragraph element in the heading body."
     (or
      ;; 1. Explicit property
      (org-element-property :ABSTRACT headline-node)
      ;; 2. Child heading named Abstract
      (org-element-map headline-node 'headline
        (lambda (child)
          (when (and (= (org-element-property :level child)
                       (1+ (org-element-property :level headline-node)))
                     (string-match-p "abstract"
                                     (downcase (or (org-element-property :raw-value child) ""))))
            (org-element-interpret-data (org-element-contents child))))
        nil t)
      ;; 3. First paragraph fallback
      (org-element-map headline-node 'paragraph
        (lambda (para) (org-element-interpret-data para))
        nil t)))
   
   (defun blog--info-subtree (headline-node container-file slug)
     "Extract post metadata for HEADLINE-NODE from CONTAINER-FILE with SLUG.
   
   Returns nil when the headline carries a :noexport: tag or the COMMENT keyword.
   Returns an alist with the same keys as blog--info plus \"slug\" and \"container\"."
     (let* ((heading-tags (mapcar #'downcase
                                  (org-element-property :tags headline-node))))
       (unless (or (member "noexport" heading-tags)
                   (org-element-property :commentedp headline-node))
         (let* (;; draft?
                (draft? (or (member "draft" heading-tags)
                            (equal "t" (org-element-property :DRAFT headline-node))))
                ;; title: :TITLE: property overrides heading text
                (title (or (org-element-property :TITLE headline-node)
                           (org-element-property :raw-value headline-node)))
                ;; date — prefer :MODIFIED:, fall back to :DATE: for old articles
                (date-raw (or (org-element-property :MODIFIED headline-node)
                              (org-element-property :DATE headline-node)))
                (date (if date-raw
                          (replace-regexp-in-string "[<>]" "" date-raw)
                        (format-time-string "%Y-%m-%d")))
                ;; description
                (description (or (org-element-property :DESCRIPTION headline-node)
                                 "I learned something neat, and wanted to share!"))
                ;; image: explicit :IMAGE: property wins; otherwise derive from tags
                (image (or (org-element-property :IMAGE headline-node)
                           (blog--image-for-tags heading-tags)))
                ;; tags: merge :TAGS: property with heading tags; strip structural tags
                (structural-tags '("noexport" "draft" "ignore" "details" "details_orange"
                                   "details_green" "header" "reexport" "noreexport"))
                (prop-tags  (s-split " " (or (org-element-property :TAGS headline-node) "") t))
                (org-tags   (seq-remove (lambda (tag) (member tag structural-tags)) heading-tags))
                (all-tags   (seq-uniq (append prop-tags org-tags)))
                (tags-str   (s-join " " all-tags))
                ;; abstract
                (abstract (blog--info-subtree-abstract headline-node))
                ;; urls
                (container-base (f-base container-file))
                (url     (concat "https://alhassy.com/" slug))
                (history (format "https://github.com/alhassy/alhassy.github.io/commits/master/%s.org"
                                 container-base)))
           (list (cons "file"        container-base)
                 (cons "slug"        slug)
                 (cons "container"   container-base)
                 (cons "title"       title)
                 (cons "date"        date)
                 (cons "image"       image)
                 (cons "description" description)
                 (cons "tags"        tags-str)
                 (cons "url"         url)
                 (cons "history"     history)
                 (cons "abstract"    abstract)
                 (cons "draft"       (if draft? "t" nil))
                 (cons "redirect"    (org-element-property :REDIRECT headline-node))
                 (cons "modified"    (org-element-property :MODIFIED headline-node))
                 (cons "site_nav"    (org-element-property :SITE_NAV headline-node)))))))
   
   (defun blog--info-multiple (container-file)
     "Return a list of post-alists for all publishable top-level headings in CONTAINER-FILE.
   
   CONTAINER-FILE must carry #+article_style: multiple.
   Headings tagged :noexport: or carrying the COMMENT keyword are excluded.
   Headings tagged :draft: are included but marked."
     (with-temp-buffer
       (insert-file-contents container-file)
       (org-mode)
       (let* ((tree (org-element-parse-buffer))
              ;; Collect all level-1 headings
              (top-headings
               (org-element-map tree 'headline
                 (lambda (h)
                   (when (= (org-element-property :level h) 1) h))))
              ;; Derive slugs.  A heading with an explicit :CUSTOM_ID: property uses it
              ;; verbatim (the author takes responsibility for uniqueness).  All
              ;; other headings derive their slug from :TITLE: or the heading text
              ;; and go through blog--make-slugs-for-headings for dedup.
              (slugs
               (let* ((explicit  ; :CUSTOM_ID: property, or nil
                       (mapcar (lambda (h) (org-element-property :CUSTOM_ID h)) top-headings))
                      (titles    ; used only for headings without an explicit slug
                       (mapcar (lambda (h)
                                 (or (org-element-property :TITLE h)
                                     (org-element-property :raw-value h)))
                               top-headings))
                      ;; Compute deduped slugs for the headings that need it,
                      ;; passing a placeholder for those with explicit slugs so the
                      ;; indices stay aligned.
                      (deduped (blog--make-slugs-for-headings
                                (cl-mapcar (lambda (exp title) (or exp title))
                                           explicit titles))))
                 ;; Explicit :CUSTOM_ID: wins over the deduped result.
                 (cl-mapcar (lambda (exp deduped) (or exp deduped))
                            explicit deduped))))
         ;; Build alists, skipping noexport/COMMENT headings (blog--info-subtree returns nil for them)
         (delq nil
               (cl-mapcar (lambda (h slug) (blog--info-subtree h container-file slug))
                          top-headings slugs)))))
   
   

   REDIRECT: zero-duplication bridges to external Org files

   Often a project already has a lovingly maintained README.org (or a self-contained section of ~/.emacs.d/init.org) that is the article — there is no point copying it into a container heading just to republish it here.

   The :REDIRECT: property solves this. Give any container heading a local path (tilde and environment variables are expanded) or an https:// URL to an Org file; the publish pipeline replaces the subtree body with a single #+include: directive pointing at that file. Org's own include machinery does the rest — the result is indistinguishable from an article whose body was typed directly in the container.

   ▼ My Literate Emacs Config : emacs : lisp :
   :PROPERTIES:
   :DATE:         2024-01-15 
   :DESCRIPTION: A literate Emacs configuration, tangled from Org and readable as prose.
   :REDIRECT:    ~/.emacs.d/init.org
   :END:
   
   ▼ Remote README : docs :
   :PROPERTIES:
   :DATE:         2024-02-01 
   :REDIRECT:    https://raw.githubusercontent.com/alhassy/example/master/README.org
   :END:
   

   Neither ~/.emacs.d/ nor an arbitrary HTTPS URL is reachable from a CI runner, so C-x C-s vendors every :REDIRECT: into resources/redirects/<slug>.org (see §) and rewrites the property in place to point at the in-repo copy. After one preview-save, the property reads :REDIRECT: resources/redirects/my-literate-emacs-config.org, CI has the content, and #+include: resolves without special cases.

   When blog-publish-all processes the heading (via blog--publish-multiple-articles) it synthesises the usual file-level keyword preamble (#+title:, #+date:, etc.) and then appends

   #+include: "/…/blog/resources/redirects/my-literate-emacs-config.org"
   

   No subtree content is copied or promoted — the export proceeds through the identical blog--style-setup pipeline as any other article.

   Forcing a republish is a matter of nudging the staleness check (see §). Any of the following suffice:

   • Axe the :MODIFIED: property from the drawer.
   • Delete ~/blog/<slug>.html outright.
   • touch the redirected file so its mtime is newer than :MODIFIED:.

   The new key "redirect" is surfaced in every alist produced by blog--info-subtree and passed through the full pipeline, so tag pages, the RSS feed, and the index all treat redirect articles identically to hand-authored ones.

   Vendoring redirects so CI can resolve them

   A :REDIRECT: of ~/.emacs.d/init.org works beautifully on the author's laptop and catastrophically on CI — the runner has no ~/.emacs.d/ and #+include: aborts. We solve this by vendoring every redirect source into the blog repo at C-x C-s preview time, then rewriting the property to point at the in-repo copy:

   • Local path (~/.emacs.d/init.org, ../foo.org, …) — url-copy-file'd into resources/redirects/<slug>.org, which is git-tracked.
   • HTTP(S) URL (https://raw.githubusercontent.com/…/README.org, …) — fetched into the same directory.

   On preview (C-x C-s), blog--publish-single-subtree vendors the redirect on-the-fly into the temp file it creates for export — the source :REDIRECT: property is left untouched.

   On full publish (blog-publish-all, i.e. CI), blog--vendor-redirects runs first: it copies each upstream into resources/redirects/ and rewrites the :REDIRECT: property to the in-repo path. That rewritten value is committed to git, so CI's clean checkout can resolve the #+include: without network access or author-local paths like ~/.emacs.d/.

   CI re-exports every subtree on every run (the checkout has no prior HTML to diff against), so the vendored copy simply has to be present when org-export-to-html follows the #+include:. blog--vendor-redirects refreshes that copy on every publish, and git is the audit log.

   (defvar blog-redirects-subdir "resources/redirects/"
     "Subdirectory of `blog-posts-directory' where :REDIRECT: sources are
   vendored for CI.  Relative path; must end with a trailing slash.")
   
   (defun blog--url-p (path)
     "Return non-nil if PATH is an HTTP(S) URL."
     (string-match-p "\\`https?://" path))
   
   (defun blog--already-vendored-p (path)
     "Return non-nil if PATH is already rooted at `blog-redirects-subdir'."
     (string-prefix-p blog-redirects-subdir path))
   
   (defun blog--vendor-one-redirect (slug redirect)
     "Fetch REDIRECT (a local path or http(s) URL) into
   `blog-redirects-subdir'/SLUG.org and return the vendored relative path.
   A no-op if REDIRECT already points into `blog-redirects-subdir'."
     (if (blog--already-vendored-p redirect)
         redirect
       (let* ((dest-dir (expand-file-name blog-redirects-subdir blog-posts-directory))
              (dest     (expand-file-name (concat slug ".org") dest-dir)))
         (make-directory dest-dir t)
         (cond
          ((blog--url-p redirect)
           (url-copy-file redirect dest t))
          (t
           (let ((src (expand-file-name redirect)))
             (unless (file-exists-p src)
               (user-error "REDIRECT source does not exist: %s" src))
             (copy-file src dest t))))
         (call-process "git" nil nil nil "add" dest)
         (concat blog-redirects-subdir slug ".org"))))
   
   (defun blog--map-publishable-top-headings (fn)
     "Walk top-level headings in the current buffer and call FN with point on each.
   
   Only runs on multiple-style containers.  Skips COMMENTed headings — the
   per-heading FN is responsible for any further filtering (e.g. :noexport:)."
     (when (blog--multiple-style-p)
       (save-excursion
         (goto-char (point-min))
         (while (re-search-forward "^\\* " nil t)
           (unless (org-element-property :commentedp (org-element-at-point))
             (funcall fn))
           (org-end-of-subtree t t)))))
   
   (defun blog--assign-slugs ()
     "Walk the current buffer's top-level headings; for each without a :CUSTOM_ID:
   property, derive one from the heading title (or :TITLE: override) and
   write it back via `org-entry-put'.
   
   Called from the C-x C-s preview binding so that, by the time a source
   lands in git, every container heading carries a stable :CUSTOM_ID:.  CI then
   reads :CUSTOM_ID: and errors out if missing, rather than silently generating
   one and writing back to a throwaway checkout."
     (blog--map-publishable-top-headings
      (lambda ()
        (let ((tags (mapcar #'downcase (org-get-tags))))
          (unless (or (member "noexport" tags)
                      (org-entry-get (point) "CUSTOM_ID"))
            (let* ((title (org-get-heading t t t t))
                   (slug  (blog--make-slug
                           (or (org-entry-get (point) "TITLE") title))))
              (org-entry-put (point) "CUSTOM_ID" slug)
              (message "=> Assigned :CUSTOM_ID: %s to %s" slug title)))))))
   
   (defun blog--vendor-redirects ()
     "Walk the current buffer's top-level headings; for each with a :REDIRECT:
   property, vendor the source into `blog-redirects-subdir' and rewrite the
   property to the vendored in-repo path.  Only touches multiple-style containers.
   
   Called by `blog-publish-all' (CI) so the rewritten path lands in git and CI
   can resolve it on a clean checkout.  NOT called on preview/C-x C-s — preview
   vendors on-the-fly inside `blog--publish-single-subtree' without touching the
   source buffer.
   
   Relies on `blog--assign-slugs' having run first so every heading carries
   a :CUSTOM_ID: property we can build the vendored filename from."
     (blog--map-publishable-top-headings
      (lambda ()
        (let ((redirect (org-entry-get (point) "REDIRECT"))
              (slug     (org-entry-get (point) "CUSTOM_ID")))
          (when (and redirect slug (not (blog--already-vendored-p redirect)))
            (let ((vendored (blog--vendor-one-redirect slug redirect)))
              (org-entry-put (point) "REDIRECT" vendored)
              (message "=> Vendored redirect for %s ← %s" slug redirect)))))))
   

   MODIFIED: retired staleness machinery

   For historical interest: there was a :MODIFIED: <YYYY-MM-DD> property stamped on each container heading after a successful export, and a predicate blog--subtree-stale-p that compared :MODIFIED: to the <slug>.html mtime to skip unchanged subtrees on the next publish. That machinery only mattered while the author published locally — CI now rebuilds public/ from scratch on every run (the checkout has no prior HTML to compare against, so the stale-check always reported "stale"), and the :MODIFIED: stamps were writing back into source files from CI's throwaway working tree, which is pointless. Both were axed.

   If a future iteration ever caches public/ across CI runs (e.g. checking out gh-pages and incrementally updating), :MODIFIED: resurrects as the natural cache key: set the property explicitly on a heading you want re-exported, and the cached HTML older than that date gets invalidated. For the RSS guid's "edits re-notify readers" story we took a different route — see § — because it works without the author having to remember to stamp anything.

   SITE_NAV: data-driven site navigation from container subtrees

   Previously the site header — the links that appear at the top of every page — was a hardcoded HTML string in blog-page-preamble. Adding or renaming a nav link meant editing that string by hand, with no connection to the rest of the blog's metadata.

   We replace this with a :SITE_NAV: t property on container subtrees. Any heading in any #+article_style: multiple file that carries this property is treated as a site navigation page rather than a blog post: it is collected into blog-pages (not blog-posts), excluded from the index and tag pages, and its URL and title are rendered as a link in the preamble of every page.

   A typical nav page heading looks like:

   ▼ AlBasmala : emacs : lisp :
   :PROPERTIES:
   :DATE:         2020-01-01 
   :DESCRIPTION: How this blog works.
   :SLUG:        AlBasmala
   :SITE_NAV:    AlBasmala
   :END:
   

   The nav is rebuilt automatically by blog--rebuild-preamble, which is called at the end of every blog--refresh-posts invocation. The order of links in the header matches the order of blog-pages, which is the order the headings appear in their container files.

   Forcing a nav rebuild without a full publish: (blog--refresh-posts) suffices.

   The implementation lives in three new/modified functions (all in the blog-posts, blog-tags, and their consumers section):

   Function	Role
   blog--compute-posts-and-pages	Replaces blog--compute-posts; returns (posts . pages) cons
   blog--rebuild-preamble	Generates blog-page-preamble from blog-pages
   blog--refresh-posts	Updated to populate blog-pages and call blog--rebuild-preamble

   🔗

   The #+begin_abstract is an Org-mode Special Block

   Every article is intended to have a section named Abstract, whose contents are used as the preview of the article, in the index landing page. See §3 for a template.

   Below is an alteration from the examples of the docstring of org-defblock.

   (org-defblock abstract (main) nil
     "Render a block in a slightly narrowed blueish box, titled \"Abstract\".
   
      Supported backends: HTML. "
      (format (concat
               "<div class=\"abstract\" style=\"border: 1px solid black;"
               "padding: 1%%; margin-top: 1%%; margin-bottom: 1%%;"
               "margin-right: 10%%; margin-left: 10%%; background-color: lightblue;\">"
               "<center> <strong class=\"tooltip\""
               "title=\"What's the goal of this article?\"> Abstract </strong> </center>"
               "%s </div>")
              contents))
   

   
   ★     ★     ★

   For example, the source:

   #+begin_abstract
   In this article, we learn to have fun!
   #+end_abstract
   

   Results in:

   Abstract

   In this article, we learn to have fun!

   Generating the Index Page

   The actual look and feel of index.html is due to the method blog-make-index-page. It summarises all of my articles by their title, data & image, 'abstract', and a read-more badge.

     1: (defun blog--greeting (&optional tag)
     2:   "Return the index/tag-page greeting string, optionally specialised to TAG.
     3: 
     4: The `thread-first` / `doc:cl-loop' name-drop makes sense on the landing page
     5: (Elisp is the site's /lingua franca/) but reads as a non-sequitur on a
     6: tag-scoped page like `life' — so tag pages get a trimmed variant."
     7:   (if tag
     8:       (format "Here are some of my latest thoughts on %s... badge:Made_with|Lisp|success|https://alhassy.github.io/ElispCheatSheet/CheatSheet.pdf|Gnu-Emacs tweet:https://alhassy.com @@html:<br><br>@@"
     9:               (blog--tag-slug tag))
    10:     "Here are some of my latest thoughts... badge:Made_with|Lisp|success|https://alhassy.github.io/ElispCheatSheet/CheatSheet.pdf|Gnu-Emacs such as doc:thread-first and doc:cl-loop (•̀ᴗ•́)و tweet:https://alhassy.com @@html:<br><br>@@"))
    11: 
    12: (defun blog--card (post)
    13:   "Return the Org source for one article card.
    14: 
    15: No Org heading is emitted — Org would render it as an <h2> *in addition*
    16: to our own <h2 class=\"title\"> inside the export block, giving every
    17: card a duplicated title.  Per-tag filtering is done in Elisp before
    18: cards are built (see `blog-make-index-page'), so the Org tag machinery
    19: earns us nothing here."
    20:   (concat
    21:    "#+begin_export html\n"
    22:    (format "<h2 class=\"title\"><a href=\"%s\">%s</a></h2>\n"
    23:            (@url post) (blog--title-html (@title post)))
    24:    (format "<center>%s</center>\n" (@tags post))
    25:    (@image post "resources/")
    26:    "\n#+end_export\n"
    27:    "\n"
    28:    (or (@abstract post) "")
    29:    "\n"
    30:    ;; badge:… is an org-special-block-extras link type, so it must sit in
    31:    ;; Org territory — not inside #+begin_export html, which would ship it
    32:    ;; verbatim to the HTML output.  The @@html:…@@ wrappers give us the
    33:    ;; surrounding <p> while keeping the badge: link itself as Org syntax.
    34:    (format "@@html:<p style=\"text-align:right\">@@ badge:Read|more|green|%s|read-the-docs @@html:</p>@@\n"
    35:            (@url post))
    36:    "\n@@html:<hr>@@\n"))
    37: 
    38: (defun blog--toc-block (posts)
    39:   "Return a #+begin_export html block listing every post as a linked TOC entry."
    40:   (concat
    41:    "#+begin_export html\n"
    42:    "<details id=\"articles-toc\" style=\"text-align:center;margin:1em 0\">\n"
    43:    "<summary style=\"cursor:pointer;font-size:1.1em;font-weight:bold\">Articles on this page</summary>\n"
    44:    "<ol style=\"display:inline-block;text-align:left;margin-top:0.5em\">\n"
    45:    (mapconcat (lambda (post)
    46:                 (format "<li><a href=\"%s\">%s</a></li>\n"
    47:                         (@url post) (blog--title-html (@title post))))
    48:               posts "")
    49:    "</ol>\n</details>\n"
    50:    "#+end_export\n"))
    51: 
    52: (defun blog--make-page-buffer (posts greeting export-file-name &optional rss-file)
    53:   "Return a fresh Org buffer for POSTS with GREETING, targeting EXPORT-FILE-NAME.
    54: RSS-FILE is the filename of the associated feed (\"rss.xml\" for the index,
    55: \"<tag>-rss.xml\" for a tag page).  It is surfaced as a prominent link right
    56: under the greeting so readers see it without scrolling.
    57: Caller is responsible for killing the buffer when done."
    58:   (let ((buf (generate-new-buffer " *blog-page*"))
    59:         (rss (or rss-file "rss.xml")))
    60:     (with-current-buffer buf
    61:       (insert
    62:        (format "#+EXPORT_FILE_NAME: %s\n" export-file-name)
    63:        "#+options: toc:nil title:nil html-postamble:nil broken-links:t\n"
    64:        "#+begin_export html\n"
    65:        blog-page-preamble "\n"
    66:        blog-page-header "\n"
    67:        "#+end_export\n"
    68:        "#+html: <br>\n"
    69:        greeting "\n"
    70:        (format "#+html: <p style=\"text-align:center;\"><a href=\"%s\">📡 Subscribe via RSS</a></p>\n" rss)
    71:        "#+html: <br>\n"
    72:        (blog--toc-block posts)
    73:        "#+html: <br>\n"
    74:        (mapconcat #'blog--card posts "\n")
    75:        "\n#+begin_export html\n"
    76:        "<hr> <center> <em> Thanks for reading everything! 😁 Bye! 👋 </em>"
    77:        " </center> <br/>\n"
    78:        (blog--license)
    79:        "\n#+end_export\n")
    80:       (org-mode)
    81:       ;; ospe provides the `badge:`, `doc:`, `tweet:` etc. link handlers
    82:       ;; used throughout `blog--card', and appends tooltipster CSS/JS
    83:       ;; to `org-html-head-extra' on first activation (idempotent —
    84:       ;; ospe's setup-guard wraps the injection).
    85:       (org-special-block-extras-mode 1))
    86:     buf))
    87: 
    88: (defun blog-make-index-page ()
    89:   "Assemble index.html and every tag page.
    90: 
    91: Builds one Org buffer per output file, each populated directly from
    92: the relevant subset of blog-posts — no copy-then-delete."
    93:   (cl-flet ((export-page (posts greeting dest rss)
    94:                (let ((buf (blog--make-page-buffer posts greeting dest rss)))
    95:                  (unwind-protect
    96:                      (with-current-buffer buf (org-html-export-to-html))
    97:                    (with-current-buffer buf (set-buffer-modified-p nil))
    98:                    (kill-buffer buf)))))
    99:     (export-page blog-posts
   100:                  (blog--greeting)
   101:                  (concat blog-publish-directory "index.html")
   102:                  "rss.xml")
   103:     (let ((by-tag (blog--posts-by-tag)))
   104:       (dolist (tag blog-tags)
   105:         (message "=> Generating tag page: %s..." tag)
   106:         (let ((slug (blog--tag-slug tag)))
   107:           (export-page (gethash tag by-tag)
   108:                        (blog--greeting tag)
   109:                        (concat blog-publish-directory (concat "tag-" slug ".html"))
   110:                        (concat slug "-rss.xml")))))))
   

   RSS feeds: one per tag, plus a global one

   RSS (Really Simple Syndication) is a plain-text format a website uses to announce its new content. A reader program — Feedly, Inoreader, Newsboat, NetNewsWire, and dozens of others — subscribes to the URL of an RSS feed and periodically refetches it. When the feed has a new <item>, the reader surfaces it as "there is a new article". The blog does not push; readers pull whenever they want.

   So yes: every time we publish, this pipeline regenerates rss.xml; the next time a reader's program polls our URL, it compares entries to what it saw last time and notifies the human about any new ones. We never send email, we never track subscribers, we never even know who is subscribed. Publishing is just "put a new item in the feed"; the rest is the reader's problem.

   Why bother generating these at all? Because RSS is the one remaining ambient-notification mechanism for writers on the open web: no algorithm, no platform lock-in, no "follow" button owned by a company. A reader who subscribed to your RSS feed in 2008 is still subscribed today as long as the URL resolves. For a personal technical blog, it's the cheapest way to have an audience that returns.

   We emit two flavours of feed:

   • rss.xml — every post, newest first. For the reader who wants everything you write.
   • <tag>-rss.xml — per-tag feed (e.g. emacs-rss.xml, arabic-rss.xml). For a reader who wants only the emacs or arabic articles. The link to each tag-specific feed is surfaced at the top of the corresponding tag page.

   Each item carries a <pubDate>, a <link> back to alhassy.com/<slug>, and the article's #+description as its preview text. Bodies are intentionally not embedded: we want readers to click through.

   On identity and what counts as "new". Every <item> also carries a <guid> (globally unique identifier). Feed readers remember which GUIDs they have already surfaced to their user; on every refetch they compare the feed's current GUIDs against that seen-set:

   • New GUID → reader announces it as a new post.
   • Already-seen GUID → reader ignores the item, even if its title, description, or pubDate changed.

   Our GUIDs are alhassy.com/<slug>?last-updated=<MODIFIED> when the post carries a :MODIFIED: property (file-level #+modified: for standalone posts, heading-level :MODIFIED: for container sub-articles), or plain alhassy.com/<slug> otherwise.

   The consequence is entirely author-driven:

   • No :MODIFIED: present → guid is just the URL → edits are silent. Typos, whitespace fixes, paragraph rewrites all land on the deployed HTML without waking anyone up.
   • Bumping :MODIFIED: (to any later ISO date, e.g. 2026-05-06) → guid changes → next CI publish re-announces the post to every subscriber's feed reader.

   So the publishing contract is: you decide what "update" means. Fix a typo and CI quietly ships it. Finish rewriting the introduction, stamp :MODIFIED: to today's date, push — subscribers hear about it.

   Partial-commit trick. Magit makes this a one-keystroke workflow: bump :MODIFIED: whenever you save (so the stamp is always current while editing), and when preparing a commit, unstage the :MODIFIED: hunk with u if you don't want this particular edit to announce. The commit lands without the property bump; gh-pages gets the updated HTML; the guid is unchanged; subscribers stay silent. Conversely, stage the :MODIFIED: hunk with s when you do want the announce. The "should this notify?" decision lives exactly where it belongs — at commit time, per-hunk, alongside the actual change.

   An alternative we considered was deriving the date automatically from git log on the source file (per-heading for container articles, via git log -L /regex/,/regex/:file). That removes one piece of author discipline but adds a different one: every single commit counts, so a [typo] commit re-announces the post. Either move the noise upstream (squash cosmetic commits before pushing) or accept the signal loss. We went with :MODIFIED: because it matches how humans actually think about revisions, and it costs nothing on CI — no git shell-outs per post, no -L regex-escape edge cases.

    1: (defun blog--rss-date (date-str)
    2:   "Format DATE-STR (an Org date string) as an RFC-822 pubDate for RSS."
    3:   (format-time-string "%a, %d %b %Y %H:%M:%S %z"
    4:                       (condition-case _
    5:                           (date-to-time date-str)
    6:                         (error (current-time)))))
    7: 
    8: (defun blog--rss-guid (post)
    9:   "Return POST's RSS <guid>.
   10: 
   11: If POST carries a :MODIFIED: property, the guid is the article URL with
   12: a ?last-updated=<MODIFIED> query string; bumping :MODIFIED: therefore
   13: re-announces the post to every subscriber's feed reader (see the
   14: identity discussion in the prose above).  Without :MODIFIED:, the guid
   15: is just the URL — edits stay quiet until you stamp one."
   16:   (let ((modified (map-elt post "modified")))
   17:     (if modified
   18:         (format "%s?last-updated=%s" (@url post) modified)
   19:       (@url post))))
   20: 
   21: (defun blog--make-one-rss-feed (posts filename &optional channel-title)
   22:   "Emit `blog-publish-directory'/FILENAME from POSTS.
   23: 
   24: A minimal RSS 2.0 feed — title, link, pubDate, description per item.
   25: Body is intentionally a short #+description rather than the full article
   26: HTML, so readers click through to alhassy.com.  CHANNEL-TITLE defaults
   27: to `blog-title'.
   28: 
   29: Text fields are run through `xml-escape-string' so <, >, & in titles
   30: and descriptions do not break feed readers."
   31:   (cl-flet ((esc (s) (xml-escape-string (or s ""))))
   32:     (let ((dest  (concat blog-publish-directory filename))
   33:           (title (or channel-title blog-title)))
   34:       (with-temp-file dest
   35:         (insert "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
   36:                 "<rss version=\"2.0\">\n"
   37:                 "<channel>\n"
   38:                 "<title>"       (esc title) "</title>\n"
   39:                 "<link>"        (esc blog-url) "</link>\n"
   40:                 "<description>" (esc title) "</description>\n"
   41:                 "<language>en-us</language>\n")
   42:         (dolist (post posts)
   43:           (insert "<item>\n"
   44:                   "<title>"       (esc (@title post))       "</title>\n"
   45:                   "<link>"        (esc (@url post))         "</link>\n"
   46:                   "<guid>"        (esc (blog--rss-guid post)) "</guid>\n"
   47:                   "<pubDate>"     (blog--rss-date (@date post)) "</pubDate>\n"
   48:                   "<description>" (esc (@description post)) "</description>\n"
   49:                   "</item>\n"))
   50:         (insert "</channel>\n</rss>\n")))))
   51: 
   52: (defun blog--posts-by-tag ()
   53:   "Return a hash-table mapping tag-string → list of posts carrying that tag.
   54: 
   55: Each post appears under every tag it declares in #+filetags.  Lookup is
   56: O(1); the table mirrors `blog-posts' and should be rebuilt after every
   57: `blog--refresh-posts' call — cheapest to just call this fresh at each
   58: consumer (index/RSS loops)."
   59:   (let ((by-tag (make-hash-table :test #'equal)))
   60:     (dolist (p blog-posts)
   61:       (dolist (tag (s-split " " (map-elt p "tags") t))
   62:         (push p (gethash tag by-tag))))
   63:     (maphash (lambda (k v) (puthash k (nreverse v) by-tag)) by-tag)
   64:     by-tag))
   65: 
   66: (defun blog--make-rss-feed ()
   67:   "Emit rss.xml (all posts) plus one <tag>-rss.xml per tag."
   68:   (blog--make-one-rss-feed blog-posts "rss.xml")
   69:   (let ((by-tag (blog--posts-by-tag)))
   70:     (dolist (tag blog-tags)
   71:       (blog--make-one-rss-feed
   72:        (gethash tag by-tag)
   73:        (concat (blog--tag-slug tag) "-rss.xml")
   74:        (format "%s — %s" blog-title tag)))))
   75: 
   

   blog-posts, blog-tags, and their consumers: tag & index page generation

   blog-posts is a sorted list of post-alists (newest first), computed by scanning ~/blog/*.org directly. Its heavyweight consumer is blog-make-index-page, which iterates it to build every article card on the index and tag pages. blog-tags is a flat sorted list of unique tag strings derived from blog-posts — used for tag-page iteration and helm completion.

   Both are initialized once at the bottom of this file (after all helpers are defined) via (blog--refresh-posts), and refreshed after every publish.

    1: (defun blog--compute-posts-and-pages ()
    2:   "Scan ~/blog/*.org and return (posts . pages).
    3: 
    4: Every .org file is processed uniformly — there is no special-cased directory.
    5: Container files (#+article_style: multiple) yield many post entries; standalone
    6: files yield one.  A file with #+site_nav: contributes a nav-page entry instead
    7: of (or in addition to) a post entry.
    8: 
    9: posts — all entries, sorted newest-first.
   10: pages — site_nav entries, unsorted (used for the nav bar)."
   11:   (let ((posts '())
   12:         (pages '()))
   13:     (dolist (file (f-files blog-posts-directory))
   14:       (when (and (s-ends-with? ".org" file)
   15:                  (blog--publishable-p file))
   16:         (let ((infos (if (blog--multiple-style-p file)
   17:                          (blog--info-multiple file)
   18:                        (list (blog--info file)))))
   19:           (dolist (info infos)
   20:             (when (map-elt info "site_nav") (push info pages))
   21:             (push info posts)))))
   22:     (cons (sort posts (lambda (a b)
   23:                         (time-less-p (date-to-time (@date b))
   24:                                      (date-to-time (@date a)))))
   25:           pages)))
   26: 
   27: (defun blog--rebuild-preamble ()
   28:   "Regenerate blog-page-preamble from blog-pages.
   29: Falls back to blog--preamble-fallback when blog-pages is empty.
   30: Called automatically by blog--refresh-posts; also useful to call
   31: interactively after editing :SITE_NAV: headings."
   32:   (setq blog-page-preamble
   33:         (if (null blog-pages)
   34:             (blog--preamble-fallback)
   35:           (concat
   36:            "<div class=\"header\">\n"
   37:            "  <a href=\"https://alhassy.github.io/\" class=\"logo\">Life & Computing Science</a>\n"
   38:            "  <br/>\n"
   39:            (mapconcat (lambda (p)
   40:                         (format "  <a href=\"%s\">%s</a>\n" (@url p) (map-elt p "site_nav")))
   41:                       blog-pages "")
   42:            "</div>"))))
   43: 
   44: (defun blog--refresh-posts ()
   45:   "Recompute blog-posts, blog-pages, and blog-tags from source org files."
   46:   (let ((result (blog--compute-posts-and-pages)))
   47:     (setq blog-posts (car result))
   48:     (setq blog-pages (cdr result))
   49:     (setq blog-tags
   50:           (sort (seq-uniq (mapcan (lambda (it) (s-split " " (map-elt it "tags") t))
   51:                                   blog-posts))
   52:                 #'string<))
   53:     (blog--rebuild-preamble)))
   54: 
   55: (defvar blog-page-preamble ""
   56:   "HTML injected at the top of every exported page: the site nav bar.
   57: Set by blog--rebuild-preamble whenever blog-pages changes.")
   58: 
   59: (defvar blog-page-header ""
   60:   "HTML injected into the <head> of every exported page: CSS, JS, MathJax, etc.
   61: Set once at load time by the setq block near the blog-banner section.")
   62: 
   63: (defvar blog-posts nil
   64:   "All post metadata, sorted newest-first. Initialized at end of file; refresh with (blog--refresh-posts).")
   65: 
   66: (defvar blog-pages nil
   67:   "Site navigation page metadata (subtrees with :SITE_NAV: t).
   68: These appear as header links on every page but not as blog post cards.
   69: Initialized at end of file; refresh with (blog--refresh-posts).")
   70: 
   71: (defvar blog-tags nil
   72:   "Tags for my blog articles. Initialized at end of file; refresh with (blog--refresh-posts).")