diff options
Diffstat (limited to 'content/blog/2024-03-29-org-blog.org')
| -rw-r--r-- | content/blog/2024-03-29-org-blog.org | 270 |
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. |