# Moving from Jekyll to OrgMode, an experience report Adolfo Villafiorita [[!template id=vid src="https://mirror.csclub.uwaterloo.ca/emacsconf/2020/emacsconf-2020--15-moving-from-jekyll-to-orgmode-an-experience-report--adolfo-villafiorita.webm" subtitles="/2020/subtitles/emacsconf-2020--15-moving-from-jekyll-to-orgmode-an-experience-report--adolfo-villafiorita.vtt"]] [Download compressed .webm video (13.8M)](https://mirror.csclub.uwaterloo.ca/emacsconf/2020/smaller/emacsconf-2020--15-moving-from-jekyll-to-orgmode-an-experience-report--adolfo-villafiorita--vp9-q56-video-original-audio.webm) [View transcript](#transcript) I have been a long time user of static site generators, such as Jekyll. I recently discovered Org Mode's publishing features and started appreciating flexibility and capabilities, especially when literate programming comes into play to generate "dynamic" content. In this talk/tutorial I will present the challenges I faced and how I finally moved my homepage and the University of Trento's Computational Logic website to Org Mode. - Actual start and end time (EST): Start: 2020-11-28T14.36.18; Q&A: 2020-11-28T14.51.48; End: 2020-11-28T14.53.03 # Questions ## Opinion on Firn ()? ## Do you discuss this in a blog as well? Where could I find more about it? Talk and content will be published later after the conference. Will be available on the talk page. ## Could you please paste your URLs in the notes below? (link to your site etc). The source repository of the first website (my homepage) lives here: and the output is: . The source repository of the second website (Computational Logic) lives here: and the output is: . The talk, code and links are now availble here: . has the source code for the website. # Notes - Main reason: Org has better support for literate programming. - Org mode files support in Jekyll - . - Mentioned: (org-html). - Other static webpage generators: . # Transcript 00:00:00.080 --> 00:00:03.120 Adolfo: Okay, excellent. Hello, everyone and nice meeting you. Let me thank the the organizer for all the organization and all the work they are doing to support us. My name is Adolfo Villafiorita. I'm teaching at the University of Trento. I will shortly be working at shared.tech, which is a non-profit organization developing applications to recover surplus food. 00:00:35.680 --> 00:00:38.600 The reason of the talk today and the reason I'm here today is to talk about my experience in moving from Jekyll static website generator to Org Mode. The reason I moved to Org Mode is to have better support for literate programming on the websites at the University of Trento, where we make available the content for the the students. 00:01:04.720 --> 00:01:08.900 First of all, what is a static website generator? It is basically a tool which allows you to generate HTML files out of text files containing basically two types of information: metadata and content. 00:01:20.700 --> 00:01:23.119 Metadata is a set of key pairs describing the 00:01:26.159 --> 00:01:28.560 content of the file, such as the title, 00:01:28.560 --> 00:01:31.733 author, tags, and so on and so forth. 00:01:31.733 --> 00:01:34.560 The content is what you actually want to 00:01:34.560 --> 00:01:37.040 get published on the Internet in 00:01:37.040 --> 00:01:38.880 the HTML file. 00:01:38.880 --> 00:01:41.439 Usually the content is written in 00:01:41.439 --> 00:01:45.800 some kind of markup language, 00:01:45.800 --> 00:01:49.759 such as Markdown or possibly 00:01:49.759 --> 00:01:53.200 Org Mode. Jekyll is a very 00:01:53.200 --> 00:01:57.900 popular static website generator. 00:01:57.900 --> 00:01:59.840 It is written in Ruby. 00:01:59.840 --> 00:02:03.280 What it does: it systematically 00:02:03.280 --> 00:02:06.840 transforms all the input files 00:02:06.840 --> 00:02:09.440 by making the content into 00:02:09.440 --> 00:02:11.599 HTML and systematically applying a 00:02:11.599 --> 00:02:14.000 template in order to generate the 00:02:14.000 --> 00:02:17.120 HTML files, which you can then deploy 00:02:17.120 --> 00:02:19.840 on your server of choice to make them 00:02:19.840 --> 00:02:22.160 available on the Internet. 00:02:22.160 --> 00:02:26.160 One of the features most-- 00:02:26.160 --> 00:02:27.500 well, I would say all 00:02:27.500 --> 00:02:30.239 static website generators have 00:02:30.239 --> 00:02:32.560 is that of being able to 00:02:32.560 --> 00:02:34.879 collect the metadata information 00:02:34.879 --> 00:02:38.400 of the files being part of 00:02:38.400 --> 00:02:39.440 your project. 00:02:39.440 --> 00:02:45.280 The reason they do that is because 00:02:45.280 --> 00:02:47.840 you sometimes want to generate pages 00:02:47.840 --> 00:02:49.280 based on the content 00:02:49.280 --> 00:02:53.200 of your projects, 00:02:53.200 --> 00:02:56.239 such as, for instance, the list of 00:02:56.239 --> 00:02:59.040 posts you have recently published, or 00:02:59.040 --> 00:03:00.400 maybe the list of tags 00:03:00.400 --> 00:03:03.840 you have defined for your post, 00:03:03.840 --> 00:03:07.280 and so on and so forth. 00:03:07.280 --> 00:03:09.760 Jekyll gives the possibility of 00:03:09.760 --> 00:03:12.400 generating this kind of dynamic 00:03:12.400 --> 00:03:14.400 content by using Liquid, 00:03:14.400 --> 00:03:18.800 which is a templating language which 00:03:18.800 --> 00:03:21.840 looks like this. 00:03:21.840 --> 00:03:24.879 So basically, you have all the 00:03:24.879 --> 00:03:26.879 constructs you can 00:03:26.879 --> 00:03:28.800 expect in a programming language. 00:03:28.800 --> 00:03:29.920 This, for instance, 00:03:29.920 --> 00:03:33.360 is a for cycle which 00:03:33.360 --> 00:03:37.440 iterates over all the posts or the 00:03:37.440 --> 00:03:39.599 files in a specific directory of the 00:03:39.599 --> 00:03:41.040 Jekyll project. 00:03:41.040 --> 00:03:45.040 For each post, it takes the title 00:03:45.040 --> 00:03:48.400 and the URL and generates a link. 00:03:48.400 --> 00:03:52.867 So Jekyll is nice and sweet, 00:03:52.867 --> 00:03:55.200 but over the years 00:03:55.200 --> 00:03:57.760 I started using more and more 00:03:57.760 --> 00:03:59.519 systematically 00:03:59.519 --> 00:04:02.000 Org Mode to write all my files. 00:04:02.000 --> 00:04:04.833 I moved from Markdown to Org Mode 00:04:04.833 --> 00:04:07.200 I am a long time Emacs user. 00:04:07.200 --> 00:04:09.167 I've been using Emacs for 30 years now, 00:04:09.167 --> 00:04:12.799 so Org Mode is a more recent discovery, 00:04:12.799 --> 00:04:17.033 but it is a very nice discovery I made. 00:04:17.033 --> 00:04:19.680 The reason I like Org Mode 00:04:19.680 --> 00:04:22.320 is because, for instance, you can write 00:04:22.320 --> 00:04:24.933 formulas using MathJax 00:04:24.933 --> 00:04:26.639 and you can generate diagrams 00:04:26.639 --> 00:04:30.320 or plots with Gnuplot. 00:04:30.320 --> 00:04:32.240 Also important is the fact that you have 00:04:32.240 --> 00:04:34.080 the possibility of publishing 00:04:34.080 --> 00:04:39.520 your documents to multiple backends such as PDF, 00:04:39.520 --> 00:04:43.600 or maybe a Reveal presentation, 00:04:43.600 --> 00:04:47.199 or HTML. This is all made possible 00:04:47.199 --> 00:04:50.479 by Babel, which is 00:04:50.479 --> 00:04:52.560 exactly what we just saw in the 00:04:52.560 --> 00:04:54.639 previous talk: 00:04:54.639 --> 00:04:57.440 Namely, the possibility of executing a 00:04:57.440 --> 00:04:59.520 snippet of code 00:04:59.520 --> 00:05:02.560 embedded in in your pages. 00:05:02.560 --> 00:05:06.400 Our model can also be used 00:05:06.400 --> 00:05:09.600 within Jekyll. In fact, 00:05:09.600 --> 00:05:13.667 there is a a nice gem, a nice library, 00:05:13.667 --> 00:05:17.233 called jekyll-org which allows you 00:05:17.233 --> 00:05:19.680 to use Org Mode files directly 00:05:19.680 --> 00:05:22.880 into jekyll. But when you start using 00:05:22.880 --> 00:05:26.560 Org Mode... When I started using 00:05:26.560 --> 00:05:30.560 Org Mode, I realized I could move 00:05:30.560 --> 00:05:34.240 all my workflow, all my publishing 00:05:34.240 --> 00:05:36.840 workflow to Emacs. 00:05:36.840 --> 00:05:41.100 In fact, Org Mode is also a 00:05:41.100 --> 00:05:42.880 static website generator because 00:05:42.880 --> 00:05:46.240 it has got the possibility of publishing 00:05:46.240 --> 00:05:50.880 projects made of Org Mode files. 00:05:50.880 --> 00:05:53.840 One of the nice things about 00:05:53.840 --> 00:05:56.479 the publishing features of Org Mode 00:05:56.479 --> 00:05:58.880 is that it allows you to define in the 00:05:58.880 --> 00:06:01.300 org-publish-project-alist, 00:06:01.300 --> 00:06:03.199 all the the components 00:06:03.199 --> 00:06:05.367 which are part of your project. 00:06:05.367 --> 00:06:07.520 In a sense, it is 00:06:07.520 --> 00:06:10.479 also more flexible than Jekyll, 00:06:10.479 --> 00:06:12.880 because it also allows you, for instance, 00:06:12.880 --> 00:06:15.120 to publish a single file rather 00:06:15.120 --> 00:06:17.440 than having to recompile everything 00:06:17.440 --> 00:06:20.080 every time you want to publish your 00:06:20.080 --> 00:06:22.333 your project to your website. 00:06:22.333 --> 00:06:25.333 However, there are some short comments 00:06:25.333 --> 00:06:29.520 I would say, or some areas of improvement. 00:06:30.400 --> 00:06:33.600 The first is that support for templating 00:06:33.600 --> 00:06:36.639 is not so obvious as it is 00:06:36.639 --> 00:06:39.280 in Jekyll, even though there are some 00:06:40.560 --> 00:06:44.560 nice extensions such as org-thtml, 00:06:44.560 --> 00:06:48.400 for instance, which allows you to use templates. 00:06:48.400 --> 00:06:51.840 More important to me was the fact that 00:06:51.840 --> 00:06:54.080 apparently, there is little support for 00:06:54.080 --> 00:06:56.133 the creation of dynamic content 00:06:56.133 --> 00:06:57.900 So I was very curious 00:06:57.900 --> 00:06:59.360 and very keen to use 00:06:59.360 --> 00:07:02.800 Org Mode for publishing my blog 00:07:02.800 --> 00:07:05.440 and the courses at the university, 00:07:05.440 --> 00:07:08.720 but then I had to find a way 00:07:08.720 --> 00:07:11.440 to being able to publish these 00:07:11.440 --> 00:07:13.599 dynamic pages, finding some kind of 00:07:13.599 --> 00:07:16.000 replacement, so to speak, 00:07:16.720 --> 00:07:17.900 for the liquid engine. 00:07:17.900 --> 00:07:24.160 The solution was there at hand, actually, because 00:07:24.160 --> 00:07:27.280 basically, I realized I could use Babel 00:07:27.280 --> 00:07:30.800 for exactly this purpose. Rather than 00:07:30.800 --> 00:07:32.720 using Babel for generating 00:07:32.720 --> 00:07:35.759 plots or my other computations 00:07:35.759 --> 00:07:37.919 or whatever I was using them for, 00:07:37.919 --> 00:07:41.039 I realized I could use Babel to 00:07:41.039 --> 00:07:45.120 generate HTML which could be 00:07:45.120 --> 00:07:49.967 then published in the project 00:07:49.967 --> 00:07:53.680 All I needed to do then 00:07:53.680 --> 00:07:56.100 was defining some kind of functions, 00:07:56.100 --> 00:07:58.319 some kind of code in order to read 00:07:58.319 --> 00:08:01.840 the metadata of all 00:08:01.840 --> 00:08:04.767 the Org Mode files of my web project, 00:08:04.767 --> 00:08:09.680 so that I could then publish-- 00:08:09.680 --> 00:08:13.280 generate the dynamic content. 00:08:13.280 --> 00:08:18.080 This is a snippet taken from 00:08:18.080 --> 00:08:21.759 one of my HTML projects, 00:08:21.759 --> 00:08:24.800 which basically shows the way in which 00:08:24.800 --> 00:08:27.599 I generate the list of posts on 00:08:27.599 --> 00:08:32.560 my page. It is exactly how the Liquid that we saw 00:08:32.560 --> 00:08:35.680 a couple of slides earlier that looks like 00:08:35.680 --> 00:08:39.200 in Org Mode. 00:08:39.200 --> 00:08:42.320 Basically, what I'm doing... I'm using... 00:08:42.320 --> 00:08:46.720 I wrote a Ruby script which 00:08:46.720 --> 00:08:49.680 reads all the metadata. So this 00:08:49.680 --> 00:08:51.040 highlighted code 00:08:51.040 --> 00:08:53.100 basically loads the script 00:08:53.100 --> 00:08:55.300 which is stored externally. 00:08:55.300 --> 00:08:56.800 Then it collects all the 00:08:56.800 --> 00:08:58.320 metadata from the 00:08:58.320 --> 00:09:00.880 Org Mode files in the 00:09:00.880 --> 00:09:02.240 current directory. 00:09:02.240 --> 00:09:04.800 And then the following... The code 00:09:04.800 --> 00:09:06.480 you can see here 00:09:06.480 --> 00:09:09.839 basically iterates over all the 00:09:09.839 --> 00:09:12.959 posts read at the previous step. 00:09:12.959 --> 00:09:16.399 It generates 00:09:16.399 --> 00:09:19.519 a list with the title 00:09:19.519 --> 00:09:22.959 and the URLS, basically 00:09:22.959 --> 00:09:27.440 replicating what Jekyll does. 00:09:27.440 --> 00:09:30.240 There are some other things 00:09:30.240 --> 00:09:32.399 I have to deal with in order to 00:09:33.200 --> 00:09:36.480 accommodate my workflow. But that was 00:09:36.480 --> 00:09:39.200 relatively easy in the sense that one of 00:09:39.200 --> 00:09:43.279 the problems, one of the issues I had to 00:09:43.279 --> 00:09:45.360 solve was that of having 00:09:45.360 --> 00:09:48.480 a common navigation on all my 00:09:48.480 --> 00:09:51.040 pages. That was easily solved 00:09:51.040 --> 00:09:53.867 using the #+INCLUDE feature. 00:09:53.867 --> 00:09:54.959 So I basically 00:09:54.959 --> 00:09:56.000 made available 00:09:56.000 --> 00:09:57.839 an #+INCLUDE with all the navigation 00:09:57.839 --> 00:10:00.560 which is embedded in all the pages of 00:10:00.560 --> 00:10:01.839 my websites 00:10:01.839 --> 00:10:03.733 through the #+INCLUDE. 00:10:03.733 --> 00:10:06.160 Another nice feature which 00:10:06.160 --> 00:10:08.560 Jekyll has is the possibility of 00:10:08.560 --> 00:10:12.800 previewing a website before deploying it. 00:10:13.200 --> 00:10:16.079 Emacs also has got a node which allows 00:10:16.079 --> 00:10:21.200 you to launch a web server. In fact, 00:10:21.200 --> 00:10:24.320 I wrote a quick hack 00:10:24.320 --> 00:10:26.959 which allows you to 00:10:26.959 --> 00:10:31.519 invoke a node on an Org Mode 00:10:31.519 --> 00:10:34.720 project, start a local preview, 00:10:34.720 --> 00:10:37.920 and then use rsync 00:10:37.920 --> 00:10:44.839 in order to deploy the the website. 00:10:46.240 --> 00:10:48.720 Five minutes left. More than 00:10:48.720 --> 00:10:51.200 enough. Okay. 00:10:51.200 --> 00:10:52.967 Thanks. Thank you, thank you very much. 00:10:52.967 --> 00:10:56.480 I'm nearly done. So then I can take some questions. 00:10:56.480 --> 00:11:00.560 Just to give you maybe 00:11:00.560 --> 00:11:03.680 a slightly more in-depth 00:11:03.680 --> 00:11:06.480 view of what the pages look like, 00:11:06.480 --> 00:11:07.200 so these are 00:11:07.200 --> 00:11:11.120 one of the pages, or the source files 00:11:11.120 --> 00:11:14.720 of one of the websites. It is 00:11:14.720 --> 00:11:18.480 in literate programming. Basically, 00:11:18.480 --> 00:11:20.399 you see there is some metadata here. 00:11:20.399 --> 00:11:22.640 I mean this is a regular Org Mode file. 00:11:22.640 --> 00:11:26.640 This part here 00:11:26.640 --> 00:11:29.920 basically defines some common options 00:11:29.920 --> 00:11:31.519 for publication. 00:11:31.519 --> 00:11:35.920 These two includes here 00:11:35.920 --> 00:11:41.120 put some extra HTML in the head part and 00:11:41.120 --> 00:11:44.480 the navigation. Here, as you can see, 00:11:44.480 --> 00:11:48.079 is the code generating the 00:11:48.079 --> 00:11:50.160 the list in chronological order. It is 00:11:50.160 --> 00:11:52.240 slightly more complex than the example I 00:11:52.240 --> 00:11:53.839 made in the slide 00:11:53.839 --> 00:11:56.240 because there is some more 00:11:56.240 --> 00:11:59.760 elaboration to do, including putting some 00:11:59.760 --> 00:12:01.839 Javascript to identify 00:12:01.839 --> 00:12:05.120 according to the tags. 00:12:05.120 --> 00:12:08.160 To go back to the presentation... 00:12:11.200 --> 00:12:13.067 I managed this migration 00:12:13.067 --> 00:12:14.560 a few months ago, 00:12:14.560 --> 00:12:17.680 and then all my workflow is within 00:12:17.680 --> 00:12:20.399 Org Mode and within Emacs. 00:12:20.399 --> 00:12:23.079 I'm very happy with it because it's 00:12:23.079 --> 00:12:26.800 simplified quite a bit 00:12:26.800 --> 00:12:28.480 my publication process. 00:12:28.480 --> 00:12:31.839 One of the advantages... Another 00:12:31.839 --> 00:12:34.240 advantage... So the first advantage is that 00:12:34.240 --> 00:12:36.959 everything is in Org Mode and Emacs. 00:12:36.959 --> 00:12:38.160 Second advantage 00:12:38.160 --> 00:12:41.680 is that everything is based on the 00:12:41.680 --> 00:12:44.880 standard machinery provided by Org Mode. 00:12:44.880 --> 00:12:47.760 So in a sense, it is 00:12:47.760 --> 00:12:50.079 more robust with respect to 00:12:50.079 --> 00:12:53.040 dependencies, possible errors, and so 00:12:53.040 --> 00:12:54.320 on and so forth. 00:12:54.320 --> 00:12:56.639 The fact that Org Mode 00:12:56.639 --> 00:12:58.240 allows you to publish 00:12:58.240 --> 00:13:00.880 a single file in a project is also 00:13:00.880 --> 00:13:03.839 very interesting because 00:13:03.839 --> 00:13:07.839 it allows to be more robust to 00:13:07.839 --> 00:13:11.040 problems you might introduce when 00:13:11.040 --> 00:13:14.959 you're changing--when I'm changing the setup. 00:13:14.959 --> 00:13:16.880 Another interesting thing which I 00:13:16.880 --> 00:13:21.519 realized that I could have is that 00:13:21.519 --> 00:13:23.600 in a sense, the specification of the 00:13:23.600 --> 00:13:28.480 website can be embedded in the website itself. 00:13:28.480 --> 00:13:30.800 In a sense this is some kind of 00:13:30.800 --> 00:13:31.839 self-documenting... 00:13:31.839 --> 00:13:35.120 It's a way of self-documenting 00:13:35.120 --> 00:13:36.600 what I'm actually doing. 00:13:36.600 --> 00:13:44.133 For instance, here on my website, 00:13:44.133 --> 00:13:46.399 you can see the 00:13:46.399 --> 00:13:48.240 specification of the 00:13:48.240 --> 00:13:51.519 project which is loaded 00:13:51.519 --> 00:13:53.933 from my initialization file, 00:13:53.933 --> 00:13:56.320 but then it is also published 00:13:56.320 --> 00:13:59.440 together with my home page. It lives 00:13:59.440 --> 00:14:01.360 with the repository where 00:14:01.360 --> 00:14:05.360 I keep all the sources of my website, 00:14:05.360 --> 00:14:08.079 which is kind of nice because it 00:14:08.079 --> 00:14:09.839 basically isolates 00:14:09.839 --> 00:14:14.079 everything in a single place. 00:14:14.079 --> 00:14:16.880 So there are some examples. I'm 00:14:16.880 --> 00:14:19.433 showing them more because of the 00:14:19.433 --> 00:14:21.760 source code which 00:14:21.760 --> 00:14:25.519 you can grab from the git repositories 00:14:25.519 --> 00:14:26.933 if you are interested. 00:14:26.933 --> 00:14:28.399 Of course I'm also available 00:14:28.399 --> 00:14:31.600 to provide some support and help 00:14:31.600 --> 00:14:32.959 if you are interested 00:14:32.959 --> 00:14:34.480 in this kind of stuff. 00:14:34.480 --> 00:14:37.760 The the next step for me will be that of 00:14:37.760 --> 00:14:41.600 trying, making this kind of machinery available 00:14:41.600 --> 00:14:45.199 for more general use at the moment. 00:14:45.199 --> 00:14:47.120 If you are interested in trying out my 00:14:47.120 --> 00:14:48.800 suggestion, grabbing the 00:14:48.800 --> 00:14:51.933 sources for one of the websites 00:14:51.933 --> 00:14:54.700 to seehow they look like, 00:14:54.700 --> 00:14:56.720 and maybe try and 00:14:56.720 --> 00:15:00.160 customize it for your purposes... 00:15:00.160 --> 00:15:03.839 This is basically the content of my talk. 00:15:03.839 --> 00:15:06.959 I'm open to questions and thank you 00:15:06.959 --> 00:15:10.880 for your attention. 00:15:10.880 --> 00:15:12.880 (Amin: Thank you very much, Adolfo, for your 00:15:12.880 --> 00:15:14.480 awesome presentation. 00:15:14.480 --> 00:15:17.360 I think we have time for maybe like 00:15:17.360 --> 00:15:19.360 one or two questions, 00:15:19.360 --> 00:15:21.279 and then the rest maybe you could 00:15:21.279 --> 00:15:26.639 take up after the stream.) 00:15:26.639 --> 00:15:28.033 Adolfo: What should we do? 00:15:28.033 --> 00:15:30.000 (Amin: Would you like me 00:15:30.000 --> 00:15:31.839 to read you the questions?) 00:15:31.839 --> 00:15:35.199 Adolfo: Yeah, probably better because 00:15:35.199 --> 00:15:36.700 I'm kind of lost there. 00:15:36.700 --> 00:15:40.399 (Amin: Okay, no problem. 00:15:40.399 --> 00:15:42.480 So someone asks, "Do you have any 00:15:42.480 --> 00:15:45.440 opinion on Firn?") 00:15:45.440 --> 00:15:48.639 Adolfo: Firn. I don't know Firn, 00:15:48.639 --> 00:15:51.839 so I'll give it a try 00:15:51.839 --> 00:15:55.040 and check it out. 00:15:55.040 --> 00:15:57.839 (Amin: Thanks. People are also asking, 00:15:57.839 --> 00:15:59.680 do you discuss this, for example, in a blog 00:15:59.680 --> 00:16:01.279 or anywhere else they could find more 00:16:01.279 --> 00:16:02.800 about it?) 00:16:02.800 --> 00:16:05.600 Adolfo: Oh yes. I'm going to publish the 00:16:05.600 --> 00:16:08.560 the talk and the content 00:16:08.560 --> 00:16:11.120 on my website, and then I'll link it from 00:16:11.120 --> 00:16:13.067 the EmacsConf conference 00:16:13.067 --> 00:16:14.720 so that it will be easier for 00:16:14.720 --> 00:16:16.533 people to to reach it 00:16:16.533 --> 00:16:19.040 I will shortly make it 00:16:19.040 --> 00:16:22.880 available right after the conference. 00:16:22.880 --> 00:16:26.160 (Amin: Wonderful. I think that's all for the questions. 00:16:26.160 --> 00:16:27.667 Thank you very much.) 00:16:27.667 --> 00:16:29.600 Adolfo: Thank you very much. Thank you. 00:16:29.600 --> 00:16:34.800 (Amin: Cheers.) Adolfo: Bye, cheers. (Amin: Bye.)