conversion from Zola to Weblorg

1 files changed, 270 insertions, 0 deletions

diff --git a/content/blog/2024-03-29-org-blog.org b/content/blog/2024-03-29-org-blog.org
new file mode 100644
index 0000000..10ae149
--- /dev/null
+++ b/content/blog/2024-03-29-org-blog.org
@@ -0,0 +1,270 @@
+#+date: <2024-03-29>
+#+title: Blogging in Org-Mode 
+#+description: 
+
+
+First and foremost, apologies to those who subscribe via RSS as I know
+that my feed duplicated itself when I moved this blog over to org-mode
+last night.
+
+This post focuses specifically on the configuration and tools I use to
+blog from Emacs with Org-Mode and does not focus on Emacs or Org-Mode
+themselves. Refer to the post I wrote about
+[[file:///blog/doom-emacs-org-mode.html][Doom Emacs & Org-Mode]] for
+more information about my base Emacs configuration.
+
+* Weblorg
+
+The first step in blogging with Org-Mode is to choose a method to
+convert the source files to HTML and publish them. The Worg site
+maintains a nice list of
+[[https://orgmode.org/worg/org-blog-wiki.html][Blogs and Wikis with
+Org]], but the tools are inevitably different and opinionated, so you'll
+need to find what works for you.
+
+I tried using Jekyll, Hugo, ox-hugo, Nikola, Blorg, org-static-blog, and
+the native org-publish functions before finally settling on Weblorg. For
+one reason or another, the other solutions were a drastic step down from
+my previous workflow that used [[https://www.getzola.org/][Zola]] with
+Markdown content.
+
+[[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]]. Since it's written in
+Emacs Lisp, there's no need to install other languages or frameworks to
+get started. More than that, you can write in any editor you please and
+simply invoke the Emacs build process with the =--script= parameter
+instead of requiring you to blog inside Emacs.
+
+** Installation
+
+The [[https://emacs.love/weblorg/doc/index.html][Getting Started]] page
+details broad installation requirements. I am using Doom Emacs on macOS,
+which requires you to add the package to the =~/.doom.d/packages.el=
+file and configure the =publish.el= file slightly differently.
+
+To start, add the =htmlize= and =weblorg= packages to Doom, sync the
+changes, and reload.
+
+#+begin_src sh
+nano ~/.doom.d/packages.el
+#+end_src
+
+#+begin_src lisp
+(package! htmlize)
+(package! weblorg)
+#+end_src
+
+#+begin_src sh
+doom sync
+#+end_src
+
+Either re-open Emacs or hit =SPC h r r= to reload the changes.
+
+** Configuration
+
+Now that I've installed weblorg, I need to configure the project. I'll
+start by navigating to my site's source code and creating a =publish.el=
+file.
+
+#+begin_src sh
+cd ~/Source/cleberg.net && nano publish.el
+#+end_src
+
+Since I'm using Doom, Emacs will not automatically load the packages I
+need later in the build process. To compensate, my =publish.el= file
+needs to explicitly tell Emacs where Doom stores the =htmlize=,
+=weblorg=, and =templatel= packages.
+
+#+begin_src lisp
+;; explicity load packages since I'm using Doom Emacs
+(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/emacs-htmlize")
+(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/weblorg")
+(add-to-list 'load-path "~/.emacs.d/.local/straight/repos/templatel")
+(require 'htmlize)
+(require 'weblorg)
+
+;; defaults to http://localhost:8000
+;; To build with the custom URL below, call:
+;;;; ENV=prod emacs --script publish.el
+(if (string= (getenv "ENV") "prod")
+ (setq weblorg-default-url "https://cleberg.net"))
+
+;; site metadata
+(weblorg-site
+ :theme nil
+ :template-vars '(("site_name" . "cleberg.net")
+                  ("site_owner" . "hello@cleberg.net")
+                  ("site_description" . "Just a blip of ones and zeroes.")))
+
+;; route for rendering the index page of the website
+(weblorg-route
+ :name "index"
+ :input-pattern "content/index.org"
+ :template "index.html"
+ :output ".build/index.html"
+ :url "/")
+
+;; route for rendering each blog post
+(weblorg-route
+ :name "blog"
+ :input-pattern "content/blog/*.org"
+ :template "post.html"
+ :output ".build/blog/{{ slug }}.html"
+ :url "/blog/{{ slug }}.html")
+
+;; route for rendering the index page of the blog
+(weblorg-route
+ :name "blog-index"
+ :input-pattern "content/blog/*.org"
+ :input-aggregate #'weblorg-input-aggregate-all-desc
+ :template "blog.html"
+ :output ".build/blog/index.html"
+ :url "/blog/")
+
+;; route for rendering each wiki post
+(weblorg-route
+ :name "wiki"
+ :input-pattern "content/wiki/*.org"
+ :template "post.html"
+ :output ".build/wiki/{{ slug }}.html"
+ :url "/wiki/{{ slug }}.html")
+
+;; route for rendering the index page of the wiki
+(weblorg-route
+ :name "wiki-index"
+ :input-pattern "content/wiki/*.org"
+ :input-aggregate #'weblorg-input-aggregate-all
+ :template "wiki.html"
+ :output ".build/wiki/index.html"
+ :url "/wiki/")
+
+;; routes for rendering all other pages
+(weblorg-route
+ :name "pages"
+ :input-pattern "content/*.org"
+ :template "page.html"
+ :output ".build/{{ slug }}.html"
+ :url "/{{ slug }}.html")
+
+(weblorg-route
+ :name "salary"
+ :input-pattern "content/salary/*.org"
+ :template "page.html"
+ :output ".build/salary/{{ slug }}.html"
+ :url "/salary/{{ slug }}.html")
+
+(weblorg-route
+ :name "services"
+ :input-pattern "content/services/*.org"
+ :template "page.html"
+ :output ".build/services/{{ slug }}.html"
+ :url "/services/{{ slug }}.html")
+
+;; RSS Feed
+(weblorg-route
+ :name "rss"
+ :input-pattern "content/blog/*.org"
+ :input-aggregate #'weblorg-input-aggregate-all-desc
+ :template "feed.xml"
+ :output ".build/feed.xml"
+ :url "/feed.xml")
+
+;; route for static assets that also copies files to .build directory
+(weblorg-copy-static
+ :output ".build/{{ file }}"
+ :url "/{{ file }}")
+
+;; fire the engine and export all the files declared in the routes above
+(weblorg-export)
+#+end_src
+
+* Project
+
+** Structure
+
+The project structure for weblorg is highly customizable and the main
+restriction is that the =publish.el= file must point to the correct
+paths.
+
+For my blog, I prefer to keep the blog content out of the top-level
+directory. This results in the following structure (shortened for
+brevity):
+
+#+begin_src txt
+.build/
+content/
+    blog/
+        example-blog-post.org
+        index.org
+    wiki/
+        example-wiki-post.org
+        index.org
+    index.org
+    other-example-page.org
+theme/
+    static/
+        styles.css
+        robots.txt
+    templates/
+        base.html
+        blog.html
+        index.html
+        page.html
+        post.html
+        wiki.html
+build.sh
+publish.el
+#+end_src
+
+This is simply my preferred structure and you can alter it to fit your
+needs. The key here really is that you can customize at will, as long as
+the =publish.el= file matches.
+
+** Build & Deploy
+
+Once you're content with the status of the project, you're ready to
+build and deploy the blog.
+
+My process utilizes a =build.sh= script that combines the steps I take
+every time.
+
+#+begin_src sh
+touch build.sh && chmod +x build.sh && nano build.sh
+#+end_src
+
+Within this script, I do the following:
+
+1. Remove any files within the =.build= directory that I use to store
+   published files.
+2. Set the environment variable to =prod= to ensure the =base_url=
+   matches my configuration in =publish.el=.
+3. Build the site with Emacs & =publish.el=.
+4. Use =scp= to copy files to my site's public directory on my server.
+
+#+begin_src sh
+rm -rf .build/*                              && \
+ENV=prod emacs --script publish.el           && \
+scp -r .build/* ubuntu:/var/www/cleberg.net/
+#+end_src
+
+*** Time to Build
+
+My only current complaints are:
+
+1. Errors messages are not helpful. It takes work to determine what the
+   error is and where it's coming from. I generally have to sit and
+   watch the build process to see the file that weblorg pubslishes right
+   before the error occurred.
+2. The build process re-builds every single file on each run, which
+   takes a long time for a blog of my size. See below for the last time
+   I measured.
+
+#+begin_src sh
+> time ./build.sh
+
+./build.sh  35.46s user 0.59s system 85% cpu 41.965 total
+#+end_src
+
+Overall, I have thoroughly enjoyed using weblog and will continue to use
+it going forward until I find something better.