I made a new block plugin for adding markdown comments that only display while editing a post with Gutenberg. Last week, while editing an upcoming article all about block plugins and the WordPress block directory, I wanted to add persistent notes and reminders within my post content – but didn’t find a proper solution. So naturally, I hit the ground running and pushed out a new block to the WordPress Block Directory to do just that—aptly called the Markdown Comment block.

And even better, it’s available to anyone running WordPress 5.5 or later, just by searching for it within your local Block Library.

This is the first block I’ve directly published in a while. I knew I wanted to lean in on block plugins to understand the ins-and-outs of this new WordPress plugin classification, so it seemed fitting to serve a need of mine and gain some experience while I’m at it. But why markdown comments? I honestly enjoy drafting articles either locally in Ulysses, or on my blog here in the Iceberg Editor. While I do love Iceberg, once I publish an article I typically bring back the default Gutenberg experience — thus removing any comments I previously added. 

Having the ability to add, and keep, any relevant editing comments within my posts, without rendering them on the front-end, means that I am freed up to mentally jot any idea down without thinking about it. It is simply natural and convenient.

What’s interesting about the block?

Now the block itself is relatively simple. Markdown Comment is essentially a single line RichText component with a few nuances: 

1. Editor only

As I mentioned, the block only renders within the editor. For developers reading this, that means there’s no save function. I don’t want my unfinished ideas, reminders, and notes rendered within my post – even if they’re hidden by CSS. 

2. Helpful transforms

I added a couple transforms, to and from headings and paragraphs, and a raw shortcut when you type %% and hit the [space] key. This lets me quickly add comments, and even convert whole paragraphs or headings to a comment. 

3. Easily resolve comments

To support that path towards simplicity, I wanted a method to quickly resolve — i.e. banish — a comment entirely. So, I added a toolbar control to quickly resolve the comment, removing the block entirely.

4. No rich text support

Comments need to have minimal impact on editing, and feel as natural as possible. That’s why there are no typical RichText controls (although you can still bold, italicize and add hyperlinks). And while you _can_ change the color of the comment — there are no other typographic controls.

5. Entirely CSS Variable ready

Global styles and full site editing are opening the door for themes to be heavily powered by CSS variables. Blocks should be designed with that same mentality, which is exactly what I did here. I added simple CSS variables with fallbacks that are the default values.

To further theme the comment, there’s no need to override any styles with classes, just write a few CSS variables like this:

:root {
  --markdown-comment-color: #B4473C;
  --markdown-comment-font-size: 15px;
  --markdown-comment-line-height: 1.8;
 }

Other ideas

I did explore adding a direct link to the block via an anchor tag of sorts, consisting of the initial block ID (saved as an attribute) — but that didn’t quite work out. The anchors/link creation works perfectly, as well as a nifty “Copy direct link” block toolbar action, but I don’t think there’s a mechanism in place to allow for pulling a specific block into focus within Gutenberg. 

I thought it’d be great to be able to link directly to a comment, say when I have something I’d like to follow up on in the future. I did ask around on Twitter, but perhaps you have an idea? Anyhow, I had a lot of fun jumping into block development. Let me know if you find my Markdown Comment block as useful as I do. And do reach out if you have any ideas for blocks you’d like to see in the Block Directory.

Edit: Justin Tadlock wrote a review of the Markdown Comment block on WP Tavern. It’s a good read — thanks Justin!