Pandoc: Converting Markdown to HTML

Pandoc is a versatile document-conversion tool that can transform content from one markup format into another. For web publishing, one of its most useful applications is converting a Markdown (.md) document into HTML.

This creates a simple publishing workflow:

Markdown → Pandoc → HTML → WordPress

Instead of manually copying headings, paragraphs, lists, and other content elements into a WordPress page, the document can be written once in Markdown and converted into structured HTML.

What You Will Learn

By the end of this tutorial, you will be able to:

• Identify the role of Pandoc in a document-publishing workflow.
• Create a basic Markdown document.
• Convert a Markdown file into an HTML file using Pandoc.
• Examine the HTML generated by Pandoc.
• Open the resulting HTML document in a web browser.
• Prepare generated HTML for use in WordPress.
• Understand how CSS can control the appearance of generated content.

What Is Pandoc?

Pandoc is an open-source document converter designed to translate documents between many different markup and document formats.

Markdown is one of its most useful input formats because Markdown provides a simple way to describe the structure of a document without requiring extensive HTML knowledge.

For example, this Markdown:

# Introduction to Pandoc

Pandoc converts documents between different formats.

## What You Will Learn

You will learn how to convert Markdown into HTML.

- Create a Markdown document
- Run Pandoc
- Examine the resulting HTML

can be converted into HTML containing elements such as:

<h1>Introduction to Pandoc</h1>

<p>Pandoc converts documents between different formats.</p>

<h2>What You Will Learn</h2>

<p>You will learn how to convert Markdown into HTML.</p>

<ul>
<li>Create a Markdown document</li>
<li>Run Pandoc</li>
<li>Examine the resulting HTML</li>
</ul>

The important point is that Markdown contains the document’s structure, while HTML provides the structure that a web browser understands.

Why Use Markdown as the Source?

When content is created directly inside a page builder, the content and presentation can become tightly connected.

For example, creating an instructional page manually might involve adding:

1. A heading widget.
2. A text widget.
3. Another heading widget.
4. Another text widget.
5. A list widget.
6. An image widget.
7. Additional formatting elements.

Markdown allows the structure to be represented directly in the source document.

A heading is represented by # characters:

# Main Heading

## Section Heading

### Subsection Heading

A bulleted list is represented using hyphens:

- First item
- Second item
- Third item

A paragraph is simply written as text.

This makes Markdown particularly useful for instructional content because the document structure is preserved independently of the publishing platform.

Before You Begin

This tutorial assumes that Pandoc has already been installed.

Open a terminal or command prompt and enter:

pandoc --version

If Pandoc is installed correctly, the command should return information about the installed version.

If the command is not recognized, Pandoc may not be installed or its executable may not be available through the system’s PATH environment variable.

Create a Markdown Document

Create a new text file named:

pandoc-test.md

The .md extension identifies the document as Markdown.

Open the file in a text editor and enter the following:

# Learning Pandoc

Pandoc provides a convenient way to convert Markdown documents into HTML.

## Why Convert Markdown to HTML?

Markdown is easy to write and maintain, while HTML is designed for displaying structured content on the web.

Using Pandoc allows the same source document to be converted into HTML without manually writing the HTML markup.

## The Basic Workflow

The conversion process is straightforward:

- Create the Markdown document.
- Save the document with a `.md` extension.
- Open a terminal.
- Run Pandoc.
- Open the resulting HTML file in a web browser.

## Conclusion

Markdown and Pandoc provide a simple foundation for creating structured web content.

Save the file.

Open a Terminal in the Document’s Folder

The easiest way to work with Pandoc is to open a terminal in the directory containing the Markdown document.

For example, if the document is stored in:

C:\Users\YourName\Documents\Pandoc

open the terminal in that directory.

You can verify that the Markdown file is present by listing the directory contents.

In PowerShell, use:

Get-ChildItem

You should see:

pandoc-test.md

Convert Markdown to HTML

The basic Pandoc conversion command is:

pandoc pandoc-test.md -o pandoc-test.html

The command consists of three important parts.

pandoc

Runs the Pandoc program.

pandoc-test.md

Specifies the input file.

-o pandoc-test.html

Specifies the output file.

After the command finishes, the directory should contain both files:

pandoc-test.md
pandoc-test.html

The Markdown file remains unchanged. Pandoc has created a new HTML file from it.

Open the HTML File

Open pandoc-test.html in a web browser.

The browser should display the document as a formatted webpage.

The Markdown syntax itself will not be visible.

For example, this:

## Why Convert Markdown to HTML?

will appear in the browser as a formatted section heading rather than displaying the ## characters.

Likewise:

- Create the Markdown document.
- Run Pandoc.
- Open the HTML file.

will appear as a bulleted list.

This demonstrates the fundamental purpose of the conversion process: Markdown describes the document while Pandoc translates that structure into HTML.

Examine the Generated HTML

The HTML file can also be opened in a text editor.

You may see something similar to:

<h1 id="learning-pandoc">Learning Pandoc</h1>
<p>Pandoc provides a convenient way to convert Markdown documents into HTML.</p>

<h2 id="why-convert-markdown-to-html">Why Convert Markdown to HTML?</h2>

<p>Markdown is easy to write and maintain, while HTML is designed for displaying structured content on the web.</p>

Notice that Pandoc has converted the Markdown headings into HTML heading elements.

The Markdown:

# Learning Pandoc

became:

<h1 id="learning-pandoc">Learning Pandoc</h1>

The Markdown:

## Why Convert Markdown to HTML?

became:

<h2 id="why-convert-markdown-to-html">Why Convert Markdown to HTML?</h2>

This is the important distinction between Markdown and HTML.

Markdown is optimized for writing.

HTML is optimized for describing web documents.

Pandoc performs the translation between them.

Generate a Standalone HTML Document

The basic command produces useful HTML, but Pandoc can also create a complete standalone HTML document.

Use:

pandoc pandoc-test.md -s -o pandoc-test.html

The -s option tells Pandoc to create a standalone document.

The resulting HTML will contain the normal document structure, including elements such as:

<!DOCTYPE html>
<html>
<head>
...
</head>
<body>
...
</body>
</html>

This form is useful when you want an HTML file that can be opened independently in a browser.

Add a Title

Pandoc can also use document metadata.

Add the following to the beginning of the Markdown document:

---
title: "Learning Pandoc"
---

The document would then begin:

---
title: "Learning Pandoc"
---

# Learning Pandoc

Pandoc provides a convenient way to convert Markdown documents into HTML.

This section is called YAML front matter.

It provides metadata about the document rather than being part of the visible body of the document.

This becomes particularly useful when Markdown documents are being managed as digital assets because metadata can accompany the content.

Control Appearance with CSS

Pandoc can generate the HTML structure, but CSS can control how that structure looks.

For example, create a file named:

pandoc.css

A very simple stylesheet might contain:

body {
    max-width: 900px;
    margin: 0 auto;
    padding: 2rem;
}

h1 {
    font-size: 2.2rem;
}

h2 {
    font-size: 1.6rem;
}

p {
    line-height: 1.6;
}

Pandoc can then use the stylesheet during conversion:

pandoc pandoc-test.md -s --css=pandoc.css -o pandoc-test.html

The HTML structure remains essentially the same, but the stylesheet controls its presentation.

This separation is important.

The Markdown contains the content and structure.

The CSS contains the visual design.

Pandoc performs the conversion.

Markdown as a Content Source

This separation creates a useful publishing model:

Markdown
   │
   │ content + structure
   ▼
Pandoc
   │
   │ conversion
   ▼
HTML
   │
   │ presentation
   ▼
CSS

The same Markdown document can therefore be used to produce different outputs without rewriting the source content.

For example:

                 ┌── HTML
                 │
Markdown ── Pandoc ┼── DOCX
                 │
                 ├── PDF
                 │
                 └── EPUB

Not every output format uses exactly the same process or requires the same supporting software. HTML conversion is one of the simplest Pandoc workflows because it does not require a separate PDF typesetting system.

Preparing HTML for WordPress

Once Pandoc has produced HTML, the resulting document can be inspected before being published.

This provides an opportunity to determine whether the generated HTML works appropriately with the WordPress site.

A simple instructional page might contain HTML elements such as:

<h1>Learning Pandoc</h1>

<p>Pandoc provides a convenient way to convert Markdown documents into HTML.</p>

<h2>Why Convert Markdown to HTML?</h2>

<p>Markdown is easy to write and maintain.</p>

<ul>
<li>Create the Markdown document.</li>
<li>Run Pandoc.</li>
<li>Open the HTML file.</li>
</ul>

WordPress already understands these basic HTML elements.

Consequently, the conversion process does not require Pandoc to understand WordPress specifically.

Instead, Pandoc produces standard HTML, and WordPress can use that HTML as web content.

A More Efficient Publishing Workflow

For instructional content, the process can eventually become:

AI-generated content
        │
        ▼
Markdown source
        │
        ▼
Pandoc
        │
        ▼
Structured HTML
        │
        ▼
WordPress

This approach eliminates much of the repetitive formatting work involved in manually constructing pages.

Instead of copying individual sections into separate WordPress widgets, the complete document can be maintained as one source file.

The Markdown file can also be retained as the original content asset.

Why This Matters for Digital Asset Management

A Markdown instructional document is more than a convenient text file.

It can serve as a structured source asset containing both content and document organization.

A digital asset management system could associate the Markdown file with metadata such as:

• Title
• Subject
• Author
• Version
• Learning level
• Content type
• Publication status
• Creation date
• Revision date

The same source asset could potentially produce multiple derivatives:

                 ┌── WordPress HTML
                 │
Instructional ───┼── PDF
Markdown Asset   │
                 ├── DOCX
                 │
                 └── Other formats

This creates a distinction between the source content and its published derivatives.

The Markdown document remains the authoritative source while generated files become representations of that source for specific purposes.

Practical Exercise

Create a second Markdown file named:

pandoc-exercise.md

Write a short instructional document containing:

• One level-one heading.
• At least two level-two headings.
• Three paragraphs.
• One bulleted list.
• One numbered list.
• Bold text.
• Italic text.
• At least one hyperlink.

Convert the document with:

pandoc pandoc-exercise.md -s -o pandoc-exercise.html

Open the resulting HTML document in a browser.

Then open the HTML file in a text editor and compare the generated HTML with the original Markdown.

The objective is not simply to learn the Pandoc command.

The objective is to recognize how a relatively simple Markdown source document can describe a complete structured webpage.

The Basic Command to Remember

For straightforward Markdown-to-HTML conversion, the essential command is:

pandoc input.md -o output.html

For a complete standalone HTML document:

pandoc input.md -s -o output.html

For HTML with a CSS stylesheet:

pandoc input.md -s --css=style.css -o output.html

These three commands provide a useful foundation for experimenting with Markdown-based web publishing.

Summary

Pandoc provides a bridge between Markdown and HTML.

Markdown provides an efficient way to create and maintain structured instructional content. Pandoc converts that content into standard HTML that can be displayed by web browsers and potentially incorporated into content-management systems such as WordPress.

The resulting workflow separates content from presentation:

Markdown → content and structure

Pandoc → document conversion

HTML → web structure

CSS → visual presentation

WordPress → publication

This approach can reduce repetitive page-building work while preserving the original Markdown document as a reusable source asset.

For a larger digital asset management system, the same principle can be extended further: one authoritative instructional-content asset can potentially generate multiple publication formats while maintaining a consistent source and version history.