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:
- Contentful does not provide the whole asset object for images when they are
used in markdown. Meaning that I would have trouble providing (among other
things) a width and height to
responsiveImage. - Rich text has a handy embedded inline entry feature that I have been using for footnotes in the page margin. That’s not going to be an option now.
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
- Remark is easy to extend and has lots of plugins to further add syntaxes in future.
- My content is portable again. I can migrate from Contentful in future if I need to.
Cons
- Markdown is a second-class citizen within Contentful, matching all the platform features of rich text will be tricky, if I ever wanted to.