@shitchell
February 6, 2021

---

blogging battle: jekyll vs hackmd

after leaving facebook, i wanted to find a place to post my musings and techy stuffs and sunset pictures for self-validation so that my experience can benefit others. my requirements for a blog were:

1. free
2. simple to use
3. beautiful interface

i already have a vps from digitalocean, so "free" could potentially include any self-hosted solution (django, wordpress, etc). unfortunately, setting up and (more importantly) maintaining it would most likely clash with "simple". security, load balancing, etc… i love full stack, but in this case i just want to blog painlessly.

if you want to skip the in-depth overview of both platforms, skip to the side-by-side comparison.

jekyll

the first potentially viable solution i looked at was jekyll. if you're already familiar with it, go ahead and skip down. if not, it's basically a static site generator with a focus on blogs.

what's a static site generator?

i'm so glad you asked! basically, it takes templates / code and converts it all into a static website to be hosted somewhere like github (since github doesn't support backend langauges). it would be as if you used php+apache to generate a website, viewed it in your browser, saved the pages, and then uploaded all the raw, generated html to github.

example template code

<div id="flavours">
    {% for flavour in page.flavours %}
      <span class="flavour">{{ flavour }}</span>
    {% else %}
      <h3>There are no flavours</h3>
    {% endfor %}
</div>

example generated html

<div id="flavours">
    <span class="flavour">apple</span>
    <span class="flavour">kiwi</span>
</div>

where php et al generate html on the fly every time someone loads a page, jekyll does it one time and then serves the result. every time you want to change a page, you have to rebuild the entire website and upload the new html.

building

much like running any backend framework, you need some software to generate the html from the templates / code. makes sense–-if you're using django, you have to install python to do anything with the code that builds your website. for jekyll, you need ruby and some jekyll libraries.

github support

the super sexy aspect of jekyll is that github will take care of the building step! you don't actually have to install any software yourself; after every commit, github will (re)build the static website for you. so once you have it set up, all you have to do is go to your blog repo, navigate to the _posts directory, and add a new markdown file all from your browser! easy peasy.

and that would be the end of it except for that pesky "once you have it set up" part. i tried cloning and setting up jekyll, but i'm just not that interested in setting up and customizing it. when i'm passionate, i'll spend 24+ hours just coding. when i'm not, it's just not gonna happen.

jekyll-now

if you don't want to bother setting it up, there's actually a repo called jekyll-now that takes care of it for you. the steps are pretty simple:

1. fork the repo
2. edit /_config.yml for your site
3. add markdown files to the _posts directory

that's it. done. this actually handles my requirements pretty nicely. i'm not a huge fan of the ui/ux, but it's not horrible. and it's not too hard to improve it with a modicum of work. i'm currently editing a fork of jekyll-now and might end up using it long-term.

reverie

one last potential solution is reverie. it's a theme for jekyll that claims to similarly require no command line struggles. not that i hate the command line. don't get me wrong; my computer doesn't even start a gui automatically on boot. i

cli. but the promise of no command line makes me think it's more likely to be the level of setup i'm looking for. i'll update once i've given this a shot.

hackmd

i was just looking for a free, clean site to edit and host markdown files when i stumbled across hackmd. i was blown away. every other similar service i found was pretty lacking, and then i stumbled upon a site with more features than ever i dreamt.

markdown

i mean, you can even add a friggin fretboard to your markdown files! i've never seen markdown implemented with such versatility, diversity, and utility

some feature highlights:

• diagrams (sequence, uml, flowcharts, etc)
• render csv as table
• embeds (youtube, gists, pdf, etc)
• emojis

view modes

you've got 3 main ways to view a note:

view

simple, clean reader mode with an outline of the headers to the left for navigation. only slight caveat is there's no dark mode

edit 2019-02-19 i went ahead and just created a dark theme that can be embedded in other notes

slideshow

it uses hugo + revealjs to generate beautiful, highly customizable slides from markdown (with each slide separated by --- in the markdown). the cool part is that building slides this way allows you to use a tool like git for tracking changes.

book

this mode collects all of your headers and links and converts your markdown into something more like a book. as someone who does a lot of tutoring and teaching and leads various workshops, i'm genuinely excited to use these.

editing

the editing experience is absotively sublime *ha! i crack me up*.

you've got an option live preview, and your markdown gets semi-converted in the editor. autocompletion and helpful if you want, you can also fullscreen the editor:

the editor also boasts:

• realtime collaborative editing (a la google docs)
• version history (with optional named versions)
• "host" mode where everyone's pages will scroll in sync with the host (to ensure everyone is on the same page)

theming

you can customize notes using css e.g.:

body {
    background-color: #333;
}

.markdown-body h1 {
    font-size: 1.5em;
}

your css will get applied to the entire page, but you can optionally prefix your rules with #doc or .markdown-body to ensure they only apply to elements within your note. further, you can reuse these styles by:

1. creating a note with nothing but style rules
2. embedding that note within other notes

embedding

{%hackmd @shitchell/dark-theme %}

unfortunately, the embed code will show up in note previews (like on your profile page), so you have to embed them at the end if you want to keep the preview snippet clean. this is slightly not ideal.

however, this does open up the possibility to reuse certain elements (e.g. headers, footers, nav stuffs, etc) across pages more like a normal website.

hackmd embedding tutorial

profile page

this is where hackmd shows surprising potential as a blogging platform, although it falls a little short for my tastes when it comes to tags. i'd like to be able to see the tags associated with each note, but right now the only thing you can do with tags is to use them for general filtering:

pros

• profile picture
• about me
• can sort notes by date/title
• can filter by tags
• can view liked notes
• can search notes

these are all features i wouldn't have expected that make it alright for blogging

cons

• can't see what tags a specific note has
• can't get notified when a user creates a new note

these two kinda kill it for me. i suppose you could write a note that includes some mailchimp subscription (i'm just pulling that out of my butt; i've never used mailchimp and don't know if it would really work like that) or create your own subscription process using a backend server… but that's exiting the realm of simple. still, i'd rather set that up once than have to forever maintain and keep secure an entire blogging website on my server. so it's less simple, but not in a way that irks me as much as it could (i'm finicky and moody; i accept this about myself)

comparison

	hackmd	jekyll	jekyll-now
setup time
customizability
tagging
aesthetics
post editing
collaboration
post sorting/display

conclusion

hackmd has a lot of awesome features that will keep me using it for as long as it remains free and awesome. and if ever it's not, they've got a slightly stripped down open source version that i will simply host on my own server (see? finicky. that's worth hosting and maintaining to me).

but as for blogging, i'm not sure yet. i've opened a couple of issues with the hackmd maintainers regarding tags and subscribing to a user. in the meantime i'm also slowly customizing jekyll-now in my free time and curious to try reverie+jekyll. if hackmd updates based on those issues, i'll happily resolve to just use it and it alone :D else i'll probably switch to jekyll at some point after i've customized it to my liking, and then just transfer all of my .md files there (another nice feature of hackmd–exporting everything!).

tags: hackmd jekyll blogging