Keep chapter content from dropping out of the PDF

[sehkone]

Supersedes #12, rebased onto main and carried the rest of the way. Squashed into one commit, with jinjoolee07 credited as co-author for the original work.

What #12 found, and what it turns out to be

The forced page break mkdocs-with-pdf puts on section + section does more than pad a subsection out to a full page. When a nav section groups several pages, the plugin emits one article of stacked section elements, and the forced break silently drops everything after each section's first paragraph from the render.

Built against a nav-grouped fixture, main produces a 5-page PDF in which a 22-row table, a 14-item list, an admonition and an 18-row table are all simply absent. With the break relaxed, the same document renders 7 pages with the content intact.

This never showed up because both samples are a single page, so mkdocs-with-pdf reports Converting 1 articles and the section + section path is never taken.

Isolated by rule:

applied to section + section	pages	chapter content
main as-is	5	dropped
min-height: auto only	5	still dropped
break-before: auto only	9	present

So the culprit is page-break-before: always, not min-height.

Changes on top of #12

Relax break-inside only. #12 also cleared break-before, but that is the declaration keeping a table or list attached to the sentence — or the bold-only label — that introduces it. Clearing it left labels such as **Key inputs** stranded at the foot of a page, which is one of the symptoms #11 lists.

Keep bordered containers whole. Under #12 as written, an admonition splits across a page boundary and renders as an open box with no left or right edge — the title bar and an empty half-box at the foot of one page, the body with no border on the next. div.admonition and div.tabbed-content--wrap keep break-inside: avoid.

Guard against lone items. Allowing a list or table to split introduces a new case: a break right after the first item, or right before the last. Guards on the first and last two list items and table rows forbid exactly those two positions, and orphans/widows bound the same case for prose and code.

Drop !important. Nothing it was competing with is !important, and article:not(#doc-cover):not(#doc-toc) … already outspecifies both the plugin's _paging.scss and styles/pdf.css. Verified: these rules win without it.

Align styles/pdf.css. It forbade the fragmentation pdf/styles.scss now allows, so browser print and PDF export broke a page at different points. The README documents that file as the PDF print guardrails, so it is aligned rather than removed.

Regression coverage

A build exiting 0 is not evidence the chapter is in the PDF — that is exactly how this bug stayed invisible. tests/pdf-test.sh gains a nav-grouped fixture whose markers are read back out of the rendered pages with pdftotext, asserting that:

• a subsection's table, list, and admonition all reach the PDF,
• a top-level chapter still starts on a page of its own,
• a subsection flows on instead of opening a padded page,
• a bold-only label keeps the first two items of its list with it, and
• a split table leaves at least two rows on the page it starts on.

Confirmed as a real control, not just a passing test: run against main's stylesheet the suite exits 1 on not ok - a subsection's list: 'option-omega' is missing, and on this branch all 22 checks pass.

Verification

check	result
all four sample PDFs (manual, api-reference × en, ko)	build clean, 8 pages each — unchanged from main
nav-grouped fixture	7 pages, no content dropped
60-item list (taller than a page)	splits 17/19/19/5, no lone item, nothing dropped
18-row table	stays on one page; without the row guard a single row is left behind
admonitions	all render whole
samples/manual	8 pages; the only movement is one list line between pages 3 and 4
markdownlint-cli2	0 issues

CHANGELOG

#12's entry predated the move to area-grouped headings, and rebasing it produced a second ## [Unreleased] section below the real one, under the abandoned ### Changed heading, plus an [Unreleased]: link this file deliberately does not carry — all without a merge conflict. It is rewritten under ## Unreleased in ### manual and ### api-reference, wrapped to 80 columns, which main now enforces since MD013: false was dropped.

Closes #11