Introduction to Markdown

Markdown is a way to write texts, mostly for the internet, that is easy to read and write in a text file and can easily be transformed into html. It can also be transformed into PDF or other document formats. But mostly for websites.

Often it is used in web forms as an alternative to the previously more popular BBCode format. Websites and blogs often allow comments and answers to be written in markdown format. Because implementing the frontend is easy. It can be a simple textarea. In the backend, almost every environment, if it is node.js, php, ruby or any other kind of server, there are modules today, to easily transform markdown formatted text into HTML.

That is because the markdown format is very simple, and translates well into html elements. With some extensions, it can be adjusted for more use cases, such as describing tables, source code snippets, SVG images and more.

Basic Elements of the markdown syntax

Some markdown syntax is universal to almost all markdown compilers.

Formatting a Paragraph in Markdown

To format a text into multiple paragraphs, you just hit two times enter into your text. That makes an empty line in your text file and in html it get translated into <p> tags.

Here is some text.

Some more text in a second paragraph.

The output of this code will look like the following:

<p>Here is some text.</p>
<p>Some more text in a second paragraph.</p>

Note: In the html output, I wrote the two paragraphs on two lines. Each compiler can decide to generate more pretty or more minified html. Some even have options to control the white spaces.

headlines in MD

Markdown is often stored in .md md files or is called md. Headlines are marked with a leading hashtag on a new line. Headlines for sub paragraphs can be marked with multiple tags. Using css this is then often displayed a little smaller. If there is only one # character, it will be translated into the highest order headline.

# headline
## second level A
## second level B

HTML:

<h1>headline</h1>
<h2>second level A</h2>
<h2>second level B</h2>

Did you note, this blog is also written using the markdown format. And the headlines will look like all the other headlines in this article.

Embedding a Link in Markdown

Do add a link into your text, you enclose the text of the link into corner brackets [] followed by the URL to link to, in round brackets (). It will look like this:

Some text with a [link](http://tnickel.de/).

Some text with a <a href="http://tnickel.de/">link</a>.

And it looks like this:

Some text with a link.

That is easy right?

How to format Lists

Lists look good in the markdown file, as well as in the rendered output. Here is an example for ordered and unordered list, presented in markdown, html and rendered what the end user will see.

# list one
 - apple
 - banana
 - peach
# list two is ordered
 1. apple
 2. banana
 3. peach

<h1>list one</h1>
<ul>
<li>apple</li>
<li>banana</li>
<li>peach</li>
</ul>
<h1>list two is ordered</h1>
<ol>
<li>apple</li>
<li>banana</li>
<li>peach</li>
</ol>

list one

• apple
• banana
• peach

list two is ordered

1. apple
2. banana
3. peach

Tables

Tables in markdown almost look like the rendered version:

one   | two
------|------
three | four

one	two
three	four

Do you notice that the first line becomes table headers? On my block they are shown a little bold.

Showing Pictures on the Page

To show an image, works similar to links. But it has a leading exclamation mark !.

![alternative texts](/images/flashed.jpg)

Uuhhh, That was too fast. The alternative text is good for SEO, accessibility (a11y) and is shown in the browser when you hover over the picture with you your mouse.

Present Code in Markdown

Writing code just plain on your page, makes it very hard to read. at least code should be presented using a monospace font. Most markdown formatter even generate some styles for syntax highlighting and add line numbers.

```markdown
your code here
```

The generated HTML from this example looks much more complex, and it will be different from every markdown compiler. How it can look, you see it all over this blog post already.

Sometimes to highlight a single word I also use the backtick (`) character.

Where to go next?

The first time that I wrote markdown, was for a project I published on github. Github presents README.md files in a html rendered form, that also allow for nice syntax highlighting when presenting code.

The same readme file is also rendered on every projects page on NPM.

I also enjoy writing my blog using markdown. As it is very clean and I write in the same tool, that I also use for coding.