Hello World from Org

#+TITLE: Hello World from Org
#+DATE: [2025-05-25 Sun]
#+INCLUDE: ../../templates/post.org

#+begin_preview
I describe /yet-another-simple-publishing-setup/ for a static website using
Emacs's Org mode. While there are plenty of resources on the topic available
already, I wanted to document my setup here for self-reference. Maybe someone
will take away an idea or two.
#+end_preview

#+begin_src sh
skywhi@dreamland:~/org/blog$ echo "Hello World Wild Web!" > src/posts/hello.org
skywhi@dreamland:~/org/blog$ make update && make publish
skywhi@dreamland:~/org/blog$ # make blogging great again!
#+end_src

{{{toc(Contents:,6)}}}

* Rationale
:PROPERTIES:
:CUSTOM_ID: rationale
:END:

I figured the time had come to host some of my modest content online for
sharing, fun, persistence, easy access and all the other usual suspects. Going
into this adventure there were only a few requirements that I wanted my website
to meet: [...]

@@html:<span class="post-date">@@
/First published: {{{date(%d %b %Y)}}}/
@@html:</span>@@

If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt{2} $$ or
\[ a=-\sqrt{2} \]

Look at this lonely equation I found:

\begin{equation}
y = x^2+1
\end{equation}

MATHJAX_DIR=static/js/mathjax
MATHJAX_VERSION=4.1.3
MATHJAX_FONT=mathjax-modern
MATHJAX_FONT_VERSION=$(MATHJAX_VERSION)
NPM=https://registry.npmjs.org
TMP=$(MATHJAX_DIR).tmp

mathjax:
        rm -rf $(MATHJAX_DIR) $(TMP)
        mkdir -p $(TMP)/mathjax $(TMP)/font
        curl -fsSL $(NPM)/mathjax/-/mathjax-$(MATHJAX_VERSION).tgz \
            | tar xz -C $(TMP)/mathjax --strip-components=1
        curl -fsSL $(NPM)/@mathjax/$(MATHJAX_FONT)-font/-/$(MATHJAX_FONT)-font-$(MATHJAX_FONT_VERSION).tgz \
            | tar xz -C $(TMP)/font --strip-components=1
# [...] the rest of the target keeps only the files that are actually served.

;; MathJax resolves its font package against 'loader.paths.fonts', which
;; defaults to cdn.jsdelivr.net. The fonts are vendored (see the 'mathjax'
;; target in the Makefile), so that path has to be pointed at the local copy:
;; without it, every page carrying math quietly pulls ~1 MB of woff2 from a
;; third party -- on a site that otherwise makes no external request at all.
;; Org's stock template has no 'loader' section, hence the injection.
(defun skw-blog/mathjax-template-with-local-fonts (template)
  "Return 'template' with a loader path pointing MathJax at the vendored fonts."
  (let ((anchor "window.MathJax = {"))
    (unless (string-match-p (regexp-quote anchor) template)
      (error "MathJax template changed upstream: cannot inject the local font path"))
    (replace-regexp-in-string
     (regexp-quote anchor)
     (concat anchor "\n    loader: {paths: {fonts: '"
             skw-blog/mathjax-dir "/fonts'}},")
     template t t)))

(setq org-html-mathjax-options
      `((path ,(concat skw-blog/mathjax-dir "/tex-mml-chtml.js"))
        (scale 1.0) (align "center") (font "mathjax-modern") (overflow "overflow")
        (tags "ams") (indent "0em") (multlinewidth "85%") (tagindent ".8em")
        (tagside "right"))

      org-html-mathjax-template
      (skw-blog/mathjax-template-with-local-fonts org-html-mathjax-template))

;; RSS feed generation
(defun skw-blog/publish-to-rss (plist filename dir)
  "Publish 'plist' when 'filename' corresponds to RSS feed Org-file to 'dir'."
  (if (equal skw-blog/rss-filename (file-name-nondirectory filename))
      ;; Not `org-rss-publish-to-rss': it stamps a random :ID: on every headline
      ;; of rss.org and writes it back, so a plain "make all" dirties the source
      ;; tree for nothing -- <guid> is the permalink here anyway.
      (org-publish-org-to 'rss filename
                          (concat "." (or (plist-get plist :rss-extension)
                                          org-rss-extension))
                          plist dir)))

(defun skw-blog/format-rss-feed (title list)
  "Generate a sitemap of posts that will be exported as an RSS feed. 'title' is
title of the RSS feed and 'list' the files to be included."
  (concat "#+TITLE: " title "\n\n" (org-list-to-subtree list)))

(defun skw-blog/format-rss-feed-entry (entry style project)
  "Format 'entry' for the posts RSS feed in given 'project'."
  (let* ((title (org-publish-find-title entry project))
         (link (concat (file-name-sans-extension entry) ".html"))
         (pubdate (format-time-string (car org-time-stamp-formats)
                                      (org-publish-find-date entry project)))
         (preview (skw-blog/get-preview (concat (skw-blog/get-root-directory) "src/posts/" entry))))

    (format "%s
:properties:
:rss_permalink: %s
:pubdate: %s
:end:
%s" title link pubdate preview)))

("website-rss"
 :author ,skw-blog/author
 :auto-sitemap t
 :base-directory ,(concat skw-blog/srcdir "posts")
 :base-extension "org"
 :description ,skw-blog/rss-description
 :email ,skw-blog/email
 :exclude ,(regexp-opt '("rss.org" "index.org" "index-no-preview.org"))
 :html-link-home ,(concat skw-blog/upstream-url "/posts/")
 :html-link-org-files-as-html t
 :html-link-use-abs-url t
 :publishing-directory ,skw-blog/outdir
 :publishing-function skw-blog/publish-to-rss
 :recursive nil
 :rss-extension "xml"
 :rss-feed-url ,(concat skw-blog/upstream-url "/rss.xml")
 :rss-image-url ,(concat skw-blog/upstream-url "/static/img/profile.jpg")
 :sitemap-filename ,skw-blog/rss-filename
 :sitemap-format-entry skw-blog/format-rss-feed-entry
 :sitemap-function skw-blog/format-rss-feed
 :sitemap-sort-files anti-chronologically
 :sitemap-title ,skw-blog/rss-feedname
 :with-author t)

;; Feed autodiscovery, so readers can find the feed from any page
(setq skw-blog/rss-link
      (concat "<link rel=\"alternate\" type=\"application/rss+xml\" title=\""
              skw-blog/rss-feedname "\" href=\"/rss.xml\">\n"))

(defun skw-blog/html-page-backend-p (backend)
  "Return non-nil when 'backend' exports whole HTML pages rather than feed items."
  (and (org-export-derived-backend-p backend 'html)
       (not (org-export-derived-backend-p backend 'rss))))

(defun skw-blog/add-heading-anchor (headline backend info)
  "Append a permalink anchor to the heading that opens 'headline'.
Only headings carrying a CUSTOM_ID get one: Org derives every other id from
a counter that shifts as soon as the document changes, so such a link would
rot silently."
  (if (not (skw-blog/html-page-backend-p backend))
      headline
    (save-match-data
      ;; Children are filtered before their parent, so the first heading tag in
      ;; 'headline' is always the one this call is responsible for.
      (if (not (string-match "<h\\([1-6]\\) id=\"\\([^\"]+\\)\">" headline))
          headline
        (let ((level (match-string 1 headline))
              (id (match-string 2 headline))
              (from (match-end 0)))
          (if (string-match-p "\\`org[0-9a-f]+\\'" id)
              headline
            (let ((close (string-match (concat "</h" level ">") headline from)))
              (if (null close)
                  headline
                (concat (substring headline 0 close)
                        (format (concat "<a class=\"heading-anchor\" href=\"#%s\""
                                        " aria-label=\"Permalink to this section\">#</a>")
                                id)
                        (substring headline close))))))))))

(add-to-list 'org-export-filter-headline-functions
             #'skw-blog/add-heading-anchor)

(defun skw-blog/page-path (input-file)
  "Return the site-root-relative path at which 'input-file' is served."
  (let* ((relative (file-relative-name (expand-file-name input-file)
                                       skw-blog/srcdir))
         (html (concat (file-name-sans-extension relative) ".html")))
    (cond ((equal html "index.html") "/")
          ((string-suffix-p "/index.html" html)
           (concat "/" (file-name-directory html)))
          (t (concat "/" html)))))


(defun skw-blog/attribute-value (string)
  "Return 'string' escaped for use as an HTML attribute value.
'org-html-encode-plain-text' leaves double quotes alone, which is fine for
text nodes and silently breaks an attribute the first time a title or a
description contains one."
  (replace-regexp-in-string "\"" """ (org-html-encode-plain-text string) t t))


(defun skw-blog/page-metadata (info)
  "Return the canonical, Open Graph and Twitter tags for the page in 'info'."
  (let* ((input (plist-get info :input-file))
         (path (and input (skw-blog/page-path input)))
         (url (and path (concat skw-blog/upstream-url path)))
         (title (skw-blog/attribute-value
                 (org-element-interpret-data (plist-get info :title))))
         (description (skw-blog/attribute-value skw-blog/rss-description))
         ;; Posts and notes are articles; the homepage and the standing pages
         ;; around them are not.
         (type (if (and path (string-match-p "\\`/\\(posts\\|notes\\)/." path))
                   "article"
                 "website"))
         (tags '()))
    (when url
      (push (format "<link rel=\"canonical\" href=\"%s\">" url) tags)
      (push (format "<meta property=\"og:url\" content=\"%s\">" url) tags))
    (push (format "<meta property=\"og:type\" content=\"%s\">" type) tags)
    (push (format "<meta property=\"og:site_name\" content=\"%s\">"
                  (skw-blog/attribute-value skw-blog/site-name))
          tags)
    (push (format "<meta property=\"og:title\" content=\"%s\">" title) tags)
    (push (format "<meta property=\"og:description\" content=\"%s\">" description) tags)
    (push (format "<meta property=\"og:image\" content=\"%s\">" skw-blog/og-image) tags)
    (push "<meta name=\"twitter:card\" content=\"summary\">" tags)
    ;; The 404 is served for every unknown path. Indexing it would scatter
    ;; "No such file or directory" across search results.
    (when (and input (equal (file-name-nondirectory input) "404.org"))
      (push "<meta name=\"robots\" content=\"noindex\">" tags))
    (concat (mapconcat #'identity (nreverse tags) "\n") "\n")))


(defun skw-blog/insert-page-metadata (output backend info)
  "Insert the tags built by 'skw-blog/page-metadata' into 'output's head."
  (if (not (skw-blog/html-page-backend-p backend))
      output
    (save-match-data
      (if (not (string-match "</head>" output))
          output
        (replace-match (concat (skw-blog/page-metadata info) "</head>")
                       t t output)))))

(add-to-list 'org-export-filter-final-output-functions
             #'skw-blog/insert-page-metadata)

;; Shown when a page is shared on a platform that renders a link preview.
;; A 256x256 crop of the same picture as the favicon: the square shape suits
;; the summary card, and profile.jpg is 138x138, under the 144px floor below
;; which several platforms drop the image entirely.
(setq skw-blog/og-image
      (concat skw-blog/upstream-url "/static/img/og-image.jpg"))