← Back

Converting to Markdown

Recent changes
  1. #a94196d8b9c0f1bd8fca4c3ffea52e78282c2e68

    Squashed commit of the following:

  2. #f8df35d280b31bcd9f2f7496faf4ad28cc871c4f

    Replace 'markdown-it-sidenote':

  3. #f56af85b82d855bf6ea8c71998d4c895a0f854d2

    A flatter file structure (#21)

See all changes

I love markdown, it’s simple, extendable, future-proof, and used almost everywhere. I write everything in markdown including the content on this page.

Until now I’ve been taking my markdown and manually converting it to Contentful’s flavour of rich text, the default WYSIWYG editor field. Rich text is okay but it’s not as simple as markdown, and there’s no way to write it outside of Contentful itself. Luckily Contentful does support markdown, so in the spirit of reducing friction 1 I thought I would make the switch.

This isn’t as simple as it would seem, for a few reasons:

Footnotes in the margin

My markdown renderer of choice [remark] 2 helpfully has a footnotes plugin which removes a lot of the upfront work. Unfortunately it formats the footnotes traditionally—inline links, with the definitions at the bottom of the page—I want my footnotes in the margin, next to the correct paragraph. The solution was to write my own remark plugin. The plugin traverses the remark tree, moves the definitions to become a sibling of the footnote reference, and then wraps the result in a new ‘paragraphWithFootnotes’ node. Finally I can tell remark how to render that custom node.

Grabbing image assets from Contentful

My solution to the image problem is to redefine how remark renders images. The markdown provides only the image src URL, which fortunately contains the Contentful entry ID. After slicing out the ID I can the correct asset out of the assets array. Then I can pass that to my responsiveImage shortcode, which I adapted to optionally return an object of the attributes remark needs to constructs the image.

Overall I’m happy with the outcome, I can write in the my format of choice from now on, but there have been some pro’s and con’s:

Pros

Cons