DEV Community

Cover image for Markdown for Beginners - Create a Better Readme
Megan Moulos
Megan Moulos

Posted on

Markdown for Beginners - Create a Better Readme

What is Markdown?

Markdown is one of the most popular markup languages. Developed by John Gruber in 2004, it's a simple and lightweight way to add formatting (and pizazz) to plaintext documents. In Gruber's words:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

While many of us are used to Rich Text Editors like Microsoft Word, where changes are visible immediately, Markdown uses unique plaintext syntax to change how text appears. This guide will go over commonly used Markdown syntax, so you can create a better GitHub README!

You can add Markdown using any text editor application. There are also Markdown applications, some of which allow you to preview your document in real time. For our purposes, you can follow along in Dillinger, so that you can see the changes immediately.


There are 6 headers available, H1 through H6.

Here is the Markdown syntax:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Enter fullscreen mode Exit fullscreen mode

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Adding emphasis to your text

Here is the Markdown syntax for making text bold, italic, and underlined. You can also strike through, or 'cross out,' text using the strikethrough method.

~~strike through~~
Enter fullscreen mode Exit fullscreen mode

BONUS: Subscripts and Superscripts

Sometimes we may want to use superscripts for things like chemical notation H20 or exponents x2. With Markdown, it's simple:

Enter fullscreen mode Exit fullscreen mode

For superscripts, you surround the element you want to make a subscript with the 'sub' tag. For subscripts, you surround the element with the 'sup' tag.

Highlighting Syntax & Code Blocks

Using a single backtick will highlight a word or piece of code. You can see it in the following example below:

In this sentence, the word hello will be highlighted.

Using three backticks will create a code block. If you add a language identifier directly after the backticks you will have more colorful, readable code. Here is an example using JavaScript:

const makeAVariable = 'Hello'

// This will show different colors 
Enter fullscreen mode Exit fullscreen mode


To show a quote, use a greater than symbol. Quotes are extremely useful for when you are referencing someone else's work. It is important to credit where credit is due.

"Make sure to save your code!" - Megan


To create an ordered list, begin from 1 and count upwards.

  1. Item one
  2. Item two
  3. Item three

You can also create sub-items on your list and even include bullet points:

  1. Item one
    1. Sub-item one
    2. Sub-item two
  2. Item two
    • Sub-item three
  3. Item three

Unordered lists are created using a minus sign before each item. See below:

Shopping List:

  • cereal
  • eggs
  • cheese

Images & Emojis

To add an image, use an exclamation point followed by square brackets containing your alt text, followed by your html link in parentheses like so: ![alt text](url)


You can also use emojis in Markdown. There is a complete list of emojis recognized here.



To create a link, simply put the link text in square brackets and then parentheses enclosing the URL you'd like to point to. The syntax looks like this: [](url)

Check out some great links below!
My GitHub
My LinkedIn

This has been a quick guide to making your README files more beautiful using Markdown. Show me your new README in the comments below!

Top comments (0)