Building a website in Markdown with Pandoc
Fast Web

© Lead Image © Martin Blech, Fotolia.com
Build a simple web page in Markdown; then convert it to HTML at the command line.
Creating a website is a lot of trouble – especially if you just have a few files you wish to publish online. You could type in all the HTML codes by hand, or you could employ a graphic design tool that looks simple but still might be more effort than you want to spend.
Another easier option is to use Pandoc [1]. Pandoc is a universal document converter. You can give Pandoc a text file in any of several markup formats, and it will convert the document to any of several output formats. One common scenario is to format a text file using the simple and expressive Markdown markup language and then use Pandoc to convert the file to an HTML page. Pandoc is a command-line tool, so it allows you to convert a file to HTML in a single command. A collection of command-line options lets you add extra features to the web page, such as a footer bar or a rudimentary navigation menu. With the right libraries, Pandoc can even read programming languages.
You wouldn't want to use Pandoc for a complex site with interactive features and a backend database, but if you are just looking for a quick-and-dirty tool for publishing text to the web, Pandoc is a very good option. For instance, some organizations use Pandoc in situations where there is a need to maintain documentation that is accessible from the command line but still easily convertible to HTML.
Markdown Magic
The scenario begins with a text file in Markdown format. This article is not intended as an introduction to Markdown, but if you're looking for a primer, you'll find several cheat sheets and tutorials online [2]. Listing 1 shows a sample Markdown file. As you can see, the format is largely self-explanatory.
Listing 1
Sample index.md
01 # Escape Mundane Life 02 03 On this website, you will never be ~~BORED~~! 04 05 ## Fun Jokes 06 07 Well, come up with something yourself! 08 09 ## Pure science 10 11 The best way to get to the truth about werewolfs! 12 13 | Moon phase | Phang size | Measurement time | Result | 14 | --- | --- | --- | --- | 15 | New Moon | 0.1 | 00:14 | Skinny | 16 | Waxing Crescent | 0.2 | 00:21 | Skinny | 17 | First Quarter | 0.6 | 00:09 | Normal | 18 | Waxing Gibbous | 2.3 | 00:32 | Strong | 19 | Full | 9.3 | 00:19 | Bulky | 20 | Waning Gibbous | 6.1 | 00:59 | Dirty | 21 | Third Quarter | 0.8 | 02:01 | Flappy | 22 | Waning Crescent | 0.2 | 00:01 | Skinny | 23 | | | | | 24 25 26 --- 27 28 ``` 29 { 30 "Human name": "Ben"; 31 "Wolf Name": "Slasher"; 32 "age": "32" 33 } 34 ``` 35 36 > Conclusion 37 > Ben is a *Werewolf* who should build his human body! [^1] 38 39 ## A link to the city. 40 41 - Some Pictures! 42 1. A bustling City! 43 44  45 46 2. Chilling in the bay! 47 48  49 --- 50 51 [^1]: Ben is fictive name. 52 <C>
You will quickly notice Markdown features such as headings (with #
for a top heading and ##
for a second-level subhead). Double tilde makes the text strikeout. You can also make tables with a simple combination of pipes |
and dashes -
.
To convert the Markdown text in Listing 1 to an HTML page, run the standard Pandoc command:
$ pandoc -t html index.md -o index.html
Pandoc outputs to standard output unless you specify an output file with the -o
parameter.
Structure
Your Pandoc-generated website will be simple and relatively sparse, but you will still want to be methodical about keeping it organized. Pandoc only generates one page at a time, so to reduce clutter and confusion, set up a basic directory structure for your source files – something like in Figure 1.

In the src/
directory, put your index.md
, about.md
, and other Markdown files you will convert to HTML for your site.
Options
The pandoc
command has many additional options. By default, Pandoc creates document fragments. If you would like to output a standalone HTML document (with <head> and <body> sections), use the -s
or --standalone
option. The --standalone
flag supports some other options for where to locate text:
- -H --include-in-header= - -B --include-before-body= - -A --include-after-body=
A CSS file is required when generating an ePub but is optional for simple, standalone pages.
If you want to maintain your site using many files, you can list all the files as input and output straight to one file.
pandoc *.md -o index.html
This command will process all the .md
files in the order they would have been listed by ls
. In most situations, you will want more control over where the content falls within the output file, so processing the files in ls
sort order has some complications – you might want to consider more sophisticated techniques.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.
News
-
Red Hat Migrates RHEL from Xorg to Wayland
If you've been wondering when Xorg will finally be a thing of the past, wonder no more, as Red Hat has made it clear.
-
PipeWire 1.0 Officially Released
PipeWire was created to take the place of the oft-troubled PulseAudio and has finally reached the 1.0 status as a major update with plenty of improvements and the usual bug fixes.
-
Rocky Linux 9.3 Available for Download
The latest version of the RHEL alternative is now available and brings back cloud and container images for ppc64le along with plenty of new features and fixes.
-
Ubuntu Budgie Shifts How to Tackle Wayland
Ubuntu Budgie has yet to make the switch to Wayland but with a change in approaches, they're finally on track to making it happen.
-
TUXEDO's New Ultraportable Linux Workstation Released
The TUXEDO Pulse 14 blends portability with power, thanks to the AMD Ryzen 7 7840HS CPU.
-
AlmaLinux Will No Longer Be "Just Another RHEL Clone"
With the release of AlmaLinux 9.3, the distribution will be built entirely from upstream sources.
-
elementary OS 8 Has a Big Surprise in Store
When elementary OS 8 finally arrives, it will not only be based on Ubuntu 24.04 but it will also default to Wayland for better performance and security.
-
OpenELA Releases Enterprise Linux Source Code
With Red Hat restricting the source for RHEL, it was only a matter of time before those who depended on that source struck out on their own.
-
StripedFly Malware Hiding in Plain Sight as a Cryptocurrency Miner
A rather deceptive piece of malware has infected 1 million Windows and Linux hosts since 2017.
-
Experimental Wayland Support Planned for Linux Mint 21.3
As with most Linux distributions, the migration to Wayland is in full force. While some distributions have already made the move, Linux Mint has been a bit slower to do so.