Introduction

You do not need to know how to code to use Markdown.

This is worth saying clearly, because Markdown has a reputation as a programmer's tool — something that lives in terminals and editors used by software developers. That reputation is historically earned but no longer accurate. Markdown is now the writing format of choice for journalists, academics, novelists, content strategists, and technical writers who have never written a line of code. It is built into Notion, Obsidian, GitHub, Reddit, Discord, Linear, Jira, Confluence, and dozens of other tools used by millions of non-technical people every day.

What has not caught up is the documentation. Most Markdown guides are still written for developers, assuming familiarity with command lines, version control, and text editors that look intimidating to anyone who has spent their writing life in Microsoft Word or Google Docs.

This book takes a different approach.

What This Book Covers

The book is organised around three practical concerns.

Workflows — how Markdown fits into real writing and publishing processes or just everyday tasks. How to start writing in Markdown today, how to collaborate with people who do not use it, and how to get usable output from your Markdown files without needing a computer science degree.

Reference — a complete, readable guide to every Markdown element, from headings and lists to tables, footnotes, and mathematics.

Showcase — todo.

What This Book Does Not Cover

todo

How to Read This Book

If you are new to Markdown, start with the Workflows the first workflows are essentially beginner tutorials. Then try some of the more advanced workflows that suit your intended use.

If you have used Markdown before and want to deepen your knowledge and practice, take a look at the Reference section, when writing this section I found many details that were previously unknown to me so there is value in this section for everyone, even those who may already work with Markdown.

The Showcase section is for inspiration, you can see some of the beautiful things you can do with Markdown. This section does include additional markup that somewhat erodes the concept of 'clean' best practice Markdown, but then when you know and understand the best practice you can also decide when to go against it to achieve superb results using Markdown.

#set page(
  number-align: center,
  numbering: (..nums) => {
    let n = nums.pos().at(0)
    if n >= 1 { numbering("1", n) }
  }
)
#counter(page).update(0)