Jekyll to jorge migration post (#33)

* fix list css

* post draft

* undraft

* excerpt

* corrections

* grammar

commands/initfiles/src/assets/css/main.css

@@ -55,6 +55,10 @@ li {
     line-height: 1.6;
 }
 
+.layout-post li p {
+    margin: 0 0 0.5rem 0;
+}
+
 li:not(:last-child) {
     padding-bottom: .75rem;
 }

docs/src/assets/css/main.css

@@ -56,7 +56,7 @@ li {
 }
 
 .layout-post li p {
-    margin: 0.5rem 0;
+    margin: 0 0 0.5rem 0;
 }
 
 li:not(:last-child) {

docs/src/blog/from-jekyll-to-jorge.org

@@ -0,0 +1,76 @@
+---
+title: From Jekyll to jorge
+date: 2024-03-20
+layout: post
+lang: en
+tags: [project]
+excerpt: "As of a couple of weeks ago, olano.dev, previously a Jekyll website, is generated with jorge. This post documents the migration process."
+---
+#+OPTIONS: toc:nil num:nil
+#+LANGUAGE: en
+
+As of a couple of weeks ago, [[https://olano.dev/][olano.dev]], previously a Jekyll website, is generated with [[/][jorge]]. The migration process was slightly more complicated than I expected, but still very doable. Below are the steps I took, documented for posterity. The relevant PR is [[https://github.com/facundoolano/olano.dev/pull/14][here]].
+
+*** General Jekyll-to-jorge changes
+The first few changes would be the same for any Jekyll site converted to jorge.
+
+1. Renamed files and directories:
+   #+begin_src
+mv _layouts layouts
+mv _includes includes
+mv _data data
+mv _config.yml config.yml
+mkdir src
+mv assets src/
+rm Gemfile
+   #+end_src
+3. [[https://github.com/facundoolano/olano.dev/pull/14/commits/092e07b90978d203bd60d7baa2f608cf2328c40b][Removed]] most of the ~config.yml~ contents since they weren't necessary anymore.
+4. Removed instances of the ~strip_index~ template filter since I didn't port it to jorge and it wasn't necessary anyway.
+5. [[Https://github.com/facundoolano/olano.dev/pull/14/commits/31e0933a3230fc5c908f0979b3b6e359bab65c64][Renamed]] configuration references in templates, to use the ~site.config.*~ namespace. For example, ~site.author~ changed to ~site.config.author~.
+6. Added a [[https://github.com/facundoolano/olano.dev/blob/HEAD/src/feed.xml][template file]] for the atom feed, to replace the jekyll-feed plugin.
+7. [[https://github.com/facundoolano/olano.dev/pull/14/commits/3ea5a73f3856a698a0d39c5fb0362882c39b4bfe][Tweaked]] the CSS to stop relying on whitespace for the layout of inline blocks, since that's [[https://github.com/tdewolff/minify/blob/55535a46bce3503da8398a5757f7c9a89a68dc60/README.md#whitespace-removal][removed]] by the minifier.
+
+I also [[https://github.com/facundoolano/olano.dev/pull/14/commits/c0ff7759d119ada8307c4de6bf152c6aeb0ff658][updated]] a little Makefile I have, to run jorge commands instead of Jekyll.
+
+*** olano.dev specifics
+
+One of the peculiarities of my site (compared to other Jekyll projects), was that I generated my blog posts from org-mode files. But since the HTML generated by the default org-export has an unconventional structure, I set up my [[https://github.com/facundoolano/emacs.d/blob/3ca806a36234f2954785a0e95163cf0ee028cc43/modules/facundo-blog.el#L39-L78][Emacs configuration]] to export to Markdown first and let Jekyll do the HTML conversion. So I had to make a couple of extra directory changes to migrate my posts to jorge:
+
+#+begin_src bash
+rm -rf _posts          # remove intermediate .md files
+mv org/_posts src/blog # put .org posts in the jorge site source
+#+end_src
+
+Since I was already changing the structure of my website, I wanted to take the opportunity to make an update I had been postponing. Instead of:
+
+#+begin_src
+https://olano.dev/2023-11-30-code-is-run-more-than-read
+#+end_src
+
+I wanted post URLs to look like:
+#+begin_src
+https://olano.dev/blog/code-is-run-more-than-read
+#+end_src
+
+So I wrote a [[https://github.com/facundoolano/olano.dev/blob/2ef3f3c49488dfe837d0be96fb02ef689299fa69/migrate.py][Python script]] to rename the files in bulk and automate the remaining content updates:
+
+   1. Remove the date from file names.
+   2. Remove the date from internal links in the org files.
+   3. Remove the ~#+BEGIN_EXPORT html~ and ~#+END_EXPORT~ that wrapped the front matter.
+   4. Ensure the front matter is the first line of each post file.
+   5. Ensure the front matter includes a ~lang~ key since I was relying on ~config.yml~ to set ~lang: es~ as a default.
+   6. Rename the footnotes header since I was relying on org-export internals to translate it from the default, while go-org leaves it as-is.
+   7. Patch image links to stop assuming file-relative paths (e.g ~../assets/img/~)
+
+Since these changes required serving posts at a different location, I needed to update my Nginx configuration so old links wouldn't break. On the first version, I [[https://github.com/facundoolano/olano.dev/blob/745d1b465e932765440bc4b0cc294f23dd8e8ee3/server/Nginx/sites-available/olano.dev#L37][used try_files]] so both the Jekyll and jorge directory layouts were supported. After swapping the files, I changed the configuration again to [[https://github.com/facundoolano/olano.dev/pull/14/commits/8472525a3ed81b3f65ee45ccad20287197fb5f80][issue redirects]] to the new post locations.
+
+Something I noticed after switching to jorge is that a couple of big JavaScript files, already minified by the Closure compiler, caused long build times because the minifier tried to process them anyway. I worked around this by updating jorge to allow to [[https://github.com/facundoolano/olano.dev/blob/2ef3f3c49488dfe837d0be96fb02ef689299fa69/config.yml#L8-L10][exclude files]] from the minifier.
+
+*** org-related patches
+
+Some of the changes were required because the HTML produced by go-org wasn't the same as the one from my previous setup:
+
+1. My old org-export to Markdown configuration translated both ~*~ and ~**~ headers to ~<h2>~ in the HTML. When I switched to jorge, each would produce either ~<h1>~ and ~<h2>~ or  ~<h2>~ and ~<h3>~, depending on go-org's [[https://github.com/niklasfasching/go-org/pull/95][TopLevelHLevel setting]]. To preserve the layout of my posts, I needed to tweak the [[https://github.com/facundoolano/olano.dev/blob/2ef3f3c49488dfe837d0be96fb02ef689299fa69/migrate.py#L80-L88][migration script]] to demote ~*~ headers to ~**~ so the output always resulted in ~<h2>~.
+2. I needed to replace ~\ast{}~ to ~\lowast{}~ to preserve how asterisks were rendered in section separators (I wanted ∗ but was getting *).
+3. I [[https://github.com/facundoolano/olano.dev/pull/14/commits/d87ff9813d9c3d56fd3f766009f6ba08b2a480e9][updated]] the CSS to preserve the footnote and centered blocks style.
+4. I [[https://github.com/facundoolano/olano.dev/pull/14/commits/59f91944e4fe1c2f2e579623fca996d57284de12][updated]] the CSS to preserve the verse blocks style.