TheOverAnalyzed

This is Part II of the series entitled Leaving Squarespace, in which I outline how I left a traditional CMS and dived deep into Casey Liss’s static blogging engine, Camel. If you haven’t already done so, you should read the first post in the series. And when you’re done with this post, you can read the next one as well.

Introduction ¶

A goal of mine from the beginning was to port over the ~250 posts I had accrued while using Squarespace. Not only would redirects have to get sorted out, I also needed to make sure that the old posts looked correct in the new platform. Modifying my plain text files for use with Camel wasn’t particularly difficult. It was, however, extremely time-consuming. In preparation for the move, I made tweaks to metadata, images, and footnotes.

Metadata ¶

Previously On TheOverAnalyzed ¶

Before transitioning to Camel, I adopted a hybrid metadata system inspired by both Byword’s MultiMarkdown guide, and, perhaps fortuitously, Camel itself. All of my posts since TheOverAnalyzed 2.0 had Title:, Date:, and Link: metadata. Byword is smart enough to know that properly-formatted text placed at the top of the document denotes metadata. Byword would then omit that when parsed to HTML.

Byword’s metadata support is everything I would want in a plain text filing system. The metadata’s there when viewing the Markdown source, but disappears when parsed to HTML. I wish Camel supported metadata in the format that Byword supports, but it doesn’t out of the box.^[1]

Metadata In Camel ¶

Unlike Squarespace, in Camel, having metadata within the actual Markdown files is absolutely necessary. Casey designed his blogging engine such such that camel.js generates all the posts and the rest of the website using these template files. These template files specify page attributes such as page headers, page footers, etc. The template files are based on Handlebars {{strings}}. Camel uses metadata strings to piece together the parts of the posts, such as the post header, the post footer, etc. And because of the way the Handlebars script works in conjunction with Camel, metadata must be called out in a particular way. In the default configuration of Camel, that’s via a @@ prefix.

Images ¶

Previously On TheOverAnalyzed ¶

In the months leading up to TheOverAnalyzed 3.0, I transitioned from Byword to MultiMarkdown Composer. Fletcher Penney’s app offered MultiMarkdown 3 features that were crucial to my workflow, such as {{TOC}} for auto-table-of-contents, and most importantly, lots of nifty image syntax.

For instance, if I wanted to embed an image with caption in MultiMarkdown Composer, this is all I would have to write:

![Caption][alt]

[alt]: link

And this is the resultant HTML:

<figure>
	<img src="link" alt="alt"/>
	<figcaption>Caption</figcaption>
</figure>

Byword, for whatever reason, doesn’t offer easy image-captioning. MultiMarkdown Composer was the only way to achieve easy image captions, so I started using it instead of Byword.

I Can’t Get No ¶

While MultiMarkdown Composer surely got the job done, it never quite felt like home. Yes, I realize how weird it may seem for me to describe a plain-text editor as homey. But it’s true: Byword’s UI/UX is just better than MultiMarkdown Composer’s. Metaclassy did a great job with gradients and shadow effects, as well as other pleasing design touches. Still, I was stuck with the latter due to my dependence on the full MultiMarkdown 3 spec for easy image captions. Moving to Camel was an opportunity to re-examine my writing workflow. Within Camel, perhaps Byword could find a new purpose?

Images In Camel ¶

Camel uses an npm package called markdown-it, which is what actually takes the Markdown files and parses them to HTML. markdown-it, even with plugins, does not support any of the nifty image syntax offered by MultiMarkdown 3 and MultiMarkdown Composer. So the easy image syntax I used in the example above would not work using markdown-it and Camel. This nullified my reliance on MultiMarkdown Composer and made it so that I could go back to using Byword.

Using Byword for future posts was an excellent prospect. But that didn’t make the old posts formatted with MultiMarkdown 3 syntax play nice with Camel. In order for those posts to get parsed correctly by markdown-it, I would have to make changes to the image syntax.

Unsure of what image syntax Camel would support, I followed Casey’s lead. As has been my M.O. for the past year, I peaked at the source for one of his posts containing an image with a caption.

Here’s what I found:

<figure class="figleft">
	<img src="http://www.caseyliss.com/images/2015/3/iphone.png" alt="Steve Jobs debuts the iPhone" width="300" />
	<figcaption>Are You Getting It?</figcaption>
</figure>

Casey was using regular-old HTML HTML5 for his images.

At first I scoffed at this. Why would I want to type out all that code—John Siracusa style—just for images? I even considered omitting image captions entirely, as the ‘standard’ Markdown image syntax of ![](image link) is parsed perfectly by markdown-it. However, captions are important to me.

The biggest reason to use Markdown is that it’s essentially shorthand HTML. Typing all that <figure> stuff is a pain not because it’s difficult to understand the syntax, but because it just takes so much time to type all that out. I needed time-saving if I was going to use regular HTML syntax for images.

Here’s what I decided to do:

1. I created a ‘starter’ post file called template.md, which lives in my Camel folder at ~/TheOverAnalyzed/Camel, and has a shortcut on the Dock.

2. The contents of that template file are thus:

   

3. When I need to embed a picture, I can just copy and paste the <figure> syntax I prefer^[2] from template.md^[3]

   Having the <figure> syntax pre-populated makes embedding images easier because it eliminates much of the time associated with writing pure HTML^[4] Once I wrapped my brain around that, I began the long and tedious process of opening my old posts and switching all the MultiMarkdown 3 image syntax to regular HTML.

Footnotes ¶

Previously On TheOverAnalyzed ¶

My previous usage of MultiMarkdown Composer would also cause me trouble with footnotes in Camel. Previously, I wrote all inline footnotes in the following format:

Text.[^Inline footnote]

This would then get parsed to this:

<p>Text.<a href="#fn:1" id="fnref:1" title="see footnote" class="footnote">[1]</a></p>

<div class="footnotes">
<hr />
<ol>

<li id="fn:1">
<p>Inline footnote <a href="#fnref:1" title="return to article" class="reversefootnote">&#160;&#8617;</a></p>
</li>

</ol>
</div>

Because I was using the parsed HTML as the content for my posts in Squarespace, it didn’t matter that Byword couldn’t understand inline or multi-paragraph footnotes.

Footnotes In Camel ¶

Out of the box, Camel includes the markdown-it plugin markdown-it-footnote, which allows for MultiMarkdown 3-style inline and multi-paragraph footnotes.

Neither inline footnotes nor multi-paragraph footnotes are supported by Byword. But as long as I format the footnotes syntax correctly, everything will display properly in the parsed HTML.

---

During the two solid weeks I spent transitioning to Camel, most of my time dealt with tweaking how the site looked (the topic of a future post in this series). Second only to that was re-formatting my old posts. Most days, I would get home around 5-6 PM, and after eating dinner, I was glued to my MacBook, re-writing the image syntax and making other small. It was arduous, but so worth it in the end. Stay tuned for the next post in the series.