Tired of reformatting documents for your website or your blog? Maybe you don’t want to have to learn how to use another online text editor just to write a post. Then use Markdown to write your web pages.
Do you write for the web? Do you post to any of these?
- a static HTML site
- a WordPress blog
- Medium
- any other online platform
If you do, wouldn’t it be great to be able to create well-formatted web pages without having to learn how to use a bunch of different online editors?
Enough with the reformatting — I just want to write a web post
Have you ever converted a file that you wrote using your favorite word processor, like Microsoft Word or Google Docs, only to discover that your new page won’t format correctly on your website?
Maybe you looked at the HTML code and discovered a bunch of formatting tags all over the place that you never added in the first place?
No problem, you say, as long as it looks OK, I don’t care about all the extra formatting. The problem is, all of these extra formatting tags increase the size of your page, which slows down the performance of your site.
Also, if your page has extra formatting embedded in it, the page might look fine on your computer’s browser, but might turn into a hot mess when you display it on a mobile device with a smaller screen.
Maybe you manage a WordPress site and one of your writers sent you a Word or Google doc — now you want to post it, but when you convert it to HTML you get a massive file full of formatting tags.
Even worse, now the new page doesn’t look like any other page on your site. Instead of pressing Publish, you need to spend hours reformatting the page to make it consistent with the rest of the site … and there’s still that one section that won’t format the right way.
All of these problems stem from the same cause: most major word processors embed all kinds of specialized formatting tags into the HTML documents they produce.
If your ultimate goal is to post your document to a web page, these custom formatting tags are a nightmare to clean up. In fact, for Microsoft Word, this type of reformatting is such a problem that there are countless specialized sites that will convert your Word documents to “clean” HTML.
But why add an extra step when you don’t have to do that? If you want to publish new content frequently, every extra step in your workflow makes it more difficult to finish a new post.
Too many formatting choices
Another problem with using word processors to create web pages is this: the typical word processor presents many formatting options that simply don’t exisit in HTML, or are very difficult to reproduce.
For example, you may specify certain type faces and sizes (fonts) in your Word document, only to find out that they simply don’t match any of the typefaces you’re using on the website where you want to publish.
What if you could use a simple text editor, like vim, to write all of your documents, and format them in a way that would produce clean HTML? That way you didn’t have slog through a huge checklist of steps just to convert the document to HTML, and then have to convert it again to clean up the HTML.
That’s why I use Markdown to compose all of my articles and documents I want to publish on the web.
I can create Markdown files in any text editor or word processor, and save the file as a simple text file — usually, with the .txt extension, but I’ll use the .md extension if it’s formatted with Markdown.
In either case, the file contains only text (letters, numbers, punctuation) with no special or proprietary formatting codes or tags.
Your blog may already know Markdown
Most blogging platforms, like WordPress, will format your Markdown document if you just paste it in to the editor.
For instance, you can type or paste Markdown directly into the WordPress editors (Classic or Gutenberg) to format your text, without having to take a special trip to the toolbar with your mouse to create, say, a bullet list.
If your favorite blogging platform won’t read Markdown directly, there are plenty of free tools to convert your Markdown file to clean HTML, without introducing any extra formatting tags into your document.
Keep your fingers on the keyboard: use Markdown to write web pages
After I learned how to compose in Markdown, it became the easiest way for me to write web pages.
Why? Because I can keep my fingers on the keyboard, and just type.
If I want to format some text — say, to make the text bold, or a level 2 heading, or to create a bullet list — I don’t have to take my hands off the keyboard and move the mouse up to some toolbar, after I select the text.
I don’t have to memorize a different set of keyboard commands to format the same kind of headings in different online editors.
And I don’t have to remember to press the Command key if I’m on a Mac or the Ctrl key if I’m on a Windows or Linux computer.
I just type.
That’s because Markdown is basically a way to format text by typing in simple, easy-to-remember characters.
In fact, you may already be using a form of Markdown if you’re using Slack or Discord, or other online chat tools that support simple formatting.
How does Markdown work?
The best way to understand how Markdown works is to see it in action. Let’s take a look at some simple Markdown formatting.
For example, if you want to make text bold, you simply surround it with two asterisks, like this:
here's some **bold text**!That text will look like this on your blog:
here’s some bold text!
Italics is even easier:
let's make _this text_ italic!That Markdown text will appear like this:
let’s make this text italic!
You can easily create blockquotes:
> Just add an angle bracket at the beginning to make a blockquote.That Markdown text looks like this:
Just add an angle bracket at the beginning to make a blockquote.
See? It’s simple.
If you want to get started with Markdown, check out the open source (and free) Markdown Guide.
Keep it simple
Another handy thing about Markdown: it’s designed to be “human-readable.” That means you can read the original Markdown document and figure out the formatting — you don’t even have to convert it to HTML to understand how it’s formatted.
Markdown formatting is, of course, limited. That’s the whole point. You won’t be tempted to do any excessive formatting in Markdown. You (or your webmaster) should be implementing all of your site’s formatting using CSS anyway, instead of using the embedded <span> tags that so many word processors insert.
Use Markdown to write web pages: structure, don’t format, your documents
When you Markdown to write web pages, you have to focus on the structure of the document, not the appearance. This is how HTML was designed to be used: HTML files should contain only the document’s text and its structure, and CSS should contain all the document’s formatting.
In other words, you can use Markdown to define headers, lists, hyperlinks, blockquotes and even boldface or italic text (the document’s structure) but not to define the colors, fonts, text or margin sizes, or any of the the document’s formatting — all of that formatting belongs in your site’s CSS files.
A well-structured web page is easier to read and understand, and this in turn improves your SEO. Separating your pages’ structure and formatting makes it easier to update the appearance of your site, too. Using Markdown to write your web pages helps you achieve these goals, and makes it easier to publish clean, fast-loading HTML, which also improves your search engine rankings.
To learn more about the development of Markdown, check out the Markdown page on Wikipedia that describes the history and various implementations of the Markdown syntax, plus the many software libraries available.