Curious (Clojure) Programmer: Moving My Blog to Cryogen and Cloudflare Pages

Cryogen

Cryogen is a simple blog engine written in Clojure. It’s used by a number of people in Clojure community, including Sean Corfield and Jakub Holy.

I think it will well serve my needs and I hope that the friction for publishing posts (and the frustrations caused by Wordpress editor) is going to diminish.

Cryogen themes

There are 3 themes included with Cryogen and I decided to pick nucleus.

However, it includes a rather weird setting for (no extra) spacing between paragraphs so I had to adjust that via CSS:

/* Increase spacing between paragraphs.
Do not use bottom margin because that also adds extra margin above the first elements in lists.
Use top margin instead.*/
.paragraph {
margin: 20px 0 0 0;
}

Moreover, I changed the default margin for p elements to fix nested lists:

/* Using the default bottom margin 20px makes makes nested lists ugly
because there's an extra vertical space.
Therefore we use zero here: */
#right p {
margin: 0 0 0 0;
}

Finally, I also increased font sizes for headings: especially H4 was too small, even smaller than standard paragraph text size.

Cloudflare pages

I was looking for a simple, free/cheap, robust, and still powerful-enough static site hosting.

I considered GitHub Pages but they are rather crude and don’t offer much options. In particular, I wanted to configure redirects for my old curiousprogrammer.net blog posts.

I finally found Cloudflare Pages and didn’t look further I already had a Cloudflare account because I’ve been using Cloudflare for a few of my domains so it was really quick to set it up and have a dev version of the blog up running.

DevEx ^[1] is very nice out of the box. Consider this example of a pull request build which automatically produces a test version containing the suggested changes:

If you are interested, check their Get Started docs page.

The old blog/content

I moved the old posts (including most of the tags!) and pages from my old wordpress blog to the new structure. The steps were roughly:

Convert WordPress To Markdown

Convert Markdown to AsciiDoc The Right Way! Use Kramdoc

find . -name "*.md" -type f -exec sh -c 'kramdoc --format=GFM --wrap=ventilate --output={}.adoc {}' \;

cp -r YOUR_DIR content/old-posts-converted
# rename the files and move them to the proper directory
cd content/old-posts-converted
find . -name "*.adoc" -exec sh -c 'postname=$(realpath --relative-to=. {}| sed "s@/index.md@@"); cp {} "$postname"' \;

Go through the files manually - fix formatting, tags, etc.
Configure redirects with Cloudflare Pages (_redirects file) https://developers.cloudflare.com/pages/platform/redirects
Add pages manually (not covered by the conversation process above)

AsciiDoc

I’ve found a couple of AsciiDoc-related links in Jakub Holy’s article and decided to give it a try. The promise is that, unlike Markdown, it’s standardized, extensible and has richer formatting options.

Asciidoc - quick notes and tips

root-relative links ala /posts/my-post.adoc don’t work - you need to use .. such as this (used on the My Talks page):
```
link:/posts/2017-11-01-functional-programming-brno-meetup-clojure[Summary]
```
- UPDATE: I was wrong - root-relative links DO work, I just had an incorrect configuration in my config.edn file
  :blog-prefix ""
Always use * for list items, DO NOT USE -.
- - works only for top-level lists, not nested lists.
Prefer explicit :toc: for generating Table of Contents
- Cryogen’s specific :toc attribute in the metadata doesn’t work with plain asciidoc
- :toc: includes nice header "Table of Contents" which is missing if you use the metadata.
- You can use :toclevels: 4 to adjust TOC depth
Images can be resized with this syntax: [img-title, width, height]
Cross-referencing sections inside the same document is very easy - just use [My section title]
Append ^ to link title to make it open in a new tab (ala target="_blank") - example:
```
https://codescene.io[Try CodeScene!^]
```
It will render as Try CodeScene!
Use + to to attach paragraphs and code listings to a list item
- See https://blog.mrhaki.com/2017/10/awesome-asciidoctor-using-paragraphs-in.html as a good example
- See also the next bullet point

use [source] and ---- together to get proper source code listings:

That is don’t just use this:

[source,clojure]
(defn hello[]
(println "Hello, AsciiDoc!"))

But use this instead:

[source,clojure]
----
(defn hello[]
(println "Hello, AsciiDoc!"))
----

++++ is for passing unprocessed content to the raw output (such as HTML), NOT for rendering the text as is - use .... (four dots) instead
You can use \ for "escaping" - such as \*hello\* (to render as *hello*) for including the stars and not rendering 'hello' using a bold font
- Note that you should escape only the first opening star, not the closing one!

Some Asciidoc resources

AsciiDoc source of this blog post
Why You Shouldn’t Use “Markdown” for Documentation
Compare AsciiDoc to Markdown
AsciiDoc Syntax Quick Reference
AsciiDoc Writer’s Guide - very good and comprehensive; recommended!
https://blog.mrhaki.com/2017/10/awesome-asciidoctor-using-paragraphs-in.html

Moving My Blog to Cryogen and Cloudflare Pages

The Wordpress problem