fix: prevent orphaned headings at page breaks + improve README

- Add CondPageBreak before headings to avoid orphans at page bottom
- Wrap heading + decorators in KeepTogether for atomic rendering
- Set keepWithNext=True on all heading styles
- Add structural and integration tests for orphan prevention
- Bump version to 0.2.0
- Add CHANGELOG.md
- Improve README with badges, features section, and better structure

Thanks to @0xlaveen for identifying the orphaned heading issue in #1.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: araa47

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-03-23
+
+### Fixed
+
+- Prevent orphaned headings at page breaks — headings no longer render alone at the bottom of a page with their content flowing to the next page. Uses `CondPageBreak`, `KeepTogether`, and `keepWithNext` for robust prevention. Thanks to [@0xlaveen](https://github.com/0xlaveen) for identifying this issue and proposing the fix in [#1](https://github.com/araa47/markpdf/pull/1).
+
+### Added
+
+- Tests for heading orphan prevention (structural and integration).
+
+## [0.1.0] - 2026-03-22
+
+### Added
+
+- Initial release: markdown to PDF with light/dark themes, code blocks, tables, lists, images, blockquotes, task lists, extended formatting, and async remote image fetching.

README.md

@@ -1,32 +1,54 @@
-# markpdf
+<p align="center">
+  <img src="assets/logo.png" alt="markpdf" width="200" />
+</p>
 
-Beautiful PDFs from markdown. One command, zero config.
+<h1 align="center">markpdf</h1>
+
+<p align="center">
+  Beautiful PDFs from markdown. One command, zero config.
+</p>
+
+<p align="center">
+  <a href="https://github.com/araa47/markpdf/actions"><img src="https://img.shields.io/github/actions/workflow/status/araa47/markpdf/ci.yml?branch=main&style=flat-square" alt="CI" /></a>
+  <a href="https://pypi.org/project/markpdf"><img src="https://img.shields.io/pypi/v/markpdf?style=flat-square" alt="PyPI" /></a>
+  <a href="https://github.com/araa47/markpdf/blob/main/LICENSE"><img src="https://img.shields.io/github/license/araa47/markpdf?style=flat-square" alt="License" /></a>
+  <a href="https://pypi.org/project/markpdf"><img src="https://img.shields.io/pypi/pyversions/markpdf?style=flat-square" alt="Python" /></a>
+</p>
+
+---
 
 ```bash
 markpdf report.md
 ```
 
 ## Install
 
-Agent skill (Claude Code, Cursor, Codex, Gemini CLI):
+**Agent skill** (Claude Code, Cursor, Codex, Gemini CLI):
 
 ```bash
 npx skills add araa47/markpdf
 ```
 
-CLI:
+**CLI**:
 
 ```bash
 uv tool install git+https://github.com/araa47/markpdf
 ```
 
+Or with pip:
+
+```bash
+pip install markpdf
+```
+
 ## Usage
 
 ```bash
 markpdf report.md                        # creates report.pdf
 markpdf report.md --dark                  # dark mode
 markpdf report.md -o final.pdf            # custom output path
 markpdf report.md -k                      # keep sections on same page
+markpdf report.md -v                      # verbose output
 ```
 
 ## Output
@@ -48,13 +70,33 @@ markpdf report.md -k                      # keep sections on same page
 
 > Source: [`tests/fixtures/showcase.md`](tests/fixtures/showcase.md) | Full PDFs: [`examples/`](examples/)
 
+## Features
+
+- **Full markdown** -- headers, lists, tables, code blocks, blockquotes, images, task lists
+- **Extended syntax** -- `==highlight==`, `^super^`, `~sub~`, `~~strike~~`
+- **Light & dark themes** -- shadcn/ui zinc palette
+- **Smart page breaks** -- headings stay with their content, no orphans
+- **Remote images** fetched concurrently
+- **Async I/O** with optional uvloop
+- **Single command**, agent-friendly -- no browser, no LaTeX, no config
+
 ## Why markpdf?
 
-Most messaging apps (Slack, Discord, Teams, WhatsApp, email) don't render markdown. `markpdf` turns it into a polished PDF — no browser, no LaTeX, no config.
+Most messaging apps (Slack, Discord, Teams, WhatsApp, email) don't render markdown. `markpdf` turns it into a polished PDF -- no browser, no LaTeX, no config.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
 
-- Full markdown — headers, lists, tables, code blocks, blockquotes, images, task lists
-- Extended syntax — `==highlight==`, `^super^`, `~sub~`, `~~strike~~`
-- Light & dark themes — shadcn/ui zinc palette
-- Remote images fetched concurrently
-- Async I/O with optional uvloop
-- Single binary-style command, agent-friendly
+[MIT](LICENSE)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "markpdf"
-version = "0.1.0"
+version = "0.2.0"
 description = "Agent-friendly markdown to PDF. Beautiful docs from the terminal."
 readme = "README.md"
 license = "MIT"

src/markpdf/renderer.py

@@ -11,6 +11,7 @@
 from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
 from reportlab.lib.units import inch
 from reportlab.platypus import (
+    CondPageBreak,
     HRFlowable,
     Image,
     KeepTogether,
@@ -114,6 +115,7 @@ def create_styles(theme: dict[str, str | None]) -> dict:
                 spaceBefore=hd["sb"],
                 leading=hd["ld"],
                 fontName="Helvetica-Bold",
+                keepWithNext=True,
             )
         )
 
@@ -298,22 +300,33 @@ def build_story(
             ):
                 level = int(btype[1])
                 text = _fmt(content, theme)
-                story.append(
-                    Paragraph(text, styles[f"Heading{level}Custom"])
+                # Avoid orphaned headings: break page if insufficient space
+                story.append(CondPageBreak(1.2 * inch))
+                heading_para = Paragraph(
+                    text, styles[f"Heading{level}Custom"]
                 )
                 if level == 2:
-                    story.append(Spacer(1, 2))
                     story.append(
-                        HRFlowable(
-                            width="100%",
-                            thickness=0.5,
-                            color=colors.HexColor(theme["border"]),
-                            spaceBefore=0,
-                            spaceAfter=8,
+                        KeepTogether(
+                            [
+                                heading_para,
+                                Spacer(1, 2),
+                                HRFlowable(
+                                    width="100%",
+                                    thickness=0.5,
+                                    color=colors.HexColor(
+                                        theme["border"]
+                                    ),
+                                    spaceBefore=0,
+                                    spaceAfter=8,
+                                ),
+                            ]
                         )
                     )
                 else:
-                    story.append(Spacer(1, 4))
+                    story.append(
+                        KeepTogether([heading_para, Spacer(1, 4)])
+                    )
 
             elif btype == BLOCK_PARA:
                 story.append(

tests/test_markpdf.py

@@ -83,3 +83,57 @@ def test_empty_file(tmp_path: Path):
     result = run_markpdf(FIXTURES_DIR / "empty.md", output)
     assert result.returncode == 0
     assert output.exists()
+
+
+def test_heading_orphan_prevention():
+    """Headings should be wrapped with CondPageBreak and KeepTogether to avoid orphans."""
+    from reportlab.platypus import CondPageBreak, KeepTogether
+
+    from markpdf.parser import parse_markdown
+    from markpdf.renderer import build_story, create_styles
+    from markpdf.themes import THEME_LIGHT
+
+    md = "# Title\n\nSome text.\n\n## Section\n\nMore text.\n\n### Subsection\n\nDetails."
+    blocks = parse_markdown(md)
+    styles = create_styles(THEME_LIGHT)
+    story = build_story(blocks, styles, THEME_LIGHT, Path("."), {})
+
+    cond_breaks = [f for f in story if isinstance(f, CondPageBreak)]
+    keep_togethers = [f for f in story if isinstance(f, KeepTogether)]
+
+    # 3 headings -> 3 CondPageBreak + 3 KeepTogether (one per heading block)
+    assert len(cond_breaks) == 3, f"Expected 3 CondPageBreak, got {len(cond_breaks)}"
+    assert len(keep_togethers) >= 3, f"Expected >=3 KeepTogether, got {len(keep_togethers)}"
+
+
+def test_heading_keepwithnext_style():
+    """All heading styles should have keepWithNext=True."""
+    from markpdf.renderer import create_styles
+    from markpdf.themes import THEME_LIGHT
+
+    styles = create_styles(THEME_LIGHT)
+    for level in range(1, 7):
+        style = styles[f"Heading{level}Custom"]
+        assert style.keepWithNext is True, f"Heading{level}Custom missing keepWithNext"
+
+
+def test_heading_orphan_long_document(tmp_path: Path):
+    """A long document with many sections should produce a valid PDF with orphan prevention."""
+    # Generate a markdown document with many sections to force page breaks
+    sections = []
+    for i in range(20):
+        sections.append(f"## Section {i + 1}")
+        sections.append("")
+        # Add enough content per section to push headings near page boundaries
+        for j in range(8):
+            sections.append(f"This is paragraph {j + 1} of section {i + 1}. " * 4)
+            sections.append("")
+    md_content = "\n".join(sections)
+
+    md_file = tmp_path / "long_headings.md"
+    md_file.write_text(md_content)
+    output = tmp_path / "long_headings.pdf"
+    result = run_markpdf(md_file, output)
+    assert result.returncode == 0
+    assert output.exists()
+    assert output.stat().st_size > 1000