Written and tested by the MD Converter editorial team
How to Add Page Numbers to a Markdown PDF
Add page numbers to Markdown PDFs using print settings, CSS, or a PDF generator, including documents with covers and front matter.
After saving, verify that numbers are continuous, the body starts correctly, totals match, footer text does not overlap content, and unwanted browser URLs or dates are absent.
Add “current / total” numbering
In a paged-media engine that supports total-page counters, combine counter(page) and counter(pages) to display the current and total page counts. Recalculate after adding a cover or TOC or changing a page break.
Keep enough bottom margin for the footer. A page containing a tall table or image is the best stress test because its content reaches closer to the page edge. If the number appears too close to the body, increase the uniform margin instead of adding empty Markdown lines.
The browser's own Headers and footers option is separate. Disable it when using CSS or generator-provided page numbers, otherwise the PDF may contain two number systems plus a URL and date.
Choose a numbering policy before layout work
Decide whether the cover and TOC count toward the displayed total. A simple handout usually benefits from one continuous 1 / 7 sequence. Formal publishing requirements may call for an unnumbered cover, Roman numerals in front matter, and restarted Arabic numbers in the body. That advanced scheme requires a paged-media engine or post-processing and should be specified before the document is designed.
Do not type page numbers directly into Markdown paragraphs. Text does not know where printed pages will end, so any later edit makes those numbers incorrect. Numbering must be generated from the final pagination.
Troubleshoot missing or duplicated numbers
If no number appears, confirm that the PDF engine supports the required paged-media counters, export again, and inspect the saved PDF rather than only an editing canvas. Reset to a white page background and at least a 10 mm margin to rule out low contrast or clipping. Also check that print scaling is not enlarged.
If numbers are duplicated, turn off browser headers and footers. If the total is wrong, make sure you are opening the latest exported file and that all remote images finished loading before printing; late image sizing can change pagination.
Page-number QA checklist
- Check the first and last displayed numbers.
- Confirm that every number advances by one.
- Compare the displayed total with the PDF viewer's page count.
- Inspect pages with full-height tables and images for overlap.
- Confirm that URL, date, and browser title are not printed unexpectedly.
- Recheck numbering after moving any page break.
Refer to sections by heading name as well as page number when documents will be revised. A link such as “See Troubleshooting” survives repagination better than “See page 12” alone.
Frequently asked questions
Why does the PDF viewer count differ from “1 / n”?
Confirm whether the cover and TOC are included and whether you opened the newest export. Browser-added sheets, post-export merging, or an old cached file can produce a different viewer count.
Can the cover be left unnumbered?
A continuous document-wide count is the reliable browser workflow. Excluding front matter or restarting at one requires more advanced paged-media support or PDF post-processing. Decide whether that complexity is necessary before laying out the document.
Should the label say “Page 1 of 7” or “1 / 7”?
1 / 7 is compact and language-neutral. A worded label can be clearer in formal accessibility contexts but occupies more footer width. Use one form consistently throughout a document set.
For documents with front matter, review the Markdown PDF table of contents guide before locking the final count.