diff options
Diffstat (limited to 'content/blog/2024-03-29-org-blog.org')
| -rw-r--r-- | content/blog/2024-03-29-org-blog.org | 123 |
1 files changed, 56 insertions, 67 deletions
diff --git a/content/blog/2024-03-29-org-blog.org b/content/blog/2024-03-29-org-blog.org index db60c65..5ae1a2b 100644 --- a/content/blog/2024-03-29-org-blog.org +++ b/content/blog/2024-03-29-org-blog.org @@ -3,48 +3,41 @@ #+description: #+slug: org-blog -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. +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 -[[https://cleberg.net/blog/doom-emacs-org-mode.html][Doom Emacs & Org-Mode]] for -more information about my base Emacs configuration. +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 [[https://cleberg.net/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 +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. +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. +To start, add the =htmlize= and =weblorg= packages to Doom, sync the changes, +and reload. #+begin_src sh nano ~/.doom.d/packages.el @@ -63,18 +56,17 @@ 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. +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. +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 @@ -184,12 +176,10 @@ needs to explicitly tell Emacs where Doom stores the =htmlize=, ** 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. +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): +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/ @@ -217,17 +207,17 @@ 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. +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. +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. +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 @@ -235,16 +225,16 @@ 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=. +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 && \ +rm -rf .build/* && \ +ENV=prod emacs--script publish.el && \ scp -r .build/* ubuntu:/var/www/cleberg.net/ #+end_src @@ -252,13 +242,12 @@ scp -r .build/* ubuntu:/var/www/cleberg.net/ 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. +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 @@ -266,5 +255,5 @@ My only current complaints are: ./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. +Overall, I have thoroughly enjoyed using weblog and will continue to use it +going forward until I find something better. |