How to use Markdown to markup text in start.me: Part 2

How to use Markdown to markup text in start.me: Part 2

Some time ago, we posted a blog about marking up your bookmarks and notes widgets with 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 terrible thing. There is just a lot of information people must 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 essential information is not missed, using proper markup is essential. And it turns out bulleted lists are a highly effective reading aid.

Using Markdown, it is 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 on the list on a separate line. By starting every line with a dash (-) or an 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

Similarly, 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 (.). You mustn’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 necessary. If you would start every line with 1, Markdown still recognizes the list and will automatically number your items.

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 their 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 sign 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 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).

To be continued

Using these more advanced formatting techniques, you can make the texts in your Notes widgets more legible. They work for bookmark block headers and bookmark descriptions as well. Try it. 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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

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 ➔