test conversion back to markdown

1 files changed, 277 insertions, 0 deletions

diff --git a/content/blog/2024-03-29-org-blog.md b/content/blog/2024-03-29-org-blog.md
new file mode 100644
index 0000000..93bbdaf
--- /dev/null
+++ b/content/blog/2024-03-29-org-blog.md
@@ -0,0 +1,277 @@
++++
+date = 2024-03-29
+title = "Blogging in Org-Mode"
+description = ""
+draft = false
++++
+
+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 [Doom Emacs &
+Org-Mode](file:///blog/doom-emacs-org-mode.html) 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 [Blogs and Wikis with
+Org](https://orgmode.org/worg/org-blog-wiki.html), 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 [Zola](https://www.getzola.org/) with
+Markdown content.
+
+[Weblorg](https://github.com/emacs-love/weblorg) is a static site
+generator for [org-mode](https://orgmode.org/), built for use within
+[Emacs](https://www.gnu.org/software/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 [Getting Started](https://emacs.love/weblorg/doc/index.html) 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.
+
+```sh
+nano ~/.doom.d/packages.el
+```
+
+```lisp
+(package! htmlize)
+(package! weblorg)
+```
+
+```sh
+doom sync
+```
+
+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.
+
+```sh
+cd ~/Source/cleberg.net && nano publish.el
+```
+
+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.
+
+```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 "atom.xml"
+ :output ".build/atom.xml"
+ :url "/atom.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)
+```
+
+# 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):
+
+``` 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
+```
+
+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.
+
+```sh
+touch build.sh && chmod +x build.sh && nano build.sh
+```
+
+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.
+
+```sh
+rm -rf .build/*                              && \
+ENV=prod emacs --script publish.el           && \
+scp -r .build/* ubuntu:/var/www/cleberg.net/
+```
+
+### 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.
+
+```sh
+> time ./build.sh
+
+./build.sh  35.46s user 0.59s system 85% cpu 41.965 total
+```
+
+Overall, I have thoroughly enjoyed using weblog and will continue to use
+it going forward until I find something better.