Introduction to Markdown

Learn the basics of Markdown syntax and how to use it to create content for your Jekyll site.

By Kevin McAleer,    3 Minutes

What is Markdown?

Markdown is a lightweight markup language with plain-text formatting syntax. Its main goal is to be as readable and understandable as possible. Markdown files have the extension .md or .markdown and can be converted into HTML by tools like Jekyll, making it an ideal choice for writing content on the web.

Why Use Markdown?

• Simplicity: Markdown’s syntax is straightforward, making it easy for anyone to learn and use.
• Flexibility: It can be converted into HTML, PDFs, and other formats.
• Compatibility: Markdown files are compatible with version control systems, facilitating collaboration and changes tracking.

The best feature of Markdown is that its just plain text. You can write Markdown in any text editor and there are no special tags to learn or remember, its mostly formatted using punctuation that looks natural.

This entire website is written using Markdown and converted to HTML using Jekyll.

Basic Markdown Syntax

Headings

Use # for headings. The number of # symbols before the text corresponds to the level of the heading.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Emphasis

• Bold: **bold text** or __bold text__
• Italic: *italic text* or _italic text_

Lists

• Unordered list: Start a line with -, *, or +.
• Ordered list: Start a line with a number.

- Item 1
- Item 2
  - Sub Item 2.1
  - Sub Item 2.2

1. First item
2. Second item

Links and Images

• Link: [Link text](URL)
• Image: ![Alt text](Image URL)

Code Blocks and Inline Code

• Inline code: Use single backticks: `code`.
• Code block: Use triple backticks or indent with four spaces.

inline code

a = 1

Using Markdown with Jekyll

In Jekyll, Markdown files are processed and converted into HTML, making up the content of your site. You can also use Liquid templating language to incorporate dynamic content into your Markdown files.

Practice Exercise

Create a new Markdown file in your Jekyll site’s _posts directory. Write a short post that includes a heading, a few paragraphs of text, a list, and a link to Jekyll’s documentation.