At the end of January I re-did my website: I switched from WordPress to a static web site (i.e. a web site that's just HTML files/content, with no programs running on the server).

For many years prior, I'd been running a WordPress site, but I virtually never wrote anything. I diligently upgraded modules and the WordPress core, but the signal:noise ratio was low. That is, I was spending very little time being creative ("signal") and lots of time maintaining the site ("noise").

At the same time, my web site is really simple. Even my WordPress theme selection was simple. So I wasn't using much of the power of WordPress.

I'd been thinking about switching to a static site but I'd prefer not having to write raw HTML or Javascript. When reading about Org-mode, I saw people were using it to generate web sites. I wanted a way to create a web site from org-mode without having to write a lot of elisp, and I found this article, Using org to Blog with Jekyll. And more or less, that's what I set up! Below I describe what I'm currently doing.

File system setup My file structure is laid out like this: org/jb.com/org: _posts/ about.org index.org ... org/jb.com/jekyll _posts/ (other stuff Jekyll created) _site/ _config.yml Makefile ...

Emacs Emacs initial configuration Before writing any posts, I needed to set up org-mode to be able to publish content. Also a couple of days in I realized I needed a way to link between blog posts that would use Jekyll's " post_url ". In my init.el : ;; This lets you publish a "project" via org-mode export: (setq org-publish-project-alist '( ;; This defines how to publish the org-mode content: ("org-jb" ;; Path to your org files. :base-directory "~/path/to/org/jb.com/org/" :base-extension "org" ;; Path to your Jekyll project. :publishing-directory "~/path/to/org/jb.com/jekyll/" :recursive t :publishing-function org-html-publish-to-html :headline-levels 4 :html-extension "html" :body-only t ;; Only export section between <body> </body> :with-toc nil :auto-preamble nil ) ;; This defines how to publish non-org-mode content e.g. txt files ("org-static-jb" :base-directory "~/path/to/org/jb.com/org/" :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|php\\|mov\\|html\\|txt\\|" :publishing-directory "~/path/to/org/jb.com/jekyll/" :recursive t :publishing-function org-publish-attachment) ;; This says "jb.com" is both of the above: ("jb.com" :components ("org-jb" "org-static-jb")) )) ; creates a new link-type, "jekyll-post". I don't have autocompletion ; working for this yet. (defun org-jekyll-post-link-follow (path) (org-open-file-with-emacs path)) (defun org-jekyll-post-link-export (path desc format) (cond ((eq format 'html) (format "<a href=\"{%% post_url %s %%}\">%s</a>" (file-name-sans-extension path) desc)))) (org-add-link-type "jekyll-post" 'org-jekyll-post-link-follow 'org-jekyll-post-link-export) The above gets me to the point where C-c C-e (Org-mode exporting) has an option P p for publishing the current project. Writing the post I go into org/jb.com/org/_posts/ and create a new post named YYYY-MM-DD-postname.org , e.g. 2019-02-13-org-mode-website.org . When I first started I created a yasnippet (with C-c & C-n ). I insert this snippet with C-c & C-s : #+OPTIONS: num:nil #+BEGIN_EXPORT HTML --- layout: post title: $1 excerpt: $2 --- $0 #+END_EXPORT The snippet lets me type the title ( $1 ), then hit tab to go to the excerpt ( $2 ), and then go to the body ( $0 ). Note well: I had read that you could use BEGIN_HTML for the above instead of BEGIN_EXPORT, but you can't. BEGIN_EXPORT will put content at the absolute beginning of the resulting HTML file, which is what Jekyll needs for reading the content as Jekyll "frontmatter." At this point I use org-mode formatting. The only special thing I've done is add #+TOC: headlines 3 to longer articles if I want a table of contents.

Publishing to Jekyll Configuring Jekyll When I first set up this environment, I installed Jekyll and then ran jekyll new : cd ~/path/to/org/jb.com jekyll new jekyll This creates a bunch of stuff in a directory that I have boringly named jekyll , such as a starter _config.yml file. I then edited this config file, setting properties such as: title

email

url

description

theme

header_pages

twitter_username (theme-specific property) At that point, Jekyll was ready to receive HTML files published from org-mode. Sending the org-mode file to Jekyll Within the org-mode blog post, I save the file and then hit C-c C-e P p . This makes org-mode generate html files from the org files, putting them in the :publishing-directory specified in init.el . Thus org/jb.com/org/_posts/2019-02-13-org-mode-website.org is compiled into org/jb.com/jekyll/_posts/2019-02-13-org-mode-website.html by Emacs. At this point I can go into the Terminal to run a jekyll server if I want: cd ~/path/to/org/jb.com/jekyll jekyll serve This starts a web server, by default http://127.0.0.1:4000, where I can see the site. If all looks good then I'm ready to have Jekyll do its own export to the _site/ directory.

Building the Jekyll content This step is relatively simple: cd ~/path/to/org/jb.com/jekyll/ JEKYLL_ENV=production jekyll build This "compiles" the Jekyll content and puts it into _site/ . The JEKYLL_ENV variable is used by my theme at least to know whether to add Google Analytics code into the site. The content built by jekyll build should be the same as what you see with jekyll serve .

Uploading the final content At this point all I need to do is send the content to my web server, which I can do with rsync: cd ~/path/to/org/jb.com/jekyll/ rsync -avz _site/ user@example.com:path/to/web/root/ Note well: Any time you use rsync without --delete you have to be kind of careful; if you delete a post, it won't be deleted from the server! I probably should change this. Makefile I love make, so of course I built a quick Makefile to build and publish my site: site: JEKYLL_ENV=production jekyll build pushup: site rsync -avz _site/ user@example.com:path/to/web/root/ Voila! It's that easy! :-P