Common Markdown Errors

By soyernesto | Curious Nook | 4 Jan 2025


Markdown is a lightweight markup language used to format text easily, allowing you to convert text to HTML format to facilitate the creation of documents, blogs, and it is widely used on many platforms. Especially for new users, a series of difficulties can arise when learning this language, mainly due to the importance of each character, including spaces. It is important to gradually familiarize yourself with the syntax and incorporate each character and resource to work efficiently.

Today I want to make a small compilation of the most common mistakes for people who are starting to use Markdown. This article is not intended to be a Markdown guide. Assuming you have already faced this format, I will analyze common mistakes and some best practices.

1. Headers

Headers help us organize our texts, allowing us to create hierarchies and facilitating navigation for users. It is also a very important SEO best practice, helping search engines classify our content. Headers are created using the # symbol followed by a space and then the header text. Adding more # symbols will decrease the header level within the text.

If you don’t leave a space after the #, the text will not render as a header (it won’t be bold and larger). Instead, it will create a tag.

Incorrect

#This is not a Header

It looks like this:

#This is not a Header

Correct

# This is a Header

It looks like this:

This is a Header

2. Links

To create links in Markdown, use brackets [] for the link text (the text that the user will see in our article) and parentheses () for the URL. If you don’t close the parentheses, the link won’t work. You should always correctly close the brackets and parentheses.

Including alternative texts for our links is a very good practice, giving a more professional image to our articles, providing our readers with greater accessibility and a closer user experience.

Incorrect

It looks like this:

Correct

Google

It looks like this: Google

3. Paragraphs

When creating paragraphs, a very good practice is to leave a blank line between each paragraph. If you don’t leave this line, each paragraph will be joined to the previous one. These joined blocks are extremely difficult for our readers and make our texts look longer and uncomfortable to read.

Incorrect

This is the first paragraph.
This is the second paragraph.

It looks like this:

This is the first paragraph. This is the second paragraph.

Correct

This is the first paragraph.

This is the second paragraph.

It looks like this:

This is the first paragraph.

This is the second paragraph.

4. Lists

There are two main types of lists: ordered and unordered. To create unordered lists, you can use an asterisk *. If you want your list to show an order, use a number followed by a period 1. and a space before the list item text. This space after the period or asterisk is very important; if you don’t leave a space, the list won’t display correctly.

Example

Unordered list:

* pineapple
* strawberry
* mango
* grape

Ordered list:

1. First
2. Second
3. Third
4. Fourth

It looks like this:

Unordered list:

  • pineapple
  • strawberry
  • mango
  • grape

Ordered list:

  1. First
  2. Second
  3. Third
  4. Fourth

5. Alternative Text for Images

Unlike links, images in Markdown are inserted using an exclamation mark ! followed by brackets [] for the alternative text and parentheses () for the image URL. If you don’t close the parentheses, the image won’t display.

It is very important to always include this alternative text whenever possible. It will not only improve the SEO of our article (it is used to index our pages), but it can also be very helpful for visually impaired people. It will also allow the alternative text to be displayed in case of loading errors, making it easier to understand our article.

!Image of a grape

6. Code Blocks

When we want to display code snippets clearly and distinctly from the rest of the text, it is necessary to use three backticks (`). If we want to display a single character instead, we simply enclose it between one backtick.

It is very important to display the original format of a text correctly without interpreting special characters. Additionally, many editors interpret different programming languages, highlighting syntax and keywords for better reading and understanding. You can see an example of this throughout this article where I have been using it to represent examples.

7. Special Characters

As I mentioned earlier, knowing special characters will save us more than one headache and formatting issues. It takes time to familiarize yourself, but it is not impossible. Characters like asterisks * play an important role. If you want to display it in your text, you have to “escape” it by using a backslash .

Incorrect

* this is an asterisk

It looks like this:

  • this is an asterisk

Correct

\* this is an asterisk

It looks like this:

  • this is an asterisk

8. Quotes

Quotes highlight texts in our article and have many uses. We can use them to emphasize information, whether they are textual quotes, references, comments, or contextual information. Additionally, different viewers usually add a different style to the text, which can help us improve the style of our article, making it more attractive and easier to read. To create quotes in Markdown, use the > symbol at the beginning of the line. It is very important to leave a blank line at the end of the quote to start the next paragraph.

Incorrect

> This is a quote.
This is NOT a quote

It looks like this:

This is a quote. This is NOT a quote

Correct

> This is a quote.

This is NOT a quote

It looks like this:

This is a quote.

This is NOT a quote

Final Recommendations

My main recommendation is to practice daily. Start by creating simple documents and add layers of complexity using different formats. Online, you can find many resources, guides, and tutorials that range from the most basic concepts to the most advanced. Use split-screen text editors to see how your texts take shape as you write. My favorites are GitHub and Obsidian, but there are many options available. It is also very useful at first to create your own templates or code snippets with different formats. I hope these tips are helpful, and don’t worry about making one of these mistakes; practice makes perfect.

I sincerely want to thank you for taking the time to read this article. Your support means a lot to me and motivates me to continue sharing content that can be useful and interesting for you. If you found this article useful or enjoyed reading it, I would greatly appreciate your comments. Best of luck.

 

Image by <a href="https://pixabay.com/users/mohamed_hassan-5229782/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6641731">Mohamed Hassan</a> from <a href="https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6641731">Pixabay</a>

 

Article first published on my personal blog at HIVE.

You can access my work at OBJKT and explore my gallery. OBJKT
I regularly generate royalty-free content for Pixabay; you can find all the links on my social media. Pixabay

All other resources have been obtained from the HIVEREMESAS bot, or are screenshots taken during its use.

 

 

How do you rate this article?

1


soyernesto
soyernesto

Passionate about art and writing. Always learning, always growing. Excited to share and learn more every day!


Curious Nook
Curious Nook

Welcome to Curious Nook, a corner where curiosity knows no bounds. Explore a diverse collection of topics, from the wonders of science and the intricacies of art to everyday life hacks and interesting reflections. Each visit promises something new and intriguing. Join me in exploring the world from different perspectives.

Send a $0.01 microtip in crypto to the author, and earn yourself as you read!

20% to author / 80% to me.
We pay the tips from our rewards pool.