Markdown Good Practices: Best way to format your post

Many of you use MarkDown to write on Hive and it's great (I love MarkDown). But did you know you can avoid display error between Ecency, Hive.Blog, PeakD or your favorite front-end just by format your post correctly?

It's not a tutorial on "How to write with MarkDown". You can use any search engine to find one (Many tutorials are in your language on HIVE and on the web). This post is more list a collections of good practices to avoid mistakes.

Let's have a look at some rules to know to have beautiful articles, everywhere.

Global

All these rules are document-wide:

No trailing spaces

Please, remove trailing spaces at the end of the lines. If you leave two trailing spaces at the end, it's like a line-break. Did you know that?

MarkDown and HTML

As you know, MarkDown allow the use of HTML tags for compatibility, but please, avoid HTML. Each Hive front-ends can use that they want and the result can be altered.

I try to only use the <center> tag for center an image because there is no alternative in MarkDown.

No consecutive blank lines

When you make more than one blank lines, it only makes the post heavier but no display changes. So, please, avoid two or three consecutives blank lines.

Consistent emphasis

When you use emphasis, keep them consistent. If you use **bold text**, try to use the same for every emphasis but don't change the style with __bold text__. It will produce the same result but it use most system resources to be parsed.

Also, remove trailing space between symbols and text. It really faster to parse. E.g : don't use ** Bold text ** but remove trailing spaces: **Bold Text**. Do you see the difference?

---

Titles

Some rules are specific to Titles. When you write your content in MarkDown, titles start with hashes. If you need a third-level title, it's ### Third-level good title, and you can have maximum 6 levels. This notation MUST be used to create titles, not to have bold text.

Start

Every title must start at the beginning of the line. No spaces or tabs are allowed before any titles. It can generate some display errors.

Don't use only one hash for your first title, it's already reserved for your post title, so, please start with two hashes titles.

Last thing about start: put a space between hashes and title content, e.g.: ## A good title.

No similar content

In general, titles must be uniques and cannot be the same. With Hive, some front-ends use titles to a table of contents, and it's really painful to see identical titles without differences.

No emphasis in titles

Some markdown parsers don't understand the emphasis (bold or italic) in titles and generate display errors. Prefer to put a clean title and emphasis in words of your paragraphs.

One time, a friend ask me: "Did you already see emphasis in titles when you read a book?". He's right, i never see that.

Also, some users use bold emphasis instead of title. It's correct but really bad for search-engine optimisation. Please use title for that.

---

Links

To build a link, it's not difficult: [Text for the link](https://the_URL.com) but don't forget some good practices:

No empty text or link

Brackets first, parenthesis after but text in them! NEVER write text without link or link without text. The result is... really bad and vary between front-ends.

Don't forget to remove trailing spaces surrounding text or URL.

For bare URL (same text and URL), don't forget to surround text with angle brackets. E.g.: [<https://google.com>](https://google.com). The result is more readable for users.

If you have many links to the same resource, please use the same text too. It's really better for SEO and for parser speed.

---

Blockquotes

Blockquotes are used to write... quotes. But don't forget how to do that:

To do a blockquote start the line with > symbol. Don't forget to add only one space between the symbol and the blockquote.

If the quote is long, you can add a trailing > to break the line.

Good example:

“We cannot solve problems with the kind of thinking we employed when we came up with them.”

Albert Einstein

Code:

> “We cannot solve problems with the kind of thinking we employed when we came up with them.”
> 
> Albert Einstein

If you have two differents quotes, please, prefer to separate them by a small text if you can.

---

Lists

Each list MUST be surrounded by blank lines. It's the best for readability and SEO. Parsers can also have problems if you don't do that.

Also, start each item with a symbol + space before text.

Unordered lists

For the unordered list, please be consistent with the symbol. Use the same for each list in your post.

If you use sublist, please indent each level with two spaces.

Example of good unordered list:

* first item
* second item
  * First item of sublist
  * Second item of sublist
* third item

Ordered lists

Like unordered lists, please be consistent with symbols. The best use is "1." but users can also use "1)".

Every ordered list must start with "1" and must be incremental. You can prefix your list with "0" if you have more than 10 items.

Example of good ordered list:

1. First item
2. Second item
  1. First item of sublist
  2. Second item of sublist
3. Third item

---

Images

About Images, in MarkDown, it's quite simple: ![Alternate text of the image](https://the_URL_of_the-image.com/image.jpg)

There is only two things to know, but they are very important

• Alt text and link MUST not be empty,
• No spaces surrounded alt text & image link.

If you do that, you will have the best SEO and parser speed with images.

---

Conclusion

With these rules, Your post will be beautiful in any HIVE front-ends. If you want to learn and practice markdown, you can check the ComonMark tutorial, it is really useful and quite easy.

As usual, if you have some questions or feedbacks, just add comment on this post. If you like my work and want to support, You can Upvote and/or reblog and share this post.

---

Images credits :

• Markdown flavors logo by CSSTricks,
• Blogging woman image by Pexels from [Pixabay](https://pixabay.com/fr//?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=1851464