cmc/cleberg.net

  1#+date:        [2024-03-29 Fri 00:00:00]
  2#+title:       Blogging with Emacs Org Mode and weblorg
  3#+description: How I set up this blog using Emacs Org Mode and weblorg.
  4#+slug:        org-blog
  5#+filetags:    :emacs:web:
  6
  7First and foremost, apologies to those who subscribe via RSS as I know that my
  8feed duplicated itself when I moved this blog over to org-mode last night.
  9
 10This post focuses specifically on the configuration and tools I use to blog from
 11Emacs with Org-Mode and does not focus on Emacs or Org-Mode themselves. Refer to
 12the post I wrote about [[https://cleberg.net/blog/doom-emacs-org-mode.html][Doom Emacs & Org-Mode]] for more information about my base
 13Emacs configuration.
 14
 15* Weblorg
 16
 17The first step in blogging with Org-Mode is to choose a method to convert the
 18source files to HTML and publish them. The Worg site maintains a nice list of
 19[[https://orgmode.org/worg/org-blog-wiki.html][Blogs and Wikis with Org]], but the tools are inevitably different and
 20opinionated, so you'll need to find what works for you.
 21
 22I tried using Jekyll, Hugo, ox-hugo, Nikola, Blorg, org-static-blog, and the
 23native org-publish functions before finally settling on Weblorg. For one reason
 24or another, the other solutions were a drastic step down from my previous
 25workflow that used [[https://www.getzola.org/][Zola]] with Markdown content.
 26
 27[[https://github.com/emacs-love/weblorg][Weblorg]] is a static site generator for [[https://orgmode.org/][org-mode]], built for use within [[https://www.gnu.org/software/emacs/][Emacs]].
 28Since it's written in Emacs Lisp, there's no need to install other languages or
 29frameworks to get started. More than that, you can write in any editor you
 30please and simply invoke the Emacs build process with the =--script= parameter
 31instead of requiring you to blog inside Emacs.
 32
 33** Installation
 34
 35The [[https://emacs.love/weblorg/doc/index.html][Getting Started]] page details broad installation requirements. I am using
 36Doom Emacs on macOS, which requires you to add the package to the
 37=~/.doom.d/packages.el= file and configure the =publish.el= file slightly
 38differently.
 39
 40To start, add the =htmlize= and =weblorg= packages to Doom, sync the changes,
 41and reload.
 42
 43#+begin_src sh
 44nano ~/.doom.d/packages.el
 45#+end_src
 46
 47#+begin_src lisp
 48(package! htmlize)
 49(package! weblorg)
 50#+end_src
 51
 52#+begin_src sh
 53doom sync
 54#+end_src
 55
 56Either re-open Emacs or hit =SPC h r r= to reload the changes.
 57
 58** Configuration
 59
 60Now that I've installed weblorg, I need to configure the project. I'll start by
 61navigating to my site's source code and creating a =publish.el= file.
 62
 63#+begin_src sh
 64cd ~/Source/cleberg.net && nano publish.el
 65#+end_src
 66
 67Since I'm using Doom, Emacs will not automatically load the packages I need
 68later in the build process. To compensate, my =publish.el= file needs to
 69explicitly tell Emacs where Doom stores the =htmlize=, =weblorg=, and
 70=templatel= packages.
 71
 72#+begin_src lisp
 73;; explicity load packages since I'm using Doom Emacs
 74(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/emacs-htmlize")
 75(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/weblorg")
 76(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/templatel")
 77(require 'htmlize)
 78(require 'weblorg)
 79
 80;; defaults to http://localhost:8000
 81;; To build with the custom URL below, call:
 82;;;; ENV=prod emacs --script publish.el
 83(if (string= (getenv "ENV") "prod")
 84 (setq weblorg-default-url "https://cleberg.net"))
 85
 86;; site metadata
 87(weblorg-site
 88 :theme nil
 89 :template-vars '(("site_name" . "cleberg.net")
 90                  ("site_owner" . "hello@cleberg.net")
 91                  ("site_description" . "Just a blip of ones and zeroes.")))
 92
 93;; route for rendering the index page of the website
 94(weblorg-route
 95 :name "index"
 96 :input-pattern "content/index.org"
 97 :template "index.html"
 98 :output ".build/index.html"
 99 :url "/")
100
101;; route for rendering each blog post
102(weblorg-route
103 :name "blog"
104 :input-pattern "content/blog/*.org"
105 :template "post.html"
106 :output ".build/blog/{{ slug }}.html"
107 :url "/blog/{{ slug }}.html")
108
109;; route for rendering the index page of the blog
110(weblorg-route
111 :name "blog-index"
112 :input-pattern "content/blog/*.org"
113 :input-aggregate #'weblorg-input-aggregate-all-desc
114 :template "blog.html"
115 :output ".build/blog/index.html"
116 :url "/blog/")
117
118;; route for rendering each wiki post
119(weblorg-route
120 :name "wiki"
121 :input-pattern "content/wiki/*.org"
122 :template "post.html"
123 :output ".build/wiki/{{ slug }}.html"
124 :url "/wiki/{{ slug }}.html")
125
126;; route for rendering the index page of the wiki
127(weblorg-route
128 :name "wiki-index"
129 :input-pattern "content/wiki/*.org"
130 :input-aggregate #'weblorg-input-aggregate-all
131 :template "wiki.html"
132 :output ".build/wiki/index.html"
133 :url "/wiki/")
134
135;; routes for rendering all other pages
136(weblorg-route
137 :name "pages"
138 :input-pattern "content/*.org"
139 :template "page.html"
140 :output ".build/{{ slug }}.html"
141 :url "/{{ slug }}.html")
142
143(weblorg-route
144 :name "salary"
145 :input-pattern "content/salary/*.org"
146 :template "page.html"
147 :output ".build/salary/{{ slug }}.html"
148 :url "/salary/{{ slug }}.html")
149
150(weblorg-route
151 :name "services"
152 :input-pattern "content/services/*.org"
153 :template "page.html"
154 :output ".build/services/{{ slug }}.html"
155 :url "/services/{{ slug }}.html")
156
157;; RSS Feed
158(weblorg-route
159 :name "rss"
160 :input-pattern "content/blog/*.org"
161 :input-aggregate #'weblorg-input-aggregate-all-desc
162 :template "feed.xml"
163 :output ".build/feed.xml"
164 :url "/feed.xml")
165
166;; route for static assets that also copies files to .build directory
167(weblorg-copy-static
168 :output ".build/{{ file }}"
169 :url "/{{ file }}")
170
171;; fire the engine and export all the files declared in the routes above
172(weblorg-export)
173#+end_src
174
175* Project
176
177** Structure
178
179The project structure for weblorg is highly customizable and the main
180restriction is that the =publish.el= file must point to the correct paths.
181
182For my blog, I prefer to keep the blog content out of the top-level directory.
183This results in the following structure (shortened for brevity):
184
185#+begin_src txt
186.build/
187content/
188    blog/
189        example-blog-post.org
190        index.org
191    wiki/
192        example-wiki-post.org
193        index.org
194    index.org
195    other-example-page.org
196theme/
197    static/
198        styles.css
199        robots.txt
200    templates/
201        base.html
202        blog.html
203        index.html
204        page.html
205        post.html
206        wiki.html
207build.sh
208publish.el
209#+end_src
210
211This is simply my preferred structure and you can alter it to fit your needs.
212The key here really is that you can customize at will, as long as the
213=publish.el= file matches.
214
215** Build & Deploy
216
217Once you're content with the status of the project, you're ready to build and
218deploy the blog.
219
220My process utilizes a =build.sh= script that combines the steps I take every
221time.
222
223#+begin_src sh
224touch build.sh && chmod +x build.sh && nano build.sh
225#+end_src
226
227Within this script, I do the following:
228
2291. Remove any files within the =.build= directory that I use to store published
230   files.
2312. Set the environment variable to =prod= to ensure the =base_url= matches my
232   configuration in =publish.el=.
2333. Build the site with Emacs & =publish.el=.
2344. Use =scp= to copy files to my site's public directory on my server.
235
236#+begin_src sh
237rm -rf .build/* && \
238ENV=prod emacs--script publish.el && \
239scp -r .build/* ubuntu:/var/www/cleberg.net/
240#+end_src
241
242*** Time to Build
243
244My only current complaints are:
245
2461. Errors messages are not helpful. It takes work to determine what the error is
247   and where it's coming from. I generally have to sit and watch the build
248   process to see the file that weblorg publishes right before the error
249   occurred.
2502. The build process re-builds every single file on each run, which takes a long
251   time for a blog of my size. See below for the last time I measured.
252
253#+begin_src sh
254> time ./build.sh
255
256./build.sh  35.46s user 0.59s system 85% cpu 41.965 total
257#+end_src
258
259Overall, I have thoroughly enjoyed using weblog and will continue to use it
260going forward until I find something better.