April 9, 2020
By: gotwf

Taking Ten for Cryogen

Taking ten for Cryogen here cuz that’s about all it takes. Well. Okay. Maybe 20. Given the dizzying array of static site generators that have sprung up the past few years, inquiring minds may wonder…​

Why Cryogen?

Good question. Indeed. With about as many answers as those askin'. The bottom line is that it pretty much boils down to personal preferences. Let me break some of mine down. Language is as good a place to begin as any.

Why Clojure?

I used to think Clojure was the next big whizz bang thang and dreamed about learning it. One of these days. When I had some spare time. Then came Go. And the rest is history. My experience with Go is limited but it does not trip my trigger. I am not inspired to learn it. I do still like functional Lispy things. Cryogen is based on Clojure. Clojure is Lispy. Ergo Cryogen is Cool™.

But Java Sucks

Maybe. Maybe not. Have you evaluated Java lately?

If platform agnosticism is high on your list then Java certainly offers a win. Although worthy of bonus points if well implemented, cross platform portability is not a big concern in my little hole in the wall blog my world. But there are other worlds. Like multi author sites where this does factor prominently. Hence I also hold such capabilities in some regard.

There will be those who whinge on about this that or the other issue with Java’s virtual machine, license, overhead, whatever. Java is evil. Yes, there will be significant start up overhead. But not really. Use Java 8, nothing greater, nothing less. You will see that much of that carping is ancient press and herd think. Particularly among a certain sector. Holy moly!! A CLI Junky just bold enough to say it. Roh, roh!

So moving on, once again it all boils down to your use case. Depending on perspective, objectives and priorities, this investment may, or may not, be well spent. Now that I have covered all my bases with circular logic…​ Bottom line is that jvm startup overhead is a non issue for me as it simply does not bother me to have to wait a few seconds for my environment to be set up.

Or not. Whatever trips your trigger. It’s not worth a religious war.

Work Flow

So I guess it must be about the environment, eh? Yep. I gots me a REPL fer' me bee loggin'. And I likes it. I find it useful. Functional. No hassle. You get the drill. And so does Cryogen.

My Cryogen Machine is smart enough to monitor file modification times for changes and parse as appropriate in a timely manner. We are not done yet. Nope. This machine thang can also optionally fire up a local webserver running on unpriviliged high port 3000 so you can visualize your handiwork real time. With options to also launch and display that modified page in your web browser. Or not, if you just want to run a quick parse job [1] before uploading a hot fix to remedy a typo. Publication involves transfer to your public facing webserver via whatever mechs suit your fancy. [2]

Oh, yeah. Cryogen requires minimal configuration and looks pretty decent out of the box. The basic knobs are damned simple. So you are free to get to work on creating content rather than wading through configuration file minutiae. Speaking of which…​

Authoring

Cryogen supports both Asciidoc and Markdown[3] sans the need for any 'extras' or 'plugins'. Hence, unlike many other SSG offerings, Asciidoc is supported as a first class citizen. Free and open software is in no small part about freedom. Cryogen makes it easy to exercise that freedom.

If you have an investment in Markdown then Markdown certainly makes sense. I did not. As I had no dog in the fight, I put each through its paces from the perspective of a naive user. [4] I prefer Asciidoc. End user perceptions are five nines of reality. I get a warm fuzzy feeling about documents marked up with Asciidoc. Groove on it.™

Theming & Templates

Cryogen ships with a few basic themes that get the job done. That said, this is one potential downside of Cryogen. As of this writing four themes come bundled with Cryogen. If eye candy and JAMStack wizardry are high on your list of priorities you likely want to either be prepared to roll up your sleeves or look elsewhere. In which case you may want to investigate Gatsby, Hugo, or NEXT.js. I am not an UX front end designer. Nor do I have any desire to become one. I appreciate aesthetics but function even more and prioritize lean, mean, and nimble web sites. There is only so much time for indulgin' in bee loggin' and I would rather spend it writing content than pursuing design awards for presentation. Thus, the screen adaptive out of the box themes bundled with Cryogen suffice nicely for me. A bit of CSS tuning and I am a happy camper.

Cryogen favors Selmer templates to facilitate knob tweakin' by intermediate and advanced users. Selmer is a powerful templating engine and has all the features you’d expect from a modern template system. If you’ve ever used Jinga2 or Mako, you will probably also feel at home with Selmer in short order.

Should templating prove inadequate for your adventures, power users have Clojure and all those mature Java libaries at their disposal. Code on, Garth!

Installation

Clojure

Clojure needs a Java VM. You probably already have one installed. If not, your distro’s package manager probably packages Clojure. So just let the Clojure install pull in its preferred version in as a dependency.

Java Version

As mentioned above, I recommend using Java 8. OpenJDK is the path to take. If you’re platform already has some other version installed, don’t sweat it. At least not until you try it. If you hit issues then jump to OpenJDK 8 and check for low hanging fruit.

Leiningen

Your distro may have a recent version of Leiningen packaged. Maybe not. Use your package manager if so. Otherwise use the lein install script. Leiningen presently recommends OpenJDK version 8. [5]

Shamelessly lifted from the Leinigen Home Page:

Leiningen Installation
  1. Download the lein script (or on Windows lein.bat)

  2. Place it on your $PATH where your shell can find it (eg. ~/bin)

  3. Set it to be executable (chmod a+x ~/bin/lein)

  4. Run it (lein) and it will download the self-install package

That was easy.

First Project

1. Create a Fresh Cryogen Project

Pick a directory where you want your project to live. Any directory. For whatever reasons trip yer' trigger. It does not really matter as long as it makes sense to you. I suggest something descriptive.

~ $ mkdir ~/Projects/
~ $ cd ~/Projects/
~ $ lein new cryogen my-new-blog
~ $ cd my-new-blog

2. Configure Your Cryogen Project

Cryogen defaults to markdown. Edit your project.clj to use asciidoc if you prefer.

~ $ sed 's/cryogen-markdown "0.1.4"/cryogen-asciidoc "0.1.5"/' project.clj  >> project.clj.tmp
~ $ mv project.clj.tmp project.clj

Some additional jvm-opts tuning is needed for FreeBSD users. [6]

~ $ echo ':jvm-opts ["-Dsun.nio.fs.watchservice=polling"]' >> project.clj

3. Fire Up Cryogen

Cryogen comes with some minimal default content for testing. It also sports some minimal documentation. So let’s fire up your engine.

~ $ lein ring server

In a moment you should be looking at a browser window pointing to localhost:3000 sporting some minimal Cryogen out of the box content for testing as well as some minimal documentation. Fine tune your blog by editing its configuration file, config.edn.

~ $ cd content
~ $ cat config.edn
{:site-title                   "My Awesome Blog"
 :author                       "Bob Bobbert"
 :description                  "This blog is awesome"
 :site-url                     "http://blogawesome.com/"
 :post-root                    "posts"
 :page-root                    "pages"
 :post-root-uri                "posts-output"
 :page-root-uri                "pages-output"
 :tag-root-uri                 "tags-output"
 :author-root-uri              "authors-output"
 :public-dest                  "public"
 :blog-prefix                  "/blog"
 :rss-name                     "feed.xml"
 :rss-filters                  ["cryogen"]
 :recent-posts                 3
 :post-date-format             "yyyy-MM-dd"
 :archive-group-format         "yyyy MMMM"
 :sass-src                     []
 :sass-path                    "sass"
 :theme                        "blue"
 :resources                    ["img"]
 :keep-files                   [".git"]
 :disqus?                      false
 :disqus-shortname             ""
 :ignored-files                [#"\.#.*" #".*\.swp$"]
 :previews?                    false
 :posts-per-page               5
 :blocks-per-preview           2
 :clean-urls                   :trailing-slash
 :collapse-subdirs?            false
 :hide-future-posts?           true
 :klipse                       {}
 :description-include-elements #{:p :h1 :h2 :h3 :h4 :h5 :h6}
 :debug?                       false}

See Cryogen configuration documentation for further elaboration regarding these knobs.

4. Develop Content

Now that you’ve familiarized yourself with Cryogen a wee bit you are ready to create some killer content. Either nuke the factory verbiage or simply point your config.edn to alternate directories to house your prose elsewhere. Be advised, however, that Cryogen only monitors file modifications under your project subdirectories. If you branch out of that tree your REPL may not be as useful as it once was.

Cyrogen broadly splits content into either "pages" or "posts" hierarchies. Pages reside in, you guessed, it, your pages subdirectory, while posts live in the posts subdirectory. Posts are displayed reverse chronologically. Pages allow more freedom and flexibility, nested hierarchies, etc. and want some addional configuration tuning accordingly. We will be creating a post in this example. So, without further dwadling about…​

~ $ cd ~/Projects/my-new-blog/content/asc/posts/

Engage your preferred text editor and visit a new file, for example, my-killer-post.asc. [7] Include some minimal header infos:

~ $ head 2014-10-10-adoc-post.asc
{:title "Adoc Post"
 :author      "yer' kewl pseudonym"
 :date        "1999-12-31"
 :draft?      false
 :layout :post
 :tags  ["cryogen" "asciidoc"]
 :toc false
}

Now flesh it out.

= Level 1 Header
This is an example asciidoc post.

== Level 2 Header - Lists

Asciidoc sports support for lists.  Lists must be preceeded by a blank line.

=== Level 3 Header - Unordered

And and nice list captions.

.Unordered List Caption

* foo
* bar
* baz

=== Level 3 Header - Ordered

.Ordered List Caption

1. One
2. Two
3. Tres

== Yet Another Level 2 Heading

But wait, There's More! Footnotes:
footnote:[Try that with Markdown,eh? ;-P].

See AsciiDoc Writer’s Guide for more Asciidoc authoring goodness.

Flesh out your article. Save/autosave your work often. Refresh your browser. Enjoy your REPL. [8] Cryogen gets it.

5. Publish Content

Enumerating the myriad modes Cryogen rendered html pages may be transferred to your webserver is beyond the scope of this article. Suffice to say, there is more than one way to do it. Depending on your circumstances, options like rsync, scp, sftp, git, etc. should be in your toolbox. If not and you would like some guidance…​.

I favor rsync. [9]

  1. Ensure you are in your new blog’s content directory. Yep. That very same one where your blog’s config.edn resides.

  2. Surprise, surprise! You now have an additional subdirectory named "public".

  3. Upload this directory and its contents to your web servers public_html directory.

~ $ rsync -avs public my.server.tld:/webserver/foo-whatever/public_html

Mind the trailing / when pointing to public above, else rsync will create a public subdir in your public_html directory. Which may be what you want. Readers are referred to rsync’s man page for futher enlightenment regarding sources, destinations, and various option flags. I shall presume by now that you know the proper directory for your web server and able to adapt the above accordingly.

Geronimo!
Yer' good to go!!
Big Medicine!!!

Please enjoy Cryogen responsibly.


1. ~ $ lein --help in your project root directory is your friend.
2. Examples include sftp, scp, git, and rsync.
3. But not both simultaneously on the same blog. So pick your poison.
4. At least as objectively as I could since I did have some familiarity with Asciidoc. Hey, what can I say? Asciidoc came first.
5. Uh, did we mention that you may want to use Java 8?
6. Shout out to Dimitri for helping me get this sorted out.
7. Name your file using the .asc extension. Asciidoc recommends using .adoc but this extension is unsupported as of yet on Cryogen.
8. To be fair, Cryogen is not the only SSG sporting a REPL.
9. Example presumes you have already uploaded your ssh public key to your webserver.
Tags: cryogenweb asciidoc guides