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
• Instaling 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!

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!