As of I build Take on Rules via a Static Site Generator (SSG 📖). Hugo 📖 to be precise. I write locally, run a build process which generates static Hypertext Markup Language (HTML 📖) pages. I push those pages to a host which is then serves those via a bare-bones web-server. I cannot express how much I appreciate that my personal blog eschews a complex web application server. My web server has no “keys to the kingdom.” It simply knows about the static pages that I give it to render.
Throughout this post, I reference functions that are in my my Emacs configuration.
Preliminary Work
Throughout my days, I’m reading code, writing code, documentation, and commit messages; I’m thinking through different implementation approaches for processes; reading blog posts around my hobbies and my profession; reading books for learning and pleasure. All of which I might be writing down little pointers or notes to what I am doing.
Those little pointers begin to take shape in my mind.
Composing a Blog Post
In Emacs 📖. I start writing my blog post by calling M-x jf/denote-create--blog-posts--default.
I might instead move a note into my blog-post sub-directory; which means it’s something I might make public.
This prompts me to:
While writing I leverage several different commands, some of those are as follows:
jf/denote-link-or-create- Search for and insert a link to an existing document in my Personal Knowledge Management (PKM 📖).
org-insert-link- Pick the type of link, describe it then insert a link to the corresponding resource. Links can be dates, abbreviations, epigraphs, files, Uniform Resource Locators (URLs 📖), and many other things provided by the default Org-Mode.
org-insert-structure-template- To insert
src,details,summary,marginnote,inline_comments org-footnote-action- To create a footnote, which converts into a
sidenotewhen exporting to my blog. See Hacking Org-Mode Export for Footnotes as Sidenotes. jf/org-capf- Some custom completion at point functions; in particular auto-completing existing abbreviations; beware when I’m in a list the
capfdoes not work.
Another important function is my jf/org-mode/capture/insert-content-dwim. This builds on the Org-Mode clocking function.
See Clocking Work Time (The Org Manual) for more documentation on Org-Mode “clocking.”
When I start a clock on a blog post, I can use jf/org-mode/capture/insert-content-dwim to quickly capture text and context from other buffers.
Leveraging HTML Semantics via Macro Substitution
Org-Mode is a great markup format, but it doesn’t map to many semantic elements of HTML. Something that I appreciate. And because I’ve chosen semantic markup, I can more readily redesign my site using Cascading Stylesheet (CSS 📖).
I also have several Org-Mode replacement macros. See Macro Replacement (The Org Manual).
- cite
- This will export the text into a CITE element.
- idiomatic
- This will export the text into a I element; once meaning italics and now meaning idiomatic.
- kbd
- This will export the text into a KBD element.
Each of those macros have corresponding Tempel templates which also provide completing-read functionality by looking up all references on my local file-system.
See my templates file.
I have a bq template that I can use to generate a BLOCKQUOTE element with cite, url, and attribution attributes.
See the bq template definition here.
About Links in My PKM
, I have just over 3000 entries in my PKM. 858 of those entries are blog posts I’ve published. In my Denote Emacs Configuration blog post, I wrote about the different domains of my PKM:
- blog-posts
- the blog posts I write
- epigraphs
- the epigraphs and quotes I’ve collected
- glossary
- my link farm of terms and concepts
- indices
- top-level indices to organize concepts
- melange
- a general junk drawer
- people
- people I know or don’t know
- scientist
- my work
By linking my “to be published” blog posts to internal notes, I can look at my internal notes and see their backlinks. That is what blog posts link to what notes. This is done through the denote-link-backlinks function.
See Denote’s documentation on the Backlinks buffer.
Exporting a Blog Post
I use the Ox-Hugo 📖 package for exporting my blog post. I have written several overrides to the export process:
- Configure to export back-ticks (e.g.
`) for code blocks, instead of indentations. - Override foot note generation for side notes.
- Override how I export links, to leverage my glossary and other custom mechanisms.
One advantage in overriding how my blog exports foot notes is that if when I choose to export my blog post into other formats (e.g. a Portable Document Format (PDF 📖) via LaTeX 📖), I still get foot notes.
Reviewing the Blog Post
With my blog post exported, I switch over to ~/git/takeonrules.source/, a Hugo project that builds the static site that is Take on Rules.
I run the following Hugo command: hugo serve -D.
The -D flag tells Hugo to build and serve both published and draft pages.
This starts a web server which can be accessed at https://localhost:1313.
The default port when locally running Hugo.
(the default port for Hugo).
Publishing a Blog Post
Having checked the blog post on my local machine, I run the following command: bundle exec rake one_shot_publish.
That command does many things: first, it runs audits to ensure well-formed content.
Somewhere around version 0.78.0 of Hugo, I was encountering rendering snafus. If memory serves, it was around the time that the maintainers were switching from one Markdown processor to another.
It also fetches data from my PKM and generates metadata for my site.
The List of All Tables being one of those.
Eventually it creates the public directory and pushes that to my Virtual Private Server (VPS 📖).
Socializing the Blog Post
Sometimes I’ll syndicate to other platforms (e.g. the DEV Community 📖). Other times I’ll post to the corresponding sub-reddit. I might also post a quick link up on Mastodon 📖. Once upon a time, I would also post to Twitter. But I Deactivated my Twitter Account.
Conclusion
I wrote this playbook as a meditation on what steps I take to bring things forward from my personal note taking process into blog posts. These days, the notes I take are now readily available to convert into blog posts for sharing.