diff options
Diffstat (limited to 'content/blog/2024-03-29-org-blog.md')
| -rw-r--r-- | content/blog/2024-03-29-org-blog.md | 132 |
1 files changed, 60 insertions, 72 deletions
diff --git a/content/blog/2024-03-29-org-blog.md b/content/blog/2024-03-29-org-blog.md index 93bbdaf..714f8db 100644 --- a/content/blog/2024-03-29-org-blog.md +++ b/content/blog/2024-03-29-org-blog.md @@ -5,49 +5,45 @@ 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. +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. +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. +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 +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. +To start, add the `htmlize` and `weblorg` packages to Doom, sync the changes, +and reload. ```sh nano ~/.doom.d/packages.el @@ -62,23 +58,20 @@ nano ~/.doom.d/packages.el doom sync ``` -Either re-open Emacs or hit `SPC h r r` to reload the -changes. +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. ```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 +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 @@ -189,12 +182,10 @@ stores the `htmlize`, `weblorg`, and ## 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): ``` txt .build/ @@ -222,17 +213,17 @@ 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. +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. ```sh touch build.sh && chmod +x build.sh && nano build.sh @@ -240,14 +231,12 @@ 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. +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/* && \ @@ -259,13 +248,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. ```sh > time ./build.sh @@ -273,5 +261,5 @@ My only current complaints are: ./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. +Overall, I have thoroughly enjoyed using weblog and will continue to use it +going forward until I find something better. |