Introduction to Markdown

Markdown is a lightweight markup language designed to make it easy to format structured text using plain-text characters. Instead of relying on a visual editor to apply formatting, Markdown uses simple symbols and conventions to describe headings, paragraphs, lists, links, images, code, and other elements.

For example, a Markdown heading can be written simply as:

# My First Heading

The same source can then be converted into an HTML heading when published:

<h1>My First Heading</h1>

This separation between the content and its presentation is one of Markdown’s most useful characteristics.

Why Learn Markdown?

Markdown is relatively easy to learn because most of its syntax is intuitive. A few characters can represent formatting that would otherwise require buttons, menus, or more complicated markup.

For example:

# Introduction

This is a **bold statement**.

This is an *emphasized statement*.

- First item
- Second item
- Third item

Markdown makes the underlying structure visible while keeping the source document readable.

This makes it particularly useful for people who need to create, organize, edit, convert, or publish large amounts of content.

Markdown as a Content Format

Markdown is more than a convenient way to make text bold or create headings. It can serve as a durable source format for structured content.

A Markdown document can contain:

• Headings and subheadings
• Paragraphs
• Ordered and unordered lists
• Links
• Images
• Tables
• Block quotations
• Code blocks
• Inline code
• Horizontal rules
• Task lists
• Metadata and other extensions

Because Markdown files are plain text, they can be opened and edited with a wide variety of applications. They do not require a particular word processor or publishing platform.

This is an important distinction between Markdown and many proprietary document formats.

Markdown and HTML

Markdown and HTML are closely related, but they serve different purposes.

HTML is a markup language designed for describing documents and content on the web. Markdown is a simplified authoring format that can be converted into HTML and other formats.

For example, Markdown:

## Learning Markdown

can produce HTML similar to:

<h2>Learning Markdown</h2>

The Markdown version is generally easier for a person to write and read, while the HTML version provides the structure expected by a web browser.

This makes Markdown particularly useful as an intermediate or source format in publishing workflows.

Markdown and the Separation of Content from Presentation

One of the most important concepts to understand when learning Markdown is the separation of content from presentation.

A Markdown file primarily describes what the content is.

For example:

# Digital Asset Management

Digital Asset Management systems organize and maintain
digital files and their associated information.

The Markdown does not normally specify exactly what the heading should look like. A publishing system can decide that all level-one headings should use a particular font, size, spacing, and visual treatment.

This approach allows the same source content to be presented in different environments without rewriting the content itself.

The same Markdown source could potentially become:

• A webpage
• A PDF document
• An ebook
• A printed publication
• Documentation
• Course material
• A knowledge-base article
• Another structured content format

Markdown Files Are Plain Text

A Markdown file normally uses the .md file extension.

Because the contents are plain text, Markdown files have several useful characteristics:

• They are small and portable.
• They can be opened without specialized software.
• They are easy to store and back up.
• They work well with version-control systems.
• They can be processed automatically.
• They can be converted into other formats.
• They remain readable even without their original publishing software.

This makes Markdown an attractive format for long-term content management.

Markdown Editors

Markdown can be written in almost any text editor. However, dedicated Markdown editors provide additional features such as syntax highlighting, live previews, table tools, and document navigation.

Common environments for working with Markdown include:

• Visual Studio Code
• Obsidian
• Typora
• GitHub
• Joplin
• Many documentation and static-site systems

The important point is that Markdown itself is not tied to any particular application.

Basic Markdown Syntax

Learning Markdown begins with a relatively small collection of syntax rules.

Headings

The number sign (#) is used to create headings.

# Level 1 Heading
## Level 2 Heading
### Level 3 Heading

The number of # characters determines the heading level.

Emphasis

Asterisks or underscores can be used for emphasis.

*Italic text*

**Bold text**

***Bold italic text***

Lists

Unordered lists can be created with hyphens:

- First item
- Second item
- Third item

Ordered lists use numbers:

1. First step
2. Second step
3. Third step

Links

Links can be written using the following structure:

[Visit Example](https://example.com)

The text inside the square brackets becomes the visible link text.

Images

Images use a similar structure:

![Description of image](image.png)

The text inside the square brackets provides alternative text for the image.

Code

Inline code can be represented with backticks:

Use the `print()` function.

Larger sections of code can be placed inside fenced code blocks:

```python
print("Hello, world!")
```

The language identifier can allow Markdown processors and editors to apply appropriate syntax highlighting.

Markdown Variations

Markdown is not a single completely standardized language.

The original Markdown syntax has been extended and implemented in different ways by different applications and platforms. These variations are often called Markdown flavors.

Examples include:

• CommonMark
• GitHub Flavored Markdown
• Markdown Extra
• MultiMarkdown

Most implementations share the fundamental syntax, but additional features may differ.

This is important when moving Markdown documents between applications. A document that uses specialized Markdown extensions may not render exactly the same way everywhere.

Markdown and Accessibility

Markdown can also contribute to accessible content when it is used correctly.

Properly structured headings create a meaningful document hierarchy. Descriptive link text provides more useful navigation information. Alternative text can be provided for images, and semantic elements such as lists can preserve the logical structure of information.

For example, this is preferable:

[Download the employee handbook](handbook.pdf)

rather than:

[Click here](handbook.pdf)

Markdown does not automatically make a document accessible, but its structural nature can encourage authors to think about the semantic organization of their content.

Markdown in Publishing Workflows

Markdown becomes especially powerful when it is treated as a source document rather than simply as a formatting convenience.

A typical workflow might look like this:

Create Markdown
       ↓
Edit and review
       ↓
Store source document
       ↓
Convert or publish
       ↓
HTML / PDF / EPUB / Other Format

A conversion tool such as Pandoc can process the Markdown and generate different output formats.

This approach allows the original Markdown document to remain the authoritative source while generated files are treated as published outputs.

Markdown and Version Control

Because Markdown files are plain text, they work particularly well with version-control systems such as Git.

A version-control system can record changes to the source document and make it possible to compare different versions.

For example:

Version 1
    ↓
Edit
    ↓
Version 2
    ↓
Edit
    ↓
Version 3

Instead of maintaining multiple copies such as:

chapter-final.docx
chapter-final2.docx
chapter-final-revised.docx
chapter-final-revised-final.docx

a version-control system can maintain a history of changes to a single source document.

This becomes increasingly valuable as the amount of content grows.

Markdown as a Foundation for Structured Content

Markdown occupies an interesting position between ordinary text and fully structured data.

A plain text document may contain information without explicitly identifying its structure. Markdown introduces recognizable structural elements such as headings, lists, links, and code blocks.

More sophisticated publishing systems can then interpret that structure and transform it into other representations.

This makes Markdown useful in documentation systems, educational content, technical publishing, knowledge bases, and content-management workflows.

What Markdown Is Not

Markdown is not a replacement for every type of document format.

It is not designed to provide the same level of precise visual layout as desktop publishing software. It does not attempt to describe every aspect of typography, page geometry, or graphic design.

Markdown is primarily concerned with the structure and meaning of content.

When precise presentation is required, Markdown can instead serve as the source from which another system generates the final presentation.

Learning Markdown

The best way to learn Markdown is to use it.

Begin with the basic elements:

1. Headings
2. Paragraphs
3. Emphasis
4. Lists
5. Links
6. Images
7. Code blocks
8. Tables
9. Block quotations

Once these elements become familiar, more advanced subjects can be explored, including Markdown extensions, metadata, document conversion, HTML integration, and automated publishing.

The syntax is intentionally small. The greater skill comes from understanding how structured content can move through a larger workflow.

Markdown in a Modern Content Workflow

Markdown is particularly useful when content needs to survive beyond the application in which it was originally created.

A document stored as Markdown is not dependent on a particular visual editor, database interface, or website theme. It can be edited, converted, indexed, versioned, archived, and republished using different tools.

That makes Markdown more than a simple formatting language.

It can be part of a broader philosophy of content management:

Create content once. Preserve the source. Generate the presentation.

Understanding this distinction is an important step toward building flexible, portable, and maintainable publishing systems.

Hiding Decorative Text from Screen Readers

Sometimes a webpage contains text that is useful visually but does not provide useful information when read aloud by a screen reader. The HTML aria-hidden="true" attribute can be used to tell assistive technology to ignore that content.

For example:

<span aria-hidden="true">Page 12</span>

The text Page 12 will still appear visually on the webpage, but a screen reader should ignore it.

This can be useful for page numbers in documents that have been converted to HTML. If the page number is displayed as a visual reference or design element, reading it aloud can interrupt the natural flow of the content.

For example:

<span aria-hidden="true">Page 12</span>

<h2>Introduction to Markdown</h2>

<p>Markdown is a lightweight markup language...</p>

A sighted reader sees:

Page 12 Introduction to Markdown

A screen-reader user would normally hear the heading and paragraph without the unnecessary Page 12 announcement.

An Important Accessibility Consideration

aria-hidden="true" should only be used when the hidden content is genuinely unnecessary to users of assistive technology. It should not be used to hide meaningful information simply because it is inconvenient to read aloud.

In this example, the page number is treated as a visual document marker rather than part of the actual content. The semantic heading and paragraph remain available to assistive technology.

This illustrates an important principle of accessible HTML: visual presentation and the information exposed to assistive technology do not always have to be identical.

Additonal Articles

Resources