{ :date "2022-01-17" :title "Moving My Blog to Cryogen and Cloudflare Pages" :layout :post :tags ["cryogen" "asciidoc" "cloudflare" "wordpress"] } :toc: == The Wordpress problem I wanted to migrate away from the existing Wordpress-based hosting for https://curiousprogrammer.net[my curiosprogrammer.net blog] for a long time yet I have not found time to do that until now. Today, I'm finally moving towards much simpler approach using https://github.com/cryogen-project/cryogen[Cryogen] as the underlying blog engine. == Cryogen https://cryogenweb.org/[Cryogen] is a simple blog engine written in Clojure. It's used by a number of people in Clojure community, including https://github.com/seancorfield/seancorfield.github.io[Sean Corfield] and https://blog.jakubholy.net/2019/migrating-from-gatsby-to-cryogen/[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: [source,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 listsA: [source,css] ---- /* 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 https://pages.cloudflare.com/[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 footnote:[Developer Experience] is very nice out of the box. Consider https://github.com/curiousprogrammer-net/curiousprogrammer.blog/pull/14[this example of a pull request build] which automatically produces a test version containing the suggested changes: image::../img/cloudflare-pages-pr-build.png[] If you are interested, check their https://developers.cloudflare.com/pages/get-started[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: . https://kevq.uk/how-to-convert-wordpress-to-markdown/[Convert WordPress To Markdown] . https://matthewsetter.com/technical-documentation/asciidoc/convert-markdown-to-asciidoc-with-kramdoc/[Convert Markdown to AsciiDoc The Right Way! Use Kramdoc] + [source,bash] ---- 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 https://blog.jakubholy.net/2019/migrating-from-gatsby-to-cryogen/[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 link:../pages/my-talks[My Talks page]): + [source,asciidoc] ---- link:../posts/2017-11-01-functional-programming-brno-meetup-clojure[Summary] ---- * 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 https://docs.asciidoctor.org/asciidoc/latest/toc/levels/[adjust TOC depth] * Images can be with this syntax: `[img-title, width, height]` * https://docs.asciidoctor.org/asciidoc/latest/macros/xref/[Cross-referencing] sections inside the same document is very easy - just use `<>` * Append `^` to link title to make it open in a new tab (ala `target="_blank"`) - example: + [source,asciidoc] ---- https://codescene.io[Try CodeScene!^] ---- + It will render as https://codescene.io[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,asciidoc] .... [source,clojure] ---- (defn hello[] (println "Hello, AsciiDoc!")) ---- .... + But use this instead: + [source,asciidoc] .... [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 * https://raw.githubusercontent.com/curiousprogrammer-net/curiousprogrammer.blog/blog-redirects/content/asc/posts/2022-01-12-moving-to-cryogen.asc[AsciiDoc source of this blog post] * https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/[Why You Shouldn’t Use “Markdown” for Documentation] * https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/[Compare AsciiDoc to Markdown] * https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference] * https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide] - very good and comprehensive; recommended! * https://blog.mrhaki.com/2017/10/awesome-asciidoctor-using-paragraphs-in.html