Miroirs/jorge
1
0
Fork 0
mirror of https://github.com/facundoolano/jorge.git synced 2024-09-28 03:20:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Jekyll to jorge migration post (#33)

Browse source 
* fix list css

* post draft

* undraft

* excerpt

* corrections

* grammar
This commit is contained in:
Facundo Olano 2024-03-20 13:08:59 -03:00 committed by GitHub
parent 3ec74a5a57
commit 281d06934e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 81 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
commands/initfiles/src/assets/css/main.css
View file

@ -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;
}

2
docs/src/assets/css/main.css
View file

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

76
docs/src/blog/from-jekyll-to-jorge.org Normal file
View file

@ -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.