Creating a Webpage with Markdown and Pandoc

Introduction

Markdown

Markdown is a special syntax for formatting text files. Unlike raw HTML, it is clean and organized when viewed as plain text.

The Markdown source code for this page may be found here.

Pandoc

Pandoc is a command-line tool that can convert pretty much every structured text format into every other.

It’s incredibly useful for all sorts of things, one of which is converting Markdown to HTML.

(It can also convert into Microsoft Word, Rich Text Files, OpenOffice ODT, PDF, LaTeX, and many more obscure or odd formats, like EMACS org-mode or Jupyter notebooks.)

Useful links to get started:

• Markdown Syntax Guide
• Pandoc Home
• Installing Pandoc

Using Markdown

Using Markdown is very simple: Simply write plain text! Save it into a file named (whatever).md, and yo’re ready to go.

Here’s the bare minimum of what you need to know:

% The document should begin with a title
% Optionally an author
% And optionally a date

# Headings begin with a #

## Subheadings begin with two #s

### Sub-subheadings begin with ###

Italic text is surrounded by *a single asterisk*

Bold text is surrounded by **two asterisks**

• * Unordered lists
• * are written
• * with leading asterisks

1. Ordered lists
2. are written
3. by numbering the lines

Links are surrounded by [square brackets](followed by the link URL)


Using Pandoc

Follow the installation instructions on the Pandoc website to get started.

Pandoc is a command-line tool, so open up a terminal, and navigate to the folder with your Markdown file.

cd /path/to/your/files/

To convert to an HTML file, run the following command:

pandoc -s -o your_file_name.html your_file_name.md

This tells pandoc:

• -s: Generate a standalone file
• -o: Output it as a file named…
• your_file_name.html: Whatever you want to call it. Will autodetect HTML from the extension.
• your_file_name.md: Your input file.

This should generate a file called your_file_name.html - This is your static HTML page!

Useful tricks

More control over style

If you’d like to apply a different style to your output, pandoc supports templates for most of its output formats.

If you’d like pandoc to print its template for a specific format, run:

pandoc -D format

For HTML:

pandoc -D html

This will print out the entire template. You can save and edit the template however you like, pandoc has online documentation here.

When you’re ready to format your pages, run:

pandoc --template template_file -o output_file input_file

The template for this website may be found here.

Pandoc expects templates to have the same extension as their associated file, so this template has a .html extension, and your browser will attempt to display it. However, it is not valid HTML, and as such will look very broken. Download the file directly to use.

Convert all markdown files in a directory to HTML

Run:

for f in *.md; do pandoc "$f" -o "${f%.md}.html"; done

Debugging

Nonempty <title> element warning

If you get the following warning:

[WARNING] This document format requires a nonempty \<title\> element.
Defaulting to 'markdown_and_pandoc' as the title.
To specify a title, use 'title' in metadata or --metadata title="...".

You need to supply a title. If you don’t care, it may be safely ignored.

Bad formatting

If your output does not have any formatting, you may have omitted the -s option on the command line. Leaving out the -s produces an HTML fragment, which can be pasted directly into another HTML page.

Documentation

If you’d like to read the Pandoc documentation in the terminal, run:

man pandoc

Next Steps

Once you have your_file_name.html, you are ready to host it on the public internet!

Check out the “Hosting a website” section of our homepage for more!