Markdown is a "lightweight" markup language (HTML is another example of a markup language). The goal of Markdown is to be easy to write and read in plain text format, and easily converted into HTML and other formats. Most people writing plain text files tended to follow similar syntax norms; Markdown formalized these norms into a language.

GitHub has a nice feature in that any file with a .md or .markdown extension will be rendered as "pretty" HTML. If you format your README as Markdown, and give it one of these extensions (i.e., README.md), your repository will have a nice looking landing page.

Below is a brief introduction into some of the commonly used features of Markdown. For more details about Markdown see John Gruber's original description of the language. GitHub has its own "dialect" that supports some additional features; for full details on GitHub-flavored Markdown go here.

Contents

• Basic Text Formatting
  • Emphasizing words
  • Paragraphs
• Section Headers
• Lists
• Links
• Images
• Code and Syntax Highlighting
• Inline code
• Code blocks

Basic Text Formatting

Emphasizing words

You can italicize text by surrounding it with one asterisk or underscore character.

For example, I want to emphasize *these words* and these _other words_.

For example, I want to emphasize these words and these other words.

---

You can bold text by surrounding it with two asterisk or underscore characters.

For example, I want to bold **these words** and these __other words__.

For example, I want to bold these words and these other words.

---

Why two ways to do the same thing?! Good question, but it does allow us to nest one inside the other in a more readable fashion.

These notes are an **absolute _disaster_**!

is a bit more readable than

These notes are an **absolute *disaster***!

but both work.

These notes are an absolute disaster!

is a bit more readable than

These notes are an absolute disaster!

but both work.

Paragraphs

Lines separated by one newline character
will be part of the same paragraph.

But, a line separated by two newline characters will be a different paragraph

Lines separated by one newline character will be part of the same paragraph.

But, a line separated by two newline characters will be a different paragraph

Section Headers

Starting a line with 1-6 # characters will result in a section heading.

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6

Header 1

Header 2

Header 3

Header 4

Header 5

Header 6

Lists

You can create unordered lists using asterisks *, dashes -, or pluses +.

-   First item
-   Second item

    You can add a second paragraph to this item as long as you indent to align
    with the text above.

-   Third item
    -   A sub item
-   A forth item

• First item

• Second item

  You can add a second paragraph to this item as long as you indent to align with the text above.

• Third item

  • A sub item

• A forth item

---

If you want to enumerate the list, then use numbers.

1.  First item
2.  Second item

    You can add a second paragraph to this item as long as you indent to align
    with the text above.
    
3.  The third item has a
    1.  Sub item.
4.  Note
1.  The numbers
5.  Don't matter

1. First item

2. Second item

   You can add a second paragraph to this item as long as you indent to align with the text above.

3. The third item has a

   1. Sub item.

4. Note

5. The numbers

6. Don't matter

Links

You can create links using the syntax [text to display](URL HERE).

Try this [little-known search engine](https://www.google.com) to learn more
about MarkDown.

Try this little-known search engine to learn more about MarkDown.

---

You can use angle brackets to turn a URL into a link

The URL for GitHub is <https://github.com/>

The URL for GitHub is https://github.com/

Images

The syntax for embedding images is very similar to links, ![alt text](PATH-or-URL-of-image "optional title text").

![Lizard photo](./images/gecko-photo.jpg "Cute gecko")

![Lizard photo](https://github.com/joaks1/markdown-notes/raw/master/images/gecko-photo.jpg "Cute gecko")

Code and Syntax Highlighting

Inline code

You can format `code` inline by surrounding it with single backticks

You can format code inline by surrounding it with single backticks

Code blocks

Blocks of code can be done by indenting:

    print("Hello Word")

Or by surrounding the line with triple backticks:

```
print("Hello World")
```

Blocks of code can be done by indenting:

print("Hello Word")

Or by surrounding the line with triple backticks:

print("Hello World")

---

The triple backticks have the advantage of being able
to specify the language for nice syntax highlighting:

```python
# Note that markdown *syntax* is **ignored** in here
for i in range(10):
    s = "Hello World " + str(i)
    print(s)
```

The triple backticks have the advantage of being able to specify the language for nice syntax highlighting:

# Note that markdown *syntax* is **ignored** in here
for i in range(10):
    s = "Hello World " + str(i)
    print(s)