The Complete Guide to Blogging in Markdown
If you want to start a blog, you should definitely write in markdown.
Markdown lets you format text by adding annotations as you write. Instead of having to click, highlight, and customize fonts on every part of your writing, you can simply add text annotations on the fly. The result will be a consistent, good-looking piece of content.
And most importantly, using markdown will save you a ton of time.
Here's why and how you should blog with markdown.
Why Markdown?
My favorite thing about markdown is that it is standardized.
That means if you take notes in markdown, you can paste them into your blog editor and the same formatting will work as-is. Also when you republish and post your content on more platforms, if they support markdown then you don't have to scroll through your content and manually format everything again.
In short, here's why markdown is great:
- It's standardized, works across platforms
- Makes your content easy to copy/paste
- Great skill to have for note-taking
- Best way to quickly format any kind of writing
This makes markdown a great tool for more than just blogging, but let's stay focused on blogging for now.
How to Format a Blog With Marking
There are a few things to keep in mind with writing markdown blog posts.
The first is search engine optimization or SEO. The goal of most bloggers is to improve their search presence over time and you will want to make sure you format your blog in a friendly and accessible way for search engines.
Using Image Alt Tags
We want to make sure our images can be interpreted by engines.
This is easy to do with markdown and should look similar to this:
First, we create what resembles a markdown link, square brackets followed by parentheses.
To format this link as an image, we start it with an exclamation point. Then instead of rendering a link, we render the image based on the destination in the parentheses.
Now to make this easy for search engines to read and understand we need to cover specifically what's going on here.
Alt Text
Alt text is an attribute given to HTML images to describe what the image is.
This helps the search engines show the image in a search result since it now has a text description of what the image is. Additionally, screen readers and accessibility tools will be able to understand what the content is intended to illustrate.
Alt text is an important part of search engine optimization and you should always make sure your images have alt tags.
Image Titles
Similarly, a little-known fact is that markdown images can also be given titles.
Inside the parentheses, you can add a second parameter that will be used as the title of the image. Make sure to take advantage of this.
We want to give search engines as much help as we can so they can understand and index our content.
Using Headers Appropriately
Search engines try their best to understand your content.
One of the ways they do this is by reading your headers throughout your content. Notice how each section of this article has a heading and within each section, there are additional subheadings. You should do the same in your articles.
You want to make it as easy as possible for search engines to understand what your content is about, so they can index it and show it to the right people.
When you use markdown headers, you will probably use the # format. That works like this:
# Title of the post
One # results in an H1 tag, and there should only be 1 H1 tag per page.
## First Section
This will result in an H2 tag. You can have multiple of these
### Subsection
These create H3 tags, and so on.
For accessibility reasons, it's best not to skip around too much. Screen readers and other accessibility tools work best when your sections are ordered and nested under larger headers.
As a rule of thumb, don't use H1 tags these are reserved for the title of your post. Search engines generally want to see just one to understand the main theme of your content.
Use H2 tags or ## Double Hashtags to create major sections in your content.
Escalate down with H3 tags within these blocks of content and so on.
Working With Links
When we add links to our posts, it's important that we build them correctly.
Search engines are capable of reading links in plain text (such as this https://testsuite.io). But that's less than idea for both the user and search engine crawlers (notice too, links should result in legitimate HTML anchor tags with HREF attributes).
This tells search engines what this link is for, and how you want it to be treated.
In markdown, links are created like this:
[How to Learn Markdown](https://testsuite.io/learn-markdown)
That will result in this: How to Learn Markdown
Links are a complicated topic and we could spend hours talking about the specifics. Follow vs No-follow links, canonical links, anchor links within the same page. All good things to know about.
But for starters, just make sure your blog posts use real hypertext links.
Bonus Tips
Line breaks can help organize your content.
I use them to separate sections when I've reached the end of one idea and want to dive into something new. Line breaks prepare the reader for a cognitive reset, or in other words, they help people understand that we're going to introduce a new topic or idea in the next section.
Most of the major platforms and editing tools that support markdown will support line breaks, so take advantage of them.
The point of writing a blog post is to help share information with a reader.
Format your content in a way that helps them understand what you are trying to convey. This will help you help the reader.
And markdown is a tool that you should definitely use to make it easier for you to create beautiful, understandable content.