Is HTML better than Markdown? Yes

When we write web content in valid vanilla HTML, the Internet is a far more inclusive product. Only the skill of our writers could change that. In this article I argue to drop Markdown as your primary writing medium and write to, or into HTML.

Comments are open 🙂 

Digital Writing

Digital writing is different to Print. Often described as Writing for UX, digital writing is a craft. Cognitive design is its keystone.

A Content Management System (CMS) is a complicated application: leave its build to the engineers. Writing into WYSIWYG content editors is easy. Sometimes it invites inexpert errors and the abuse of presentation patterns. The most common I encounter are:

• The abuse of heading levels and emphasis for visually biassed design.
• Poor writing style based in the Print Paradigm including:
  • Reading level
  • Verbosity
  • Lack of reader orientation including:
    • Table of contents
    • headings
    • links
    • lists or tables (for data)
    • inappropriate imagery
  • Linear content architecture

These can quickly render our product “non-compliant” with WCAG, or at best disappoint our prospects and customers.

What Is Markdown?

Markdown is a powerfully simple writing syntax favoured by technical writers in the print paradigm. Text copy written in Markdown is easily exported to one or more digital publishing formats. These include ePub, PDF, MS Word, and HTML.

Markdown is useful when writing Open API specifications using YAML files, although YAML also receives vanilla HTML. 

Markdown does not qualify a writer to the digital paradigm. It’s a tool. Digital writing is a skill; a design; a craft. It is not writing for print and then publishing to the web.

Why Use Markdown for Web Content?

When composing copy text, writing in a word processing application works for many of us. We write and update to craft the perfect experience of our copy. Most applications offer structural tagging and editable visual styles from headings to emphasis. The features are not all necessary and can be helpful to outline and confirm structure or to mimic the intended web presentation.

Benefits

Markdown editing applications share many of the same features as any word processor. When writing in the Markdown syntax, there are no ‘styles’ applied – only an encoded intention. A visit to the menu often rewards with a vanilla or basically styled HTML preview of the text.

The benefit of Markdown is that the finished MD file is instantly useful to HTML, PDF, MS Word, ePub, and allied digital outputs. That’s great when publishing to more formats than HTML alone.

It’s challenge is when writing only for HTML: why should our writer cognitively design for HTML and translate to and from MD? It has to increase the mental effort required, which should be directed at our craft.

Writing for CMS

When our content is intended published only on the web and specifically to a CMS then why write with Markdown at all: habit, efficiency, or a fear of HTML?

A CMS may require a middle-software to translate an MD file into HTML. It’s a step that could be avoided by copy and pasting copy from a text editor directly into the CMS’ WYSIWYG editor:

• Benefit. Our writer can review the inclusiveness of the presentation in context of the end-product.
• Drawback. Some refinement may be required at the HTML level.

Abstraction

Markdown-flavoured writers claim a benefit of abstracting content from presentation. I don’t understand this argument. Reviewing our output in the same medium as our visual and non-visual readers is essential to refining the inclusive design and experience of our content.

When writing for HTML output, then writing Markdown clearly replicates HTML syntax used to present. That’s not an abstraction. It’s an equivalence.

Syntax for presentation

The Markdown syntax includes codes for:

• Heading levels 1 to 6
• Paragraphs
• Links
• Ordered and unordered lists
• Tables
• Blockquotes
• Pre texts (code blocks)
• Emphasis
• Image

These are all content presentation strategies. Additional ‘short codes’ may be required for product-specific styling including modal and non-modal card patterns, navigation, and other HTML components.

Why not work with HTML when we can clearly write in Markdown?

Markdown v. real code

Markdown doesn’t feel like real code. Its flexible output to multiple formats is clearly attractive to writers. When those alternative outputs are not required, then perhaps learning HTML appears too much effort?

# Heading Level One

| Header | Two  | Three |
| ------ | ---- | ----- |
| 1+1    | 1+2  | 1+3   |
| 2+1    | 2+2  | 2+3   |
| 3+1    | 3+2  | 3+3   |

Paragraphically correct [link text](https://link.url).
## Heading two

> Blockquote!

```pre, or Code block:
<p>HTML Paragraph text.</p>
```

In my opinion, Markdown is a barrier to inclusive writing for the Web where an abstraction from presentation risks overlooking the requirements of inclusive HTML content strategies. In anycase, Markdown does not abstract content (visual and nonvisual) from semantic presentation design. Writers using Markdown are:

• Designing the content’s semantic
• Specifying presentation.
• Using a code!

Surely, when digital writers can learn Markdown syntax they can learn the equivalent HTML tags? Yes. Should they? Yes, if only to test the final HTML presentation meets their and their readers’ expectations.

When Markdown is Necessary

The great feature I noticed about the free Markdown editors I played with this week is that they can display the Markdown as styled or vanilla HTML output.

Converting HTML to Markdown

It can’t beyond our wit to convert vanilla HTML into Markdown when it is necessary? Default Markdown files (.MD) are not dead, after all.

No! Browserling’s HTML to Markdown editor is online and free.

Summary

I may be influenced by my habitual (if imperfect) understanding and use of inclusive HTML and maintain that digital writing should exploit it. HTML is our medium: not some intermediary Markdown code designed to export to formats we seldom use, or that can be created from HTML. 

My advice?

• Drop the Markdown when output is to HTML documents.
• When possible, paste or write into CMS using WYSIWYG editors and adjust HTML when necessary.
• Learn to write in HTML editors and have engineering create the complicated snippets.
• Have engineering create HTML-based web documents that print beautifully.
• Export HTML to Markdown when needed.

You won’t look back.

Disagree?

Feel free to share your comments. I am always Learning Too, and not as close minded as I write 🙂