# The Complete Beginner‘s Guide to Markdown

- Canonical: https://33rdsquare.com/the-complete-beginners-guide-to-markdown/
- Published: 2024-04-05
- Author: Kara Masterson
- Categories: [Technology](https://33rdsquare.com/category/tech/)

---

Markdown has become the formatting language of choice for writers and tech professionals across the web. With its simple plaintext formatting syntax, markdown allows you to write quickly while producing clean, consistent web documents that look great on any device.

In this comprehensive guide, you‘ll learn everything you need to know to become productive in markdown, from the basics of formatting text to more advanced features like creating tables and math equations.

## The Explosive Growth of Markdown

While originally created in 2004 as a simple way to add formatting to plaintext documents, markdown has exploded in popularity over the past decade as theFORMATTING INFORMAT stripping any rich text styling down to basic syntax elements like asterisks and underscores.

**According to recent surveys among technical writers in 2022, adoption of markdown has now surpassed use of legacy desktop publishing platforms like Microsoft Word and Adobe InDesign.**

The below chart illustrates how interest in markdown and search volume has grown significantly since 2016 to surpass interest in more complex formatting approaches:

![Search Interest in markdown vs other formats](https://33rdsquare.com/search_interest.png)

What is driving this rapid adoption of markdown across industries? **Several key advantages make markdown a attractive choice:**

- Human readability – Documents formatted in markdown remain easy to read as raw plaintext
- Version control friendliness – Markdown can be managed by basic version control tools like git
- Format flexibility – Markdown documents can render well as HTML, PDFs, slide decks and more
- Writer efficiency – The syntax is simple enough to allow writers to compose documents faster
- Platform ubiquity – Markdown is supported out-of-the-box across most modern publishing platforms

The lightweight nature of markdown makes it accessible to more people without disrupting existing technical workflows dependent on managing plaintext documents.

Next, we‘ll explore the basic markdown syntax newcomers can learn to become productive with writing documents in markdown.

## Markdown Formatting Basics

The syntax for formatting markdown looks much like you might format an email or other plaintext document, using characters you can type directly from your keyboard:

- Asterisks (`*`) and underscores (`_`) to denote _italics_ and **bold**
- Square brackets (`[]`) for links
- Parentheses for URLs
- Pound sign (`#`) for headings
- Plus sign (`+`) or dashes (`-`) for bullet lists
- Plain numbers and periods for numbered lists

For example, here is a quick paragraph I might write in markdown, using some basic formatting:

```
# My Markdown Paragraph

I‘m writing in **markdown** today. I can make things *italic* or **bold** and even write a [hyperlink](https://www.example.com) to any web page I want!

Below I‘ll add a nice ordered list:

1. First item
2. Second item
3. Third item

And maybe an unordered list too:

- Apples
- Oranges
- Bananas
```

The above markdown will be rendered as nice clean HTML in any markdown editor or publishing platform:

I‘m writing in **markdown** today. I can make things _italic_ or **bold** and even write a [hyperlink](https://www.example.com) to any web page I want!

Below I‘ll add a nice ordered list:

1. First item
2. Second item
3. Third item

And maybe an unordered list too:

- Apples
- Oranges
- Bananas

The coding behind the scenes handles converting all the syntax to proper HTML tags, while my source document remains clean and publishable as-is if needed in plaintext form.

Now that you have the basics down, let‘s explore some more powerful markdown capabilities…

## Advanced Markdown Features

In addition to simple text formatting, markdown also supports adding images, code blocks, tables, footnotes, and even math equations, all using consistent syntax designed to look clean to the untrained eye.

Here are some examples showcasing more advanced markdown functionality:

### Images

Adding images in markdown is accomplished using an exclamation point, square brackets for alt text, and parentheses for the image URL:

```
![My helpful screenshot](https://images.example.com/screenshot.png)
```

Renders to:

![My helpful screenshot](https://images.example.com/screenshot.png)

### Code Blocks

Code blocks use surrounding backticks to delimit a section of code:

````
```
# Sample javascript code
function helloWorld() {
  console.log("Hello markdown!");
}
```
````

Renders as a nicely formatted code block:

```
// Sample javascript code
function helloWorld() {
  console.log("Hello markdown!");
}
```

### Tables

Tables use pipe dividers (`|`) and row of dashes to delimit table cells:

```
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
```

Renders as:

| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |

### Footnotes

Footnotes are denoted by brackets, caret, text, and colon:

```
Here is a footnote reference[^1]

[^1]: Here is the footnote content
```

The footnote renders at the bottom of the document:

Here is a footnote reference[^1]

[^1]: Here is the footnote content

### LaTeX Math Equations

Surround math expressions with double dollar signs for inline math:

```
This expression is inline: $x^2 + y = 3$
```

Renders as: This math is inline: $x^2 + y = 3$

Markdown also supports display math with LaTeX delimiters:

```
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
```

Renders as a nicely formatted equation:

$$
 \frac{n!}{k!(n-k)!} = \binom{n}{k}
 $$

With these advanced capabilities, markdown enables technical documents, analysis reports, scientific papers and more to contain all the elements they need while retaining readability and portability from original authoring in markdown syntax.

Now let‘s talk about helpful tools for writing markdown itself.

## Markdown Editors & Tools

Now that you understand the markdown syntax, let‘s look at some useful tools and editors for writing markdown documents efficiently:

### Typora

[Typora](https://typora.io/) provides a clean user interface and live document preview alongside your markdown source text. It‘s available for Windows, macOS and Linux.

![Typora markdown editor screenshot](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Typora_screenshot.png/2880px-Typora_screenshot.png)

Typora is excellent for beginners looking for a simplified, distraction-free environment to write markdown without seeing all the syntax.

### iA Writer

[iA Writer](https://ia.net/writer) is a popular markdown editor for Mac and iOS, with a focus on simplicity, excellent typography and night mode for writing.

![iA Writer](https://ia.net/writer/img/writer-screenshot.png)

iA Writer works well for long-form writing and exports documents to HTML, PDF and Microsoft Word formats.

### Ulysses

[Ulysses](https://ulysses.app/) is a full-featured writing app for Mac, iPad and iPhone that uses markdown behind the scenes to format text. It offers seamless syncing of documents across devices via iCloud.

![Ulysses app](https://ulysses.app/images/screenshots/desktop_library_xl.jpg)

Ulysses hides markdown syntax by default, letting you focus on writing without distraction while still producing markdown documents.

There are many other great choices besides these for editing markdown. The right tool comes down to personal preferences around operating systems, budget, complexity and desired features.

Next let‘s explore all the possibilities with markdown documents…

## Uses & Applications for Markdown

Now that you know the basics of writing markdown-formatted text, what kinds of things can you _do_ with markdown?

As a universal, future-proof document format, markdown excels across nearly any application involving written content.

### Websites & Blogging

Markdown was designed from day one to power web writing, so it should be no surprise it integrates beautifully with modern blogging platforms. Rather than struggling with WYSIWYG editors and formatting toolbars, authors can focus purely on writing content itself formatted in simple markdown. Some popular blogging platforms with built-in markdown support include:

- [Ghost](https://ghost.org/)
- [Hexo](https://hexo.io/)
- [Jekyll](https://jekyllrb.com/)
- [Hugo](https://gohugo.io/)
- [Wordpress](https://wordpress.org/) (requires [plugin](https://wordpress.org/plugins/wp-markdown/))

Static site generators like Jekyll allow you to author sites as markdown files which get compiled to HTML during site build processes. This makes it easy to version control and manage markdown-authored content using basic plaintext workflows.

### Documents & Notes

Markdown shines for personal documents and notes. With editors like [Obsidian](https://obsidian.md/), [Joplin](https://joplinapp.org/), and [Bear Writer](https://bear.app/), you can take notes and write documents in markdown from any device while easily syncing your content across mobile, tablet, desktop via cloud services like Dropbox. Markdown files render nicely to HTML and PDF for archival and exports.

### Technical Writing

For software teams publishing internal technical documentation, wikis, API references, developer guides and release notes, markdown has become the standard authoring format. Tech writer teams manage markdown file collections using version control tools like Git rather than heavy word processor file formats. Markdown flows through developer workflows and toolchains seamlessly from authoring to publishing. Platforms like [Read the Docs](https://readthedocs.org/), [DocOps](https://docops.com/) and [VuePress](https://vuepress.vuejs.org/) have built-in support to stream markdown content through templating engines into modern reader experiences as portable HTML without added effort from authors.

### Books & Long-Form Writing

Many [indie authors](https://www.thecreativepenn.com/2015/01/14/writing-in-markdown/) now use markdown for authoring books and long-form writing. The simplicity of markdown for content authoring combined with conversion tools like [Pandoc](https://pandoc.org/) makes the publishing process no longer dictated by specific word processor file formats. A manuscript authored in markdown can readily be exported into necessary formats for publishing print, ebooks, audiobooks, websites and more without disruption. Popular tools in this category include [Leanpub](https://leanpub.com/) and [Bookdown](https://bookdown.org/).

### Email Newsletters

Markdown provides excellent support for newsletter publishing platforms. Authors can write rich content solely focused on words rather than fighting against a visual template builder. Images, links, formatting and other elements flow through easily from markdown to final rendered newsletters. Platforms like [Buttondown](https://buttondown.email/), [Revue](https://www.getrevue.co/) and [Substack](https://substack.com) allow writers to author newsletters in markdown which then publish across email, web and RSS seamlessly without added effort.

### Reporting & Analytics

Within business intelligence teams, markdown empowers self-service reporting and analytics publishing. Rather than being locked into proprietary reporting tools, business analysts can author data-rich documents in markdown leveraging code chunks for calculations which integrate cleanly into reporting dashboards. [Quarto](https://quarto.org/) provides excellent support foranalytics teams with the flexibility of markdown-powered documents containing live code and query output in a reproducible format for sharing internally or externally.

### Research Writing

For researchers authoring papers and scientific communication, markdown removes all friction dealing with equation editing, citations, formatting inconsistencies and managing collaborative feedback. Authors can write papers and lab notebooks natively in markdown then utilize versatile tools like [Pandoc](https://pandoc.org/), [Quarto](https://quarto.org/) and LaTeX class templates to target PDF, HTML, EPUB publication formats easily without disrupting writing workflow focused on content itself. Projects like [Manubot](https://manubot.org/) aim to revolutionize scholarly publishing based on markdown source manuscripts.

### Government & Public Sector

Complex government processes often mandate submission of information via specific document formats containing forms, tables and metadata together. This puts friction on constituents providing information while also introducing accessibility barriers to participation. Code for America outlines a case study for [simplifying document submission](https://markdownguide.org/tools/obisidian/) where forms can be populated by residents in simple markdown formats to generate compliant PDFs without difficulty. Similar opportunities likely exist across other areas of public sector red tape.

## Limitations of Markdown

For all its benefits, Markdown does have some limitations to be aware of as an author:

**Design Constraints** – The plaintext nature of markdown leads some complex content arrangements difficult or awkward to achieve. Workarounds frequently involve escaping to raw HTML which can work but often results in messy hybrid documents.

**Metadata Support** – On its own, markdown just contains text content and some formatting. Tracking richer structural attributes like document authors, page structure semantics, revision history and more requires additional conventions around the markdown specification.

**Accessibility Gaps** – Native HTML provides robust built-in accessibility features like ARIA roles and semantic element markup exceeding what markdown can represent on its own. Additional effort is warranted to check rendered markdown passes accessibility standards for complex documents.

**Specification Variance** – While a common baseline of markdown exists, flavors and extensions do vary across implementations technically resulting in areas of incompatibility depending on processor. For simplicity, restrict markdown features to universally supported elements.

**Small Learning Curve** – Those accustomed to WYSIWYG word processors likely will met with a minor adaptation moving into plaintext using markdown. Practicing for a few weeks typically alleviates major hurdles for new adopters.

While these limitations deserve awareness, none meaningfully detract from markdown‘s utility for the vast majority of everyday authoring use cases. Tradeoffs vs graphical editors are reasonable for most given the simplicity and durability that markdown affords.

## Closing Thoughts on Markdown Essentials

Hopefully you‘ve now gained an appreciation for the simplicity yet enormous flexibility of markdown for writing just about anything requiring formatted text. While early markdown focused primarily on blogging, uses today span books, technical docs, web writing, computational notebooks, government forms and even presentations.

For beginners, the most important next step is _writing actual documents in markdown_. Challenge yourself to author your next status report, blog post, meeting notes or other document in markdown instead of your traditional editor. With some practice using the syntax, plus leveraging available apps and tools to integrate markdown into your workflows, you may find text writing becomes simpler and less constrained across projects once formatting concerns fade into the background.

If this overview was helpful or you have observations about markdown you‘d like to share, please leave them in the comments below!

---

Source: [The Complete Beginner‘s Guide to Markdown](https://33rdsquare.com/the-complete-beginners-guide-to-markdown/)