10 Markdown Best Practices

Markdown is a simple and easy-to-use syntax for formatting text. It’s a popular choice for developers and writers who want to write in a plain text format that can be easily converted to HTML.

While Markdown is a great way to write formatted text, there are a few best practices to follow to make sure your Markdown documents are well-formed and easy to read. In this article, we’ll share 10 Markdown best practices that will help you get the most out of this simple syntax.

1. Use Markdown for everything

When you use Markdown for everything, you create a consistent experience for yourself and for others. For example, if you’re creating a README file for a project, you can use Markdown to format the file so it’s easy to read. Then, when someone else needs to update the file, they can do so without having to learn a new markup language.

Markdown is also easy to learn and use, which means you can start using it right away. There’s no need to spend hours learning how to use a complicated markup language.

Finally, Markdown is portable, which means you can use it on any platform. Whether you’re working on a Windows, Mac, or Linux machine, you can use Markdown to format your files.

2. Keep your headings consistent

When someone is skimming through a document, they will use the headings to quickly get an idea of what the document is about. If the headings are all over the place, it will be difficult for the reader to follow along.

It’s important to have a consistent structure to your headings so that readers can easily scan the document and find the information they’re looking for.

Here are some tips for keeping your headings consistent:

– Use the same number of # symbols for each heading level
– Use the same style for each heading level (e.g., all h1 headings should be in bold)
– Keep the headings in the same order throughout the document

3. Don’t use too many levels of heading

When you use too many heading levels, it can make your document look cluttered and difficult to read. It can also be confusing for readers because they might not know which heading level is most important.

Stick to using two or three levels of headings in your documents. This will make your document more organized and easier to read.

4. Write short paragraphs

When you’re writing in plain text, there are no visual cues to break up your content into manageable chunks. This can make long blocks of text difficult to read and digest.

Short paragraphs help to overcome this by breaking up your content into small, bite-sized pieces. This makes it much easier for readers to scan and skim through your content, and helps to keep them engaged.

So, when writing in markdown, aim to keep your paragraphs short – no more than a few sentences each. And if you find yourself with a longer block of text, consider breaking it up into multiple smaller paragraphs.

5. Break up long lists with subheadings

When you have a long list, it can be difficult to scan and find the information you’re looking for. By breaking the list up into smaller sections with subheadings, you can make it much easier for readers to quickly find what they’re looking for.

Not only that, but by using subheadings, you can also make your lists more visually appealing and easy to read. When done correctly, subheadings can act as mini headlines that help guide readers through your content.

So, if you have a long list that you want to format in Markdown, consider breaking it up into smaller sections with subheadings. It will make it much easier for readers to scan and find the information they’re looking for, and it will also make your content more visually appealing.

6. Make links descriptive

When you’re writing in Markdown, the goal is to make your content as easy to read and understand as possible. This means that links should be clear and descriptive so that readers know where they’re going to be taken when they click on them.

Links that are just a URL or an IP address are not only difficult to understand, but they can also be long and cumbersome. Descriptive links, on the other hand, are much easier to understand and provide context for the reader.

Here’s an example of a link that is just a URL:

https://www.google.com

And here’s an example of a link that is descriptive:

Google Search Engine

7. Link to other pages on your site

When you link to other pages on your site, you’re essentially creating a web of interconnected content that’s easy for both users and search engines to navigate. Not only does this make your site more user-friendly, but it also helps boost your SEO by giving search engines more opportunities to crawl and index your content.

To create a link in Markdown, simply enclose the text you want to link in square brackets [ ] and then follow it with the URL you want to link to in parentheses ( ). For example, if you wanted to link to our home page, you would use the following code:

[WebFX](https://www.webfx.com/)

You can also add title attributes to your links by adding the title in quotes after the URL. Title attributes are important because they give users additional information about where the link will take them. They also help improve your click-through rate (CTR) because they give users a preview of what they’ll find on the linked page.

Here’s an example of how to add a title attribute to a link:

[WebFX](https://www.webfx.com/ “A Full-Service Digital Marketing Agency”)

8. Avoid using HTML in Markdown files

When Markdown is rendered, the HTML is rendered along with it. This can lead to problems if the HTML is not well-formed, or if it doesn’t render as intended.

It’s also important to avoid using HTML in Markdown files because it can make the Markdown file difficult to read. If you need to use HTML in a Markdown file, consider using a code block instead.

9. Add a table of contents

A table of contents allows your readers to quickly and easily navigate your document. It’s especially important for long documents, or documents with a lot of sections.

Adding a table of contents is simple. Just add a line that says “Table of Contents” (or something similar), followed by a list of the sections in your document. Make sure to use headings so that the table of contents is generated automatically.

Here’s an example:

Table of Contents

1. Introduction
2. Section 1
3. Section 2
4. Conclusion

By following this markdown best practice, you’ll make it easier for your readers to find the information they’re looking for, and you’ll make your document more user-friendly overall.

10. Use images sparingly

Images are often much larger files than text, which can make pages load slowly. In addition, images can be a distraction from the main content on the page. Too many images can make a page feel cluttered and overwhelming.

Of course, there are times when an image is the best way to convey a message or provide information. When using images, keep them small and relevant to the text around them. Use alt text to describe the image for those who may not be able to see it. And always think about whether an image is really necessary before adding it to your markdown document.