Software, Development, and WordPress

Markdown Syntax (And Developer’s Tunnel Vision)

As far and and as exciting as text editing can get, one of my favorite introductions into the space in the last decade has been Markdown.

I remember the first time I read about it, I loved it – it was essentially simplified markup – and the first time I used it regularly was when Stack Overflow launched.

Then I began to write my text files using the format even if the tool didn’t support formatting because it help to make reading the text file that much cleaner (besides, sometimes word processors are just overkill, aren’t they?).

Notes for Mayer in Markdown

Notes for Mayer in Markdown

Then other development-oriented sites began implementing markdown parsers into their site much like Stack Overflow did when they started. For developers and others who enjoy writing in markdown, it’s been a really cool ride.

With tools and services like:

I’d say that markdown is more prevalent than it’s ever been.

And although I’m someone who clearly is clearly a fan, I can’t help but think that developers are developing a bit of tunnel vision as it relates to a way for everyone to write.

Markdown Syntax – It’s Not For Everyone

Here’s the thing: Over the past couple of years, as we’ve watched markdown be implemented in more and more platforms, we’re getting to a point to where we’re seeing platforms offering it as a way – if not the way – to write text.

In fact, entire publishing platforms have been built around the concept and marketed as a way that makes it easy to not only draft content, but to get a live preview of what you’re going to see on the front end when the post is published.

But this is where I think those who are involved in technology are giving markdown too much credit.

Yes, it’s easier than markup. Yes, it provides clean formatting of plain text, yes it’s easy-ish to write parsers for it, yes it’s nice that there’s a standard set of rules for it, and yes it’s great that there are so many applications and tools that make it easy for us to use it just about anywhere.

But the truth is that it’s still syntax – it’s simplified form of markup (hence the name) – and I argue that the average publisher, author, or writer is not willing to break away from that.

Just like shortcodes can be viewed as a type of tag or high-level markup, as can markdown. And this, I believe, can negatively impact the user experience for writers.

Learning a Language To Write?

When I hear that a given publishing platform – be it Ghost, WordPress, or whatever else – is offering markdown as a way to publish content, I dig it.

I really do.

But part of me also hopes that it’s not the only way for people to draft their content because I think that the average person is still used to the WYSIWYG editors, or the editors that have toolbars that resemble what their used to seeing in their day-to-day tools, namely, word processors.

And face it: Reading *this* is not as easy as reading this when you aren’t trained in the syntax, is it? The same can be said for **this** and this, and those are two of the simplest examples.

All of that to say is that I fear the people who are building tools that enable other people to publish are slowly beginning to push their preferred methods onto others who not only aren’t interested in learning the syntax, may not even understand what’s wrong with text-formatted as they know it.

It’s Not The End All Be All – Choices Matter

To that end, I will always advocate for markdown being a choice – not a standard – for people to draft their content, but I also believe that it’s important we not expect non-technical users to want to author their content in that way.

This isn’t a statement about intelligence or willingness or ability to pick up a new syntax, but about writing and the user experience that comes with it.

As someone who enjoys writing, programming, and obviously markdown, I can also say that I’m someone who drafts all of his posts in the WYSIWYG editor of WordPress using `editor-style.css` because, when done right, it helps me to see clearly see what my content is going to look like when it’s published, and shortcuts save me just as much time as do syntax of markdown.

Writing with Editor Styles

Writing with Editor Styles

So if I haven’t been clear about it, I absolutely dig on markdown and think it’s a fantastic way to format text for certain people, but I think developers are getting too close to making it one of the default ways of writing which is still too cryptic for the average writer to learn.

I’m all for markdown – let’s make it an option in every text editor or web application – but let’s not make it the standard way in which people have to write.

Give ’em the choice of how they want to write; otherwise, we risk making something that should be fulfilling – that is, writing and publishing – a bit of a frustrating chore.


  1. Nate Wright


    Making the jump from WYS to WYG, even with a simplified syntax like markdown, is a huge hurdle for everyday users. I still do regular, direct client work and it’s a great reminder of how difficult many people find it to conceptualize and master what developers know are highly simplified systems.

    • Tom

      …what developers know are highly simplified systems.

      That are built by other developers, no less.

      It’s like when something is wrong with the ignition coil in your car and you have to ask what the ignition coil is, then the mechanic laughs at you for not knowing what that is.

      Smh. All day long.

  2. Michael Musgrove

    I think the answer may be what several editors offer, like Ghost, and that’s the ability to do both simultaneously. I like being able to stick HTML in with my markdown when wanted/needed without even having to think about it.

    • Tom

      I think being able to mix the two is a great option, but I still see that as leaning in the direction of developers because it requires knowledge of syntax, a language, and so on.

      That’s not to say we should avoid it – again, I’m all for choice – but if you’re going to offer the ability to draft content, offer up several ways to do it: HTML, Markdown, plain text, WYSIWYG, whatever.

      I just want to see us stop leaning in our own direction and then saying our solutions are somehow more elegant than something that people outside a niche don’t understand.

  3. Eldon Yoder

    Good thoughts Tom!

    I definitely agree with what your saying here. When Markdown showed up in Jetpack I was thrilled… However I have used it very little. Partially because I haven’t totally learned Markdown and partially because a lot of my writing happens away from an internet connection. Without the ability to upload images or insert correct links, it’s just easier to write plain text and “mark it up” once I start working with the post in WP.

    I do want to learn to use Markdown [because its kind of cool and potentially faster to type], but definitely think it should be an option, not THE way to edit in WP.

    • Tom

      I do want to learn to use Markdown [because its kind of cool and potentially faster to type], but definitely think it should be an option, not THE way to edit in WP.

      Yep – we agree completely.

      And I could be wrong, but I don’t think anyone is saying that it should be the way to draft content in WordPress (of course, the Internet is large so someone is probably saying it :), nor do I think it should be the way to draft content in any publishing platform.

      It makes sense in the context of things like, say, GitHub; however, that’s a developer-centric tool. If you’ve got developer-friendly languages around developer-centric tools, then go for it!

      Otherwise, we’ve gotta have options.

  4. Mark Root-Wiley

    Really great post. I’ve been thinking this a lot and so I’m glad someone said it for all to hear. I remember when WP Tavern covered the Jetpack module for markdown and asked whether this was a move to offer markdown as the only editor (or default? I forget which). I was shocked.

    As someone who works with clients and does a lot of trainings, it can’t be overstated how helpful that work is in keeping my expectations for the “average” user in check. And like you said, implementing editor-style.css is so important. I’m really surprised how infrequently it still seems that I see it.

    • Tom

      Like you, `editor-style.css` is one of the features of WordPress that I wish more people would take advantage of.

      It’s relatively easy to implement, goes a long way in bridging the gap, and really enhances the overall drafting experience, in my opinion.

      But yeah – setting a syntax-based editor as the default editor for a massive blogging platform seems at odds with itself.

  5. Kraft

    Agreed completely. While I’m excited that Markdown is in Jetpack now, I’m equally excited by the work of the Front End Editor feature plugin and Jaquith’s new plugin toward enabling users to touch markup, in any form, less.

    I don’t think any of the options should be added at the exclusion of others. Plain-text markdown works great for some. Editing in raw HTML other. The quasi-WYSIWYG others while editing a post directly on the front end will be preferred by others. We should make it easier for people to use and publish with WordPress—no matter their markup choice :-)

    • Tom

      Agreed completely. While I’m excited that Markdown is in Jetpack now, I’m equally excited by the work of the Front End Editor feature plugin and Jaquith’s new plugin toward enabling users to touch markup, in any form, less.


      And I agree with your statements on the variety of editors. Each serve their purpose and they generally do a good job at it. To that end, I think we need to be mindful of the choices we’re offering and be intentional about them.

      And I certainly wouldn’t want to retire anything that’s going to alienate the average author.

      If anything, developers can suck it up and get away from markup or markdown ;).

  6. Rusty S

    I’m not against choice, but I *am* and advocate for accessible content.

    Giving users the ability to make text bold and big, à la MS Word, and not forcing the proper use of a heading tag (when the text is a heading), for example, encourages bad habits. Markdown, in my opinion, encourages good, semantic structure and aids in creating accessible content.

    That’s my ¢2.

    • Tom

      I – and I think many – are advocates for accessible content, as well, but I’m not sure that Markdown, when used by someone who doesn’t really think in terms of the hierarchy of text – is going to use its syntax to make their text any more or less accessible.

      Bold is bold no matter how you generate it.

      On top of that, I think that a ‘#’, a ‘##’, and a ‘###’ all generate “big bold text” to some people. They don’t see the advantages of heading, subheading, and so on – so it still presents its share of challenges.

  7. matt

    At we made the markdown choice for our users. I don’t think users want choice for the sake of having it (at least those we build our application for). I think they want something easy to use.
    These users I am talking about have been fighting with , RTE’s, CKEditor, WYMEditor, WhateverEditor for years on a daily basis, trying to figure out how to import this text their boss send them in MS Word etc.. They are kind of tired.

    They only want to write, throw a bold word here, a header there and that’s it.
    And they want their text to play nicely while being copy/paste around.

    Markdown offers this simplicity. It may be not optimal, it may be another syntax scheme after all, but it does a great job.

    Don’t let markdown become a standard ? Okay. But let a standard arises for a”easy to read, easy to write plain text format” then.
    Don’t get me wrong, plurality is good, competition is good but also are standards.

  8. Morten Rand-Hendriksen

    You are spot on Tom. Markdown is like HTML stenography: it’s quicker and easier to write if you know it, but if you don’t know it it just looks like gibberish.

    I love your term “developer goggles” and I’m going to start using it. This is a systemic problem in open source in general I think. Many of the tools built are built for the builders rather than the users and the builders have a vast array of tacit knowledge they unintentionally force on their users by doing things like switching to Markdown. WordPress is popular because of the low entry level user experience. When we start building in developers centric solutions we lessen that user experience and make the tool harder to use for the real user.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑