Replacing my Octopress blog with 200 lines of Babashka | Hacker News Reader

Replacing my Octopress blog with 200 lines of Babashka

blog.michielborkent.nl

166 pointsgrzm27 comments

I love these hands-on write-ups! This one is particularly well written and thoughtful. It makes me feel I could follow along and do it myself.

For me, the posts underlines the argument that you’ll feel better if you stick to the tools or languages you know.

The $RET$ hack smells weird. Can you join the lines before flushing it down the markdown renderer?

Very nice indeed. I bet it wasn’t the intention of the author, but the intro sounded a bit critical of Octopress and of how it fell behind, and so on.

Perhaps I woke up in the wrong mood, but I’d have praised the authors and community of the tool, it’s open-source, was built with generosity out of one’s own free time. That’s quite a capital!

So, we all know stuff gets abandoned, people do move on, perhaps they could handle handovers or sunsetting better, but let’s be first of all grateful.

I'd agree with you, but the passage is really not passing any blame and is being factual, not exaggerated or flaming the authors in any way. I think it's a pretty fair observation even if critical. Doesn't mean the work so far wasn't appreciated.

For posterity, here is the passage:

> I started using Octopress back then and was still using it until today. In recent years I became frustrated with it since on every new system I had to install a version of Ruby that happened to work with Octopress, which wasn't always the case. When it did work, I started getting deprecation warnings from Ruby while compiling this blog. On top of this, Octopress seemed no longer maintained. The website says "Octopress 3.0 is Coming" but this announcement was from 2015 and the website hasn't been updated ever since. It felt like time to move on.

Thanks for the feedback. I added the following:

Octopress worked great for my blogging purposes and I'm grateful that it existed. However, in recent years I became frustrated with the experience of using it, which is probably due to a lack of my familiarity with the Ruby ecosystem.

This is a lovely, honest sentiment. Thanks for sharing (here and on your blog).

> The $RET$ hack smells weird. Can you join the lines before flushing it down the markdown renderer?

Unfortunately this didn't work since it would also join lines in code snippets that contained []'s. This is a basic hack that prevented me from writing a more sophisticated markdown parser.

The problem with things like the $RET$ hack is that now you have a forbidden magic character sequence. Although this isn't the worst thing in the world, it doesn't look like you're doing basic validation on your input to make sure that that sequence doesn't already appear organically, which is the consequence of doing things this way.

Considering you now have at least one input file where this sequence does appear organically (i.e. this blog post), I'm also curious how your setup is handling this correctly instead of mangling the content. What am I missing?

Since this is my personal script, I'll take the trade-off of not being able to use $RET$. If I would have written a framework or library, I would have solved it more at the root level, but that wasn't a cost I was ready to pay at this stage. The real sequence is $$RET$$ so what you see in the blog post is a variant of this, just to explain the idea.

I added a clarification of this in the blog post.

> In Octopress, blog posts start with a section like … I removed these sections replaced them with maps in a file called posts.edn:

Part of blogging in markdown files is universal portability: you can use any editor, parser, doc publisher, or site generator on a set of generic plaintext files. Those headers were “YAML Front Matter” standard metadata, and for portability belong in the file not elsewhere.

This is used across pandoc, static site gens, Markdown parsers, and Markdown editors (VSCode, Sublime, Bear, Ulysses, Obsidian, Typora, etc.).

https://jekyllrb.com/docs/front-matter/

https://forestry.io/docs/editing/front-matter/

https://assemble.io/docs/YAML-front-matter.html

https://blog.valeconsulting.co.uk/2019/09/05/automating-docu...

https://docs.zettlr.com/en/core/yaml-frontmatter/

And finally, Clojure library designed to parse front matter:

https://github.com/liquidz/frontmatter

The bog-standard Markdown editor would output the front matter directly in the post, unless it specifically has support for front matter. So if you're really aiming for "universal portability", get rid of the front matter.

And there is nothing wrong with inversing the control of the metadata. Instead of having each file carrying the metadata and you need to iterate filenames to get the full list, it's OK to have a index that has the filenames to read + the metadata. Simply a matter of preference and not really a requirement for someone to say that they "blog in markdown files", whatever that means.

Simply a matter of preference...

It's not simply a matter of preference. While front matter isn't a part of the Commonmark spec, it is very well adopted to the point where it's effectively universal across blogging apps and static site generators. You can move a markdown file from Hugo to 11ty to Gatsby to Hexo to Jekyll without changing or losing any of the content and they'll all understand your title, slug, posting date, labels, etc without any configuration or code changes necessary.

You lose that by doing something different even if you prefer an alternative approach. That's something to consider if you choose to go against the grain. It affects more than just preference.

Personally the biggest advantage I see of front matter is that it encapsulates everything about a post in one place. I don't need to update an index if I delete a post, or add one, or something.

That said, writing a script to take the index content and insert it in to the post markdown files as front matter wouldn't be very hard, just as it'd be very simple to extract front matter to your own index file, so it's not really a big deal however you choose to do things.

I'm not married to either one of the approaches and it's fairly trivial to switch between the approaches if I might change my mind.

It seems this author has no interest in using any other blogging frameworks so why does it matter?

The project is cool, I enjoyed the walkthrough, and I like Clojure and love seeing discussions applying it in everyday use.

But this particular design decision, which works well for the author, is worth flagging for others as it bumps against a variety of first principles in Unix and Lisp such as simplicity, composability, and interop/portability apart from tools.

For example, from your comment:

> Instead of … filenames … have an index [of] filenames to read + the metadata

And now you have to sync an index of metadata on top of the existing index and files. If you interact with the files through any other tool, you can have files not in the index, or index w/o files…

Plenty use cases depend on that. Here’s a user asking about inability to independently edit files with Joplin:

https://discourse.joplinapp.org/t/yaml-front-matter-metadata...

But here we already have an index, the directory tree, that already contains the critical metadata: name, created/modified dates, sufficient to retrieve the media and the media specific metadata. Can even natively leverage tags if we use file tag metadata natively supported in some filesystems, then the OS GUI and other apps can search and retrieve w/o extra moving parts, and still read custom metadata from the media (in this case plaintext markdown article) itself.

Also, most “bog standard” markdown editors have, by now, a toggle to pretty print or table-ize frontmatter, and suppress it on publish (especially since many leverage pandoc which supports that). When they don’t, it’s just three dashes and some TOML, works fine as text.

Put another way, YAML Front Matter is to plaintext .MD articles as ID3 tags are to MP3, AIFF, AIF, M4A, M4R, FLAC, OGG, WAV, APE, ASF, and WMA audio files.

TL;DR:

Even if you maintain a separate index, you still want to write back the metadata into the media file standard so the media outlasts the media management tool.

It’s universal portability, but at the cost of only using the lowest-common-denominator features of any random markdown implementation. There are so so many more things that can be done with websites and long-form writing than big standard markdown, and even Pandoc (which I consider to be the most versatile fully-featured markdown implementation) has extensive support for user-written filters, which provide more on top of what Pandoc markdown provides.

What is the priority - being able to switch blog implementations at the drop of a hat, or having an actually good website?

I know a lot of people that moved from Octopress to Hugo. I still keep using Pelican which has been around for close to a decade now and is still actively developed.

Judging by the repositories Borkdude (author) is normally working on (seemingly), I'd say Golang (language Hugo uses) suffers the same problem as Ruby does. Seems anything Clojure is much better fit for them than anything Golang.

Also, Hugo/Golang has it's own templating and really, who wants to deal with templating in 2021? XML/HTML as data (like Hiccup does) is so much easier and flexible.

In the case of Hugo one can download a binary release, so it does not suffer from the same problems.

If you use Hugo for anything else than just basic blog posts, you're eventually gonna have to A) read the source to understand how stuff works and B) use their/Golangs horrible templating language. Using a binary doesn't make you avoid that.

I once updated the dependencies of a octopress blog and it changed the enumeration rendering of lists from bullet points to numbers :-)

I went through a phase of switching blog engines, then settled on Pelican. I haven't felt a need to switch for the last six years.

Same here. Another advantage I've found is that I can have a virtualenv with my particular pelican version and never feel the need to update. There are no moving parts on the server, so as long as the HTML / RSS output works, everything is fine. At this point I don't like dealing with the (necessary, expected, I'm not critizising that) bits that break between versions.

I use Pelican for my blog because it meets all my requirements: markdown, latex support, jupyter notebook support, syntax highlighting, and integration with GitLab. I tried another blog engines, like Jekyll and Hugo. However, since I do not use Ruby and Go daily, I did not use those engines.

Some things I would like to see in Pelican are:

- Better documentation in the code. The documentation for the final user is great. However, if you inspect the code, it will take some time to understand it since many functions are not documented. Compared to other code bases, like Keras, the docstrings can help the developer.

- More themes. The default theme is not my favorite. Also, I think Jekyll and Hugo have better themes.

(It is not a critic. I love Pelican)

This is a second post I see about "do your scripting in xyz". I wonder in what ways the *nix ecosystem with sh and all the tools around it is insufficient. Is it a case of wanting everything to have your favourite flavour?

The fact that writing bash is an awful experience might have something to do with it

I love seeing examples of people showing off a simple, purpose built solution. It's possible to do simple things quickly and with a small amount of code.

Reply on news.ycombinator.com