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:
- First
- Second
- Third
- 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.