How to Convert Markdown Files to HTML in Linux Terminal Using pandoc

Markdown has become the universally adopted markup standard for software documentation, technical blogging, personal note-taking, and README files. However, sharing documents with non-technical colleagues, publishing web content, or embedding formatted text into web portals requires clean, valid HTML markup.

In the Linux command-line ecosystem, pandoc is widely celebrated as the “Swiss Army knife” of document conversion. Capable of translating dozens of markup syntaxes, pandoc effortlessly converts CommonMark, GitHub-flavoured Markdown, and custom frontmatter into lightweight HTML snippets or complete, standalone HTML5 web pages with embedded CSS stylesheets.

Installing Pandoc on Linux Distributions

Pandoc is available directly from the standard repositories of virtually every major Linux distribution:

Ubuntu, Debian, and Linux Mint

sudo apt update && sudo apt install -y pandoc

Fedora, RHEL, and Rocky Linux

sudo dnf install -y pandoc

Arch Linux and Manjaro

sudo pacman -S pandoc-cli

To verify successful installation and inspect supported extensions, execute:

pandoc --version

Converting a Markdown File to an HTML Fragment

By default, when you execute pandoc with an input Markdown file and output to HTML, it produces an HTML body fragment containing solely your formatted paragraph tags (such as <h1>, <p>, and <ul>) without surrounding <html> or <head> wrappers. This is ideal for copying formatted content into content management systems or static site generator templates:

pandoc input.md -o output.html

To view the converted HTML output directly in your terminal standard output (stdout):

pandoc input.md -t html

Creating a Complete, Standalone HTML5 Web Page

If you want to view the resulting HTML file in a web browser as an independent, fully compliant web document, pass the -s (or --standalone) flag. Pandoc will automatically construct the complete document skeleton, including <!DOCTYPE html>, character set declarations, and responsive viewport meta tags:

pandoc -s input.md -o document.html

Adding a Custom Web Page Title

When compiling a standalone page, define the browser tab title using the --metadata flag:

pandoc -s --metadata title="Project Architecture Guide" input.md -o document.html

Styling the HTML Output with External CSS

Unstyled HTML pages render with plain browser defaults. To link a clean external stylesheet (such as GitHub Markdown CSS or your organisation’s brand stylesheet), supply the -c (or --css) parameter:

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

Pandoc inserts a standard <link rel="stylesheet" href="style.css" /> element directly inside the generated <head> section.

Generating a Dynamic Table of Contents

For extensive technical guides and academic documentation, pandoc can automatically parse your Markdown heading hierarchy (#, ##, ###) and compile a hyperlinked table of contents at the beginning of the web page:

pandoc -s --toc --toc-depth=3 input.md -o guide.html

The --toc-depth=3 argument instructs pandoc to index up to H3 subsections, rendering an interactive nested list that allows readers to jump directly to any document chapter.

Batch Converting Multiple Markdown Files

If you manage a repository containing numerous Markdown documents and need to batch convert them all into HTML simultaneously, leverage a concise Bash shell loop:

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

This automated loop converts every Markdown file in the active directory into a matching standalone HTML document in seconds.