Using markdown to markup bookmarks and pages: Part 2 – Bullets and headings

Using markdown to markup bookmarks and pages: Part 2 – Bullets and headings

Some time ago, we posted a blog about marking up your bookmarks and pages using Markdown. That blog covered the basics, such as making text bold and using a fixed width font. In this second blog, we will continue to explore the possibilities of Markdown. We will show you how you can make use markup to enhance your pages with bulleted lists and headings.

Creating bulleted lists

It turns out, most people are very lazy when it comes to reading text from a screen. That’s not necessarily a bad thing. There is just a lot of information people have to process every day and being lazy helps to keep things manageable. So people read what they need to read and will hardly ever finish an article. To make sure important information is not missed, using proper markup is essential. And it turns out bulleted lists are a very effective reading aid.

Using Markdown, it is really simple to create bulleted lists. A good example of a place where bulleted lists work well is in the Notes widget. But bulleted lists will work in bookmark block headers and bookmark descriptions as well. So feel free to experiment!

So, to create a bulleted list, just put every item in the list on a separate line. By starting every line with a dash (-) or asterisk (*), followed by a space, the Markdown processor will automatically turn your list into a bulleted list. It would look something like this:
A notes widget with Markdown formatting to create a bulleted list

* Apples
* Pears
* Bananas

Numbered lists

In a similar way, numbered lists can be created using Markdown. Just start every item on a new line. Instead of a dash or asterisk, you will now start the line with a number, followed by a period (.). It is important you don’t forget to add a space after the period, or the Markdown processor will not recognize your numbered list properly. The list would look like this:
A Notes widget showing a numbered list formatted with Markdown

1. Because!
2. I want it!
3. He does it, too!
4. I will squeeze you!
5. You like me, right?

One interesting thing to note: the Markdown processor will automatically number your items. So even though it will look nicer if you start with 1 and continue the series, that’s not really necessary. If you would start every line with 1, Markdown still recognizes the list and will automatically number your items.

Suggested reading:  A bookmarks block header to add context

Adding subheadings

Another formatting technique that helps to make long texts more readable is the subheading. Subheadings add structure to text. And because subheadings are usually set in a larger font, they are easily recognized. When reading a text, people tend to scan its headings and bulleted lists first. Knowing this, you can help yourself and others navigate the texts in your notes widgets easier.

Subheadings can be added to Notes widgets in two ways: by adding one or two pound signs (#) to the beginning of a line or by underlining lines. The pound signs technique is easiest. Adding a second pound signs to the beginning of the line will create a subheading. Like this:
Notes widget showing heading and subheading formatted with Markdown

# Heading
First paragraph

## Subheading
Second paragraph

The second way to achieve headings is more elaborate but looks ‘nicer’ in the actual Markdown source code. That is why some people prefer this style. And with good reason: Markdown was originally conceived as a markup language that would be both easy to read by users and machines. That’s why most of the markup is really intuitive.

To create headings and subheadings using the underlining technique, put the header on a single line. On the following line, underline the heading using equality signs (=) or dashes (-) to create headings and subheadings respectively. The rendered effect will be the same as what can be achieved with pound signs, but the source code will look a little more legible:

Heading
=======
First paragraph

Subheading
----------
Second paragraph

Please note that, even though it looks nice, you don’t have to use the exact same number of dashes as there are characters in the heading. It is sufficient to use two dashes (or equality signs).

Suggested reading:  How to quickly add multiple bookmarks to your startpage

To be continued

Using these more advanced formatting techiques, you can make the texts in your notes widgets more legible. They work for bookmark block headers and bookmark description as well. Give it a try. Experiment a little and let us know if you have any questions. Soon, we will continue this series with a blog of more advanced formatting options, including inserting hyperlinks and images.

Markdown series

Michiel de Wit

Michiel de Wit

Michiel is CGO and co-founder of start.me. He is a software professional with a lot of experience in developing enterprise grade web applications. He is a certified Scrum Master and a great proponent of modern software development practices.


(It's free and will only take a minute)

Leave a Reply

Subscribe to our blog via email

If you want to stay up-to-date, enter your email address below. You will receive notifications of new posts by email.

Subscribe to our blog ➔