Markdown
Technology

Wise up to Markdown

James Gordon
James Gordon

If you produce journalism for the web, Markdown was made for you

Markdown is useful for journalists (and anyone who writes for the web) because it’s a reliable, open-source technology with a non-proprietary format. Copy can be written and edited once and then disseminated through multiple websites, mobile apps, etc. For example, if you were interested in publishing your Markdown-based content on Apple News, check out these docs.

What is Markdown

All web copy is published in HTML, but practically no one writes or edits web copy in HTML.

HTML is a markup language designed for annotating content, not writing it. Web page authors use its extensive syntax to encode structural semantics into their content so web browsers render it properly. But for most of us, all those tags and attributes are just distracting cruft.

Rich text editors (RTEs), like the one built into your content management system, hide HTML behind a “what-you-see-is-what-you-get” (WYSIWYG) text editing area with point-and-click formatting options. They often look nice on the surface, but online RTEs have a bad reputation for mangling content and providing subpar user experiences.

A promising new class of online RTEs (e.g., Quill, Trix, CKEditor and Editor.js) have come along in the past five years. However, an even older technology, Markdown, has proven to be a reliable alternative approach to writing for the web.

Even if you’ve never heard of Markdown, you’ve probably encountered it. Those special characters for formatting text in posts on Slack, GitHub and StackOverflow? That syntax is Markdown (or at least Markdown-inspired).

Markdown is two things.

First, Markdown is a plain text formatting syntax that supports a subset of the semantic elements in the HTML standard, including headers, paragraphs, lists and links. Instead of tags and attributes, Markdown has less obtrusive special characters for annotating plain text. That’s why Markdown is often described as a “lightweight” markup language.

In addition to being a syntax, Markdown is also software (originally written in Perl) that converts Markdown-annotated plain text to HTML. And because Markdown compiles to semantic HTML, without any inline styling, the content is portable to different content management systems. In fact, some content management systems (e.g., Ghost, Grav, Pico and Hugo) rely on Markdown documents to generate static websites that are simple to implement and blazingly fast.

Here’s what Markdown looks like in the raw:

## Heading 1

This is a *paragraph* (with emphasis). Notice how, in Markdown, there's no annotation, but in HTML it is wrapped in opening and closing `<p>` tags.

## Heading 2

1. This is the first item of a list
2. This is the second.
3. You can also do [unordered lists](https://www.markdownguide.org/basic-syntax/#unordered-lists).
4. And that's how you do a link

For comparison, here’s the same text in HTML:

<h2>Heading 1</h2>

<p>This is a <em>paragraph</em> (with emphasis). Notice how, in Markdown, there's no annotation, but in HTML it is wrapped in opening and closing <p> tags.</p>

<h2>Heading 2</h2>

<ol>
<li>This is the first item of a list</li>
<li>This is the second.</li>
<li>You can also do <a href="https://www.markdownguide.org/basic-syntax/#unordered-lists">unordered lists</a>.</li>
<li>And that's how you do a link</li>
</ol>

Notice the difference in readability? The free online Markdown Guide has a more comprehensive tour of Markdown’s basic and extended syntaxes.

Desktop Markdown editors

You can write and read Markdown in any text editor, including the one that came pre-installed on your laptop.

For a more pleasant editing experience, here are some examples of popular desktop editors

Collaborative online Markdown editors

The tools mentioned in the previous section provide great, distraction-free, writing experiences. However, a lot of the docs we create require feedback and edits from multiple members of our team.

These tools add collaborative editing and versioning features:

Live collaboration on Desktop text editors

The killer feature for Google Docs is live collaborative editing, which allows multiple users to edit the same document simultaneously.

Yet Google Docs, like the word processors that preceded it, is designed more for crafting print documents, not web documents. So the path from Google Docs to your website isn’t simple or clear. Though, there are some browser plug-ins and web apps that try to help.

These text editor extensions allow live collaborative editing:

Comments

Comments are closed.