This is searched as a Markdown question and it is not one. A .md file has no bottom of the page, so it has nowhere to put a number. Every working answer is an instruction to the thing that makes the PDF.
Why typing the number in the file fails
The instinct is to put — 12 — at the end of a section, or to keep a running count in a footer you write by hand. That only works if the pagination never changes. Edit a paragraph on page three and every number after it is wrong, and you will not notice until someone else does.
A real page number is generated at render time from the page counter. The renderer knows it is on page twelve; the manuscript does not and should not.
Where they belong
In a book, centred in the footer, or on the outer corner if the book will be bound and you care about inner/outer. For a digital PDF that will never be printed, centred at the bottom is the default that nobody notices, which is the point of a page number.
- Footer, not header. A header is for the chapter title; a number at the top of a screen-read PDF looks like a browser print-out.
- Smaller than the body. 8 or 9 point, in the body typeface, in the body colour. It should be findable and not competing.
- Same position on every page. Switching from centre to outer corner halfway through is the tell that two templates got concatenated.
Roman numerals for front matter (i, ii, iii) and Arabic from chapter one is the traditional treatment. It is correct, and it is more machinery than most self-published books need. Starting at 1 on the first page of body text, with the cover unnumbered, is enough.
Pages that should not be numbered
A number on a cover is a mistake. It says "this is page one of a document" about a surface whose job is to be a cover. The same is true of a full-bleed back cover, and of a title page that is meant to sit like a title page rather than like the start of the text.
| Page | Numbered? |
|---|---|
| Front cover | No |
| Back cover | No |
| Title / half-title | Usually no |
| Copyright | Optional — tradition says no, a short PDF can number it |
| Contents | Yes, if the book is long enough to have one |
| Body pages | Yes |
In CSS terms this is a named page with content: none on the footer, not a number you delete by hand. In LaTeX it is \thispagestyle{empty}. In a hosted tool it is the cover being a different kind of page from the rest of the book, which is the only setup that survives a re-export.
What the common converters actually do
| Route | How you get page numbers | Cover handled? |
|---|---|---|
| Print to PDF from a preview | The browser's own header/footer — turn it off | No — you get "1" on everything |
| VS Code Markdown PDF | Via CSS @page { @bottom-center { content: counter(page) } } | Only if you write the rule |
| Pandoc + LaTeX | The document class does it; geometry and fancyhdr if you want control | Yes, with a bit of template |
| wkhtmltopdf / older headless Chrome | --footer-center [page] or a CSS footer | Rarely — covers pick up the number |
| A typesetting app with a page-number toggle | A control, not a stylesheet | Yes, if covers are first-class pages |
The CSS that actually works in a paged renderer is short:
@page {
@bottom-center {
content: counter(page);
font-size: 9pt;
}
}It does nothing in a normal browser window. It only fires when the document is being laid out as pages, which is why a live paginated preview is the only way to see the numbers before you export. Print-preview in Chrome is not the same thing: it is the browser inventing pages from a continuous document, and the numbers it stamps are its own.
Starting at a number other than 1
Sometimes you want the PDF to continue a sequence — part two of a report, or a chapter exported on its own. CSS has counter-reset: page 12 on the first page; LaTeX has \setcounter{page}{13}. Most casual converters do not expose this, and faking it by inserting blank pages at the front is how people end up with a twelve-page preface they did not write.
For a book that is one file, start at 1 and leave it. Off-by-one errors in the counter are almost always a cover that was counted as a page when it should not have been.
What this looks like in bukpress
In bukpress page numbers are a toggle. On, they sit centred in the footer at 9pt in the body typeface; off, they are gone. They are off by default, because a number on a five-page handout looks like someone forgot to turn it off, and a number on a cover looks worse. Covers use a different page than the body, so a front or back cover does not pick up a "1" or a last-page number when the toggle is on.
The live preview paginates with the same rules as the export, so you can see the footer on page seven while you are still writing page seven. There are no running headers — chapter titles in the top margin — and no roman/arabic split. For a book whose pages are A4 and whose job is to be read, the toggle is the whole feature.
If you want to see it rather than read about it, the sample book is eight pages with the footer doing exactly this.