March 30, 2026 ・ Updated: August 18, 2026Cover Pages & Table of Contents

Written and tested by the MD Converter editorial team

How to Add a Cover Page to a Markdown PDF: 3 Practical Methods

Compare three practical ways to add a cover page to a Markdown PDF: print HTML/CSS, Pandoc include files, and a separately prepared cover PDF. Learn when each method fits and how to handle TOCs and page numbers.

Keep the cover separate from the Markdown body

There are three practical ways to add a cover to a Markdown PDF:

Add a small HTML cover and style it with print CSS.
Let Pandoc insert a separate cover file before the body.
Prepare the cover as a separate PDF and merge it with the body PDF.

In every case, the cover's first job is identification. A reader should be able to see what the document is, who produced it, when it was issued, and which revision it represents. Decorative elements come after those facts are clear.

Method	Effect on Markdown	Automation	Design freedom	Best fit
HTML and print CSS	Adds HTML elements	Good	High	HTML-based PDF workflows
Pandoc include file	Keeps body unchanged	Excellent	Depends on writer	Repeated CLI or CI builds
Merge a separate PDF	Keeps body unchanged	Limited	Highest	Formal branded covers

Method 1: use HTML and print CSS

A Markdown implementation that permits raw HTML can place a cover element before the body:

<section class="cover-page">
  <p class="cover-label">PROJECT SPECIFICATION</p>
  <h1>Payments Platform Specification</h1>
  <p>Acme Engineering</p>
  <p>Version 2.1 / April 1, 2026</p>
</section>

Use print CSS to give the element its own page:

@media print {
  .cover-page {
    box-sizing: border-box;
    min-height: 100vh;
    display: grid;
    place-content: center;
    gap: 1rem;
    text-align: center;
    break-after: page;
  }
}

Avoid adding break-before to the first body element as well; two declarations at the same boundary can produce a blank page. See CSS page breaks for Markdown PDFs for the complete print-CSS pattern.

This approach is flexible, but it will not work where raw HTML is stripped. A GitHub preview may also look different because screen rendering does not apply the same print rules as the final PDF.

Method 2: insert a cover file with Pandoc

Pandoc can insert a separate file before the document body with --include-before-body, or -B. Match that file to the output writer.

For an HTML document that will be printed to PDF:

pandoc body.md \
  --standalone \
  --include-before-body=cover.html \
  --css=print.css \
  -o document.html

For a PDF produced directly through XeLaTeX:

pandoc body.md \
  --include-before-body=cover.tex \
  --pdf-engine=xelatex \
  -o document.pdf

Do not assume that an HTML cover will work in a LaTeX PDF pipeline. Use HTML for an HTML writer and TeX for a LaTeX writer; otherwise the cover may be ignored or appear as raw markup.

This method fits specifications and reports rebuilt in CI. Passing the title, date, and revision through YAML metadata also prevents teams from copying a nearly identical cover file for every document.

Method 3: merge a separate cover PDF

If an organization already maintains an approved cover in PowerPoint, Illustrator, or Word, export that page as PDF and place it before the Markdown-generated body PDF.

This provides full control over logos, photography, and brand elements. The tradeoff is an extra assembly step and a greater risk of combining the latest body with an outdated cover.

Check the following before merging:

Cover and body use the same paper size and orientation.
Fonts are embedded in the cover PDF.
The cover occupies exactly one page.
Revision and date match the body.
Bookmarks, links, and page order survive the merge.

Choose the information that belongs on the cover

Keep only information needed to identify and control the document.

Item	Example	Decision rule
Title	API Specification	Name both the subject and document type
Subtitle	Payments Platform Renewal	Add only when the title is not distinctive enough
Organization or author	Engineering / Jane Smith	Include when ownership or contact matters
Date	April 1, 2026	Define whether this means publication or submission date
Revision	Version 2.1	Keep it synchronized with the body
Handling label	Internal	Use only when backed by an actual information policy

Long summaries, disclaimers, and chapter lists make the cover harder to scan. Put the summary at the beginning of the body and the chapter list in the table of contents.

Order the cover, TOC, and page numbers

A longer document commonly follows this sequence:

Cover
Table of contents
Body
Appendices

Whether the cover displays a page number—and whether the body can restart at page 1—depends on the PDF engine. Browser print dialogs offer limited control over numbering sections. Use Pandoc, a typesetting engine, or PDF post-processing when formal pagination is mandatory. See how to add page numbers to a Markdown PDF.

Build the TOC from the Markdown heading hierarchy rather than from the cover layout. Clear, sequential heading levels make the document navigable after the title page.

FAQ

Is it acceptable to add HTML only for the cover?

Yes, when every target renderer permits HTML and the main output is HTML-based. If the same source must work on GitHub, in a CMS, and in several converters, a separate cover file is more portable.

Can a cover include a logo or image?

Yes. Check print resolution, aspect ratio, and usage rights. A logo identifies the publisher; it should support rather than overpower the document title.

Why is there a blank page after the cover?

Check for both break-after on the cover and break-before on the first body element. A cover element slightly taller than the printable area can also spill onto another page. Follow the blank-page troubleshooting checklist.

Edit the cover separately from the Markdown body

Markdown Document Converter provides a cover editor for adjusting templates, text, shapes, and logos without adding presentation markup to the Markdown source.

Create a Markdown PDF with a cover