A literate programming file for publishing my website using org.
While the Emacs community have a plethora of options for generating a static website from org-formatted files, I keep my pretty simple, and use the standard org-publish feature.
While the following packages come with Emacs, they aren’t necessarily loaded:
(use-package org
:config
(require 'ox-html)
(require 'ox-rss)
(require 'ox-publish))Render my code with my font colors:
(use-package htmlize
:config
;; But I turn the source code coloring off to use a CSS stylesheet I
;; control, as otherwise, switching between dark and light themes
;; make the code difficult to read:
(setq org-html-htmlize-output-type 'css))Also, we need Jack, and his HTML prowess:
(use-package jack
:straight (:host github :repo "tonyaldon/jack")
:commands (jack-html))Variable settings:
(setq org-publish-project-alist nil ; filled in below
org-export-with-broken-links t
org-mode-websrc-directory "~/website"
org-mode-publishing-directory (concat (getenv "HOME") "/website-pub/"))Since I have two specific websites, I create two variables for those destinations:
(setq ha-publishing-howardabrams (concat org-mode-publishing-directory "howardabrams")
ha-publishing-howardism (concat org-mode-publishing-directory "howardisms"))I separate my website into distinct projects separately built:
blog-content- The bulk of rendering my
websiteorg files into HTML blog-static- Copies all assets, like images, in place
blog-rss- Regenerate the feeder files
org-notes- Optionally render a non-web site collection of notes.
Years of having two domain names can be confusing, but I have to keep them going now. My howardabrams.com is essentially a single static page (oh, and email).
(add-to-list 'org-publish-project-alist
`("website"
:base-directory "~/dropbox/website-howardabrams"
:publishing-directory ,ha-publishing-howardabrams))(add-to-list 'org-publish-project-alist
`("blog-content"
:base-directory ,org-mode-websrc-directory
:base-extension "org"
:publishing-directory ,org-mode-publishing-directory
:recursive t
:publishing-function org-html-publish-to-html
:preparation-function org-mode-blog-prepare
:export-with-tags nil
:headline-levels 4
:auto-preamble nil
:auto-postamble nil
:auto-sitemap t
:sitemap-title "Howardisms"
:section-numbers nil
:table-of-contents nil
:with-toc nil
:with-title t
:with-author nil
:with-creator nil
:with-tags nil
:with-smart-quotes t
:html-doctype "html5"
:html-html5-fancy t
:html-head-include-default-style nil
;; :html-preamble org-mode-blog-preamble
:html-postamble org-mode-blog-postamble
;; :html-postamble "<hr><div id='comments'></div>"
:html-head-extra
,(jack-html
'((:link (@ :rel "alternate"
:type "application/rss+xml"
:title "RSS"
:href "https://www.howardism.org/index.xml"))
(:link (@ :rel "stylesheet"
:type "text/css"
:href "http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700&subset=latin,latin-ext"))
(:link (@ :rel "stylesheet"
:type "text/css"
:href "http://fonts.googleapis.com/css?family=Source+Serif+Pro:400,700&subset=latin,latin-ext"))
(:link (@ :rel "stylesheet"
:type "text/css"
:href "http://fonts.googleapis.com/css?family=Source+Code+Pro:400,700"))
(:link (@ :rel "stylesheet"
:type "text/css"
:href "/css/styles.css"))
(:script (@ :type "text/javascript"
:src "https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"))
(:script (@ :src "/js/magic.js" :type "text/javascript"))
(:meta (@ :name "viewport" :content "width=device-width, initial-scale=1"))
(:link (@ :rel "shortcut icon" :href "/img/dragon-head.svg"))
(:link (@ :rel "icon" :href "/img/dragon.svg"))
(:link (@ :rel "me" :href "https://pdx.sh/@howard"))
(:meta (@ :http-equiv "X-Clacks-Overhead" :content "Darol Allen"))
(:meta (@ :http-equiv "X-Clacks-Overhead" :content "George Vanecek"))
(:meta (@ :http-equiv "X-Clacks-Overhead" :content "Rick Cooper"))
(:meta (@ :http-equiv "X-Clacks-Overhead" :content "Terry Pratchett"))))))Why not break out the images and other static files into a separate project:
(add-to-list 'org-publish-project-alist
`("blog-static"
:base-directory ,org-mode-websrc-directory
:base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|svg"
:publishing-directory ,org-mode-publishing-directory
:recursive t
:publishing-function org-publish-attachment))The RSS generation seems to be something I do later once I have my site working:
(add-to-list 'org-publish-project-alist
`("blog-rss"
:base-directory ,org-mode-websrc-directory
:base-extension "org"
:rss-image-url "https://howardism.org/img/dragon-head.png"
:publishing-directory ,org-mode-publishing-directory
:publishing-function (org-rss-publish-to-rss)
:html-link-home "https://www.howardism.org/"
:html-link-use-abs-url t
:with-toc nil
:exclude ".*"
:include ("index.org")))And let’s make some blends of the individual projects:
(add-to-list 'org-publish-project-alist
`("blog" :components ("blog-content" "blog-static" "blog-rss")))I take notes on a variety of technical subjects, and since I can share these notes with others, I feel like I can publish those:
(add-to-list 'org-publish-project-alist
`("tech-notes"
:base-directory "~/technical/"
:base-extension "org"
:publishing-directory ,(concat org-mode-publishing-directory "notes/")
:recursive t
:publishing-function org-html-publish-to-html
:headline-levels 4
:auto-preamble t
:auto-sitemap t ; Generate sitemap.org automagically...
:makeindex t
:section-numbers nil
:style ,(jack-html
'(:link (@ :rel "stylesheet"
:type "text/css"
:href "../css/styles.css")
:script (@ :type "text/javascript"
:src "https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js")
:link (@ :ref "stylesheet"
:type "text/css"
:href "http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/themes/smoothness/jquery-ui.css")
:script (@ :type "text/javascript"
:src "https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.16/jquery-ui.min.js")
:script (@ :type "text/javascript"
:src "js/magic.js")))
:table-of-contents nil
:with-title t
:with-author nil
:with-creator nil
:with-tags nil))As above, we can separate the publishing of the images and other static files:
(add-to-list 'org-publish-project-alist
`("tech-notes-static"
:base-directory "~/technical/"
:base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|svg"
:publishing-directory ,(concat org-mode-publishing-directory "/src/")
:recursive t
:publishing-function org-publish-attachment))I’ve been committing my literate-style Emacs configuration for years now, and Github has rendered it well, but I felt I could publish this to my own web site as a cleaner version.
(add-to-list 'org-publish-project-alist
`("hamacs"
:base-directory "~/src/hamacs"
:publishing-directory ,(concat org-mode-publishing-directory "hamacs/")
:publishing-function org-html-publish-to-html
:recursive t
:auto-preamble nil
:auto-sitemap nil
:makeindex nil
:section-numbers nil
:html-head-include-default-style nil
:html-head ,(jack-html
'(:link (@ :rel "stylesheet" :type "text/css"
:href "../css/styles.css")))
:html-head-extra nil
:table-of-contents t
:with-title t
:with-author nil
:with-creator nil
:with-tags nil))
(add-to-list 'org-publish-project-alist
`("hamacs-static"
:base-directory "~/src/hamacs"
:base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|svg"
:publishing-directory ,(concat org-mode-publishing-directory "hamacs")
:recursive t
:publishing-function org-publish-attachment))I have an ADU on my property that I rent out through Airbnb. The place is full of QR Codes that display everything from local restaurants to how to play the Raspberry Pi Arcade my son and I built.
(add-to-list 'org-publish-project-alist
`("airbnb"
:base-directory "~/website/airbnb"
:publishing-directory ,(concat org-mode-publishing-directory "airbnb/")
:publishing-function org-html-publish-to-html
:recursive t
:auto-preamble nil
:auto-sitemap nil
:makeindex nil
:section-numbers nil
:html-head-include-default-style nil
:html-head ,(jack-html
'(:link (@ :rel "stylesheet" :type "text/css"
:href "airbnb.css")))
:html-head-extra nil
:table-of-contents nil
:with-title t
:with-author nil
:with-creator nil
:with-tags nil))
(add-to-list 'org-publish-project-alist
`("airbnb-static"
:base-directory "~/website/airbnb"
:base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|svg"
:publishing-directory ,(concat org-mode-publishing-directory "airbnb/")
:recursive t
:publishing-function org-publish-attachment))In the project definitions, I reference a pre- and postamble that allow me to inject some standard HTML file headers and footers:
(defun org-mode-blog-preamble (options)
"The function that creates the preamble top section for the blog.
OPTIONS contains the property list from the org-mode export."
(message "Preamble options: %s" (princ options))
(let ((base-directory (plist-get options :base-directory)))
(org-babel-with-temp-filebuffer (expand-file-name "top-bar.html" base-directory) (buffer-string))))
(defun org-mode-blog-postamble (options)
"The function that creates the postamble, or bottom section for the blog.
OPTIONS contains the property list from the org-mode export."
(let ((base-directory (plist-get options :base-directory)))
(org-babel-with-temp-filebuffer (expand-file-name "bottom.html" base-directory) (buffer-string))))Another helper function for the content of website is to make sure to update index.org, so that the RSS gets generated.
(defun org-mode-blog-prepare (&optional options)
"Change modification of `index.org' before publishing."
(let* ((base-directory (plist-get options :base-directory))
(buffer (find-file-noselect (expand-file-name "index.org" base-directory) t)))
(with-current-buffer buffer
(set-buffer-modified-p t)
(save-buffer 0))
(kill-buffer buffer)))Using rsync to keep published files in sync with my website:
(defun ha-sync-site (project)
"Sync PROJECT (an org publish project) with my website."
(interactive (list (completing-read "Publish project: "
org-publish-project-alist)))
(let* ((host "gremlin.howardabrams.com")
(conf (thread-last org-publish-project-alist
(seq-filter (lambda (lst) (string-equal (car lst) project)))
(car)
(cdr)))
(parent (plist-get conf :publishing-directory))
(combos (cond
((s-starts-with? "blog" project)
'("Technical" "howardism"
"Personal" "howardism"
"RPG" "howardism"
"index.html" "howardism"
"about-me.html" "howardabrams"))
((s-starts-with? "tech" project) '("" "howardabrams"))
((s-starts-with? "hamacs" project) '("" "howardabrams"))
((s-starts-with? "airbnb" project) '("" "howardabrams")))))
;; (dolist (tuple (seq-partition combos 2))
;; (seq-let (src dest) tuple
;; (format "rsync -az %s/%s %s:%s" parent src host dest)))
(thread-last (seq-partition combos 2)
(seq-map (lambda (tuple) (seq-let (src dest) tuple
(format "rsync -avz %s%s %s:%s" parent src host dest))))
(s-join "; ")
(message)
(async-shell-command))))A single function to publish and sync my literate initialization of Emacs.
The idea is that pushing a Git commit to this project, triggers a Forgejo Workflow, that exports the literate text as HTML to my website.
(defun hamacs-publishing-workflow ()
"Render and push a new web version of my Emacs initialization."
(interactive)
(org-publish-project "hamacs")
(org-publish-project "hamacs-static")
(ha-sync-site "hamacs"))Make it easy to publish all projects or single project:
(ha-leader :keymaps 'org-mode-map
"o p" '(:ignore t :which-key "publish")
"o p a" '("all" . org-publish-all)
"o p p" '("project" . org-publish-project)
"o p s" '("sync site" . ha-sync-site)
"o p h" '("hamacs" . (lambda () (interactive)
(org-publish-project "hamacs")
(sit-for 30)
(ha-sync-site "hamacs"))))And let’s put a leader key sequence for my favorite file on my website:
(ha-leader
"f h" '(:ignore t :which-key "howards")
"f h i" '("website index" . (lambda ()
(find-file (expand-file-name "index.org" "~/website")))))Let’s provide a name so we can require it:
Before you can build this on a new system, make sure that you put the cursor over any of these properties, and hit: C-c C-c