Markdown for Developers

One of my guiding principles as a developer is that our ability to communicate is one of the most important tools we developers have in our toolbox. There are lots of ways we communicate with others in code, documentation, and blog posts. What we need is a way to write our documentation that can be easily created, edited, revisited, and because we’re developers kept in source control.

Markdown provides us with a way to do all of this and more.

What is Markdown?

At its core, Markdown is a lightweight markup language that provides a simple formatting syntax for converting plain text into formatted text. Using the correct tools, we can use it to create websites, documents, and even emails. John Gruber created Markdown in 2004 to make writing easier, and it has become one of the world’s most popular markup languages.

Markdown allows us to take Markdown-formatted text and run it through a processor to create formatted text. Generally, the output is HTML, but because we’re just working with plain text that has formatting rules set in, nothing is preventing us from converting it to a wide variety of formats.

Why Use Markdown

In a word processing application, we click buttons to format words, and the changes are immediately shown to us. Markdown operates differently. When we’re working on a Markdown-formatted file we add Markdown syntax to the text to indicate which words should be formatted based on the Markdown rules.

Because it’s so easy to use Markdown, the tools we use every day have built-in support for it, and we may not even know. For example, most IDEs now have support to edit a Markdown file and view a formatted version of it as we type. They also have support for keyboard shortcuts to help format the document. I write all my blog posts and articles in Markdown and then use the built-in preview to see what it will look like. A ton of websites also support it for basic text entry and then display the HTML output of the text we’ve entered. Some famous examples include GitHub and Reddit.

Because we’re working with just a text file with extra characters added to show the formatting, the files are incredibly small and can be opened by any free or open-source text editor.

It can take a little getting used to seeing Markdown syntax in files but once you get the hang of the minimal formatting rules you’ll be able to read Markdown formatted documents without trouble. The rules were created so a Markdown-formatted document could be published as-is in plain text. This makes Markdown formatted text easy to read and understand even if your reader doesn’t know what Markdown is.

Formatting Basics

Let’s get into the basics of formatting a document. If you want to follow along you just need to create a “.md” file and open it in your favorite text editor. I’m using a scratch Markdown file in PHPStorm with the live preview enabled.

Paragraphs

To create a paragraph we just need to separate one or more lines of text with a blank line.

Paragraph 1

Paragraph 2

This generates the following:

Paragraph 1

Paragraph 2

If you need to force a return line inside a paragraph end the line with two or more spaces and then add a return.

Paragraph with returnline  
return

This generates the following:
Paragraph with return line
return

Headers

To create headers inside of our text (H1, H2, H3, etc) we add a number sign (#) in front of the text that we want to be the heading. The quantity of number signs corresponds to the heading level. For example, to create an <h1> element, we would use one number sign “#,” and to create an <h2> element, we would use two.

# H1
## H2

Emphasis

We can emphasize our text by making it bold, italicized, or bold and italicized by wrapping it in one, two, or three asterisks or underscores, respectively.

*bold*
__italic__
***both***

This generates the following:
bold
italic
both

Direct HTML

Because we’re using Markdown to generate what generally becomes HTML, we can write HTML in our Markdown-styled document, and it will ” pass through” into the output.

<a href="https://scott.keck-warren.com">a link in HTML</a>

There are some potential downsides to this as the processor may not support HTML directly so the output might look funny. I’ve seen this less and less over the years, but it’s still a potential downside, especially if our output isn’t direct HTML.

Code

We have a couple of options with Markdown to display the code.

To format code inside a paragraph we can wrap the code with backticks (`) so it will be displayed as code.

This text refers to `mb_strstr()`

This generates the following:
This text refers to mb_strstr()

We can also create code blocks by either putting four (4) spaces before each line of our code.

    class Scott {
        public function __construct() {}  
    }  

Or by wrapping the text in three backticks (“`)

```
class Scott {
    public function __construct() {}  
}  
```

These both generate the following:

class Scott {
    public function __construct() {}  
}  

In some versions of Markdown (we’ll discuss this later) we can include the language the code is from and it will give us syntax highlighting.

```php
class Scott {
    public function __construct() {}  
}  
```

class Scott {
    public function __construct() {}  
}  

Special Characters

Because we’re developers a lot of what we write uses the special characters that Markdown requires to do its formatting. It generally does a good job of allowing this to work but we’re going to run into situations where we need to use the special characters in unexpected ways.

For example, I may need to use the backtick character (`) twice in one sentence. I can safely use it once but as soon as I use it a second time the Markdown rules will convert it to a code snippet.

This sentence uses backticks (`) twice which messes up its formatting because we're using two backticks (`).

This sentence uses backticks () twice which messes up its formatting because we're using two backticks ().

To get around this, we can use the backslash () to display it correctly.

This sentence uses backticks (\`) twice which messes up its formatting because we're using two backticks (\`).

This sentence uses backticks (`) twice, which messes up its formatting because we’re using two backticks (`).

Blockquotes

We may need to quote something in our Markdown document and to do so we add a greater than sign (>) in front of the paragraph.

> Don't Worry Be Happy 

Don’t Worry Be Happy

A weird thing about blockquotes is that they can contain other Markdown formatting elements, but not all of them, depending on the application you’re using, so you may need to experiment to see what works.

Lists

We can create both ordered (with numbers) and unordered (without) lists in Markdown.

Ordered lists are created by adding numbers followed by a period at the start of a line. The numbers don’t have to be in numerical order but it’s easier to maintain if they do.

1. Line item 1
1. Line item 2

This generates the following:

1. Line item 1
2. Line item 2

Unordered lists are created by adding asterisks (*), plus signs (+), or dashes (-) at the start of the line. I usually use asterisks because they more closely resemble the output.

* Line item 1
* Line item 2

This generates the following:

• Line item 1
• Line item 2

Links

There are three ways we can add links to our Markdown-formatted documents

The first option is to enclose the link text in brackets and then follow it immediately with the URL in parentheses.

[Scott's Homepage](https://scott.keck-warren.com)

Scott’s Homepage

Our next option is to use reference-style links. Reference-style links make URLs easier to display and read in Markdown by breaking the links into two pieces. The first is the part we keep in line with our text and the other is the link which we keep later in the document.

This also makes it cleaner to reuse links as we’re adding them to our document in multiple locations.

[Concurrency With Florian Engelhardt][1]

[1]: https://scott.keck-warren.com/podcasts/2024-12-03-Concurrency%20With%20Florian%20Engelhardt/

Concurrency With Florian Engelhardt

We can also just enclose the link in greater than and less than symbols.

<https://scott.keck-warren.com>

Images

Images can be added by adding an exclamation point, followed by the alt text in square brackets, and then the URL to the image in parentheses.

![Community Corner Podcast Logo](https://scott.keck-warren.com/assets/img/Community-Corner-Logo-500x500.png)

Variations

One of the more annoying parts about Markdown is that practically every tool and application that supports Markdown may implement a slightly different “flavor” of Markdown. Generally, every flavor supports all of the features that we’ve discussed so far, but they may include additional formatting options such as tables, task lists, math, and my favorite Mermaid support. Unfortunately, you may have to play around with the application you’re using to figure them all out but they generally provide some kind of a cheetsheet to understand it.

In Our Applications

As developers, we can use a library to provide Markdown to HTML support for our users using a wide variety of libraries and then add our additional formatting options on top. For example, in an application I support, we allow users to enter information into a textbox that, after it’s saved, gets displayed as HTML using the League\CommonMark library. We then extend it to allow us to add specially formatted sections when there’s a link to other sections of our website.

Other Places

A lot of the development tools we already use most likely have support for Markdown and we may not even realize it. GitHub has its special version that we can use wherever we have comments and some WYSIWYG applications will allow you to type in Markdown and automatically convert it to its internal formatting.

What You Need to Know

1. Markdown is a formatting syntax for text documents
2. Easy to read and easy to write
3. Can be used in web applications when users enter text