← Back

Converting to Markdown

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.

  1. Nº1 Brian Lovin recently gave some excellent pointers for making personal sites more updatable.

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.

  1. Nº2 remark is a Markdown processor powered by plugins.

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: