printdown 1.1.1 → 1.2.0

package/README.md

@@ -13,6 +13,7 @@ Printdown turns Markdown into clean, publication-grade PDFs, PNGs, JPEGs, and We
 - **Badges & Labels**: Badges with `<Badge>` / `[badge:...]` supporting `solid`, `soft`, and `outline` variants.
 - **Keyboard Keys**: Styled keyboard keys with `<Kbd icon="command" />` / `[kbd:...]` and embedded icon masks.
 - **Center Alignment**: Center text, headings, or blocks with `::: center`, `-> text <-`, `<center>`, or `[center:...]`.
+- **Page Breaks**: Force page breaks in PDFs using `<!-- pagebreak -->`, `\pagebreak`, `[pagebreak]`, `<pagebreak />`, or `{.page-break}` on headings.
 - **Heading Border Control**: Remove underline/border from individual headings using `{.no-border}` or `{-}`.
 - **Code Highlighting**: Syntax highlighting powered by **Shiki** with dark theme support.
 - **Custom CSS & Variables**: Full control over styling by overriding OKLCH CSS variables or injecting custom CSS.
@@ -82,6 +83,10 @@ npx printdown document.md -o page.png -f png --pages
 # Set image output scale (e.g. 1x, 2x, 3x)
 npx printdown document.md -o output-3x.png -f png --scale 3
 
+# Add headers, footers, and page numbers
+npx printdown document.md --header "My Document | {date}" -n
+npx printdown document.md --footer "Confidential | Page {page} of {total}"
+
 # Apply custom CSS
 npx printdown document.md -o output.pdf --css ./custom.css
 
@@ -236,6 +241,167 @@ In Printdown's default theme, `h1` has a bottom border/underline. You can remove
 <h1 no-border>Title Without Underline</h1>
 ```
 
+## Page Breaks (PDF & Print)
+
+Printdown supports manual page breaks in PDF output:
+
+### Standalone Page Break Syntax
+
+```markdown
+Page 1 Content...
+
+<!-- pagebreak -->
+
+Page 2 Content...
+```
+
+You can also use any of the following equivalents:
+
+```markdown
+\pagebreak
+\newpage
+[pagebreak]
+<pagebreak />
+```
+
+### Container Block Syntax
+
+```markdown
+::: pagebreak
+:::
+```
+
+### Heading Page Break Attribute
+
+Force a heading to always start at the top of a new page:
+
+```markdown
+# Next Chapter {.page-break}
+
+# Section Title {.break-before}
+```
+
+## Cover Pages
+
+Printdown provides a built-in cover page generator that automatically formats a full-page cover with vertically and horizontally centered typography, optional metadata, and automatic page breaks.
+
+### Container Block Syntax
+
+```markdown
+::: cover
+
+# Document Title
+
+A concise subtitle or description of the document
+
+[badge(soft):Official Guide] [badge(soft,amber):v1.1.2]
+
+::: cover-meta
+**Author**: Engineering Team  
+**Date**: 2026-08-30  
+**Status**: Ready for Review
+:::
+:::
+```
+
+### HTML Tag Syntax
+
+```markdown
+<cover>
+
+# Technical Proposal
+
+Subheading description
+
+<div class="printdown-cover-meta">
+<strong>Author</strong>: Architecture Team
+</div>
+</cover>
+```
+
+## Mathematical Formulas (KaTeX)
+
+Printdown includes built-in math formula typesetting powered by KaTeX, preloaded with KaTeX web fonts for offline and fast rendering.
+
+### Inline Math
+
+Use `$ ... $` or `\( ... \)` for inline formulas:
+
+```markdown
+The mass-energy equivalence is defined as $E = mc^2$.
+Euler's formula states that \(e^{i\pi} + 1 = 0\).
+```
+
+### Display / Block Math
+
+Use `$$ ... $$` for display equations:
+
+```markdown
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+```
+
+### Fenced Code Blocks & Container Syntax
+
+You can also use `math` or `latex` code blocks:
+
+````markdown
+```math
+f(x) = \sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!} (x - a)^n
+```
+````
+
+Or container blocks:
+
+```markdown
+::: math
+\mathbf{F} = m \mathbf{a}
+:::
+```
+
+## Headers, Footers & Page Numbers
+
+Printdown supports configurable headers, footers, and page numbers for PDF generation and multi-page image exports.
+
+### Template Placeholders
+
+- `{page}`: Current page number
+- `{total}` or `{totalPages}`: Total number of pages
+- `{title}`: Document title
+- `{date}`: Formatted print date
+
+Use the `|` delimiter to create multi-column layouts (e.g. `Left | Right` or `Left | Center | Right`).
+
+### Programmatic Usage
+
+```typescript
+import { render } from "printdown";
+
+await render(markdown, {
+  output: "document.pdf",
+  // Simple header and footer
+  header: "Project Specification | {date}",
+  footer: "Confidential | Page {page} of {total}",
+});
+
+// Shortcut for page numbers
+await render(markdown, {
+  output: "document.pdf",
+  pageNumber: true, // Displays "{page} / {total}" centered in footer
+});
+```
+
+### CLI Usage
+
+```bash
+# Add header with date and page numbers in footer
+npx printdown report.md --header "Report Title | {date}" -n
+
+# Custom footer format
+npx printdown report.md --footer "Confidential | Page {page} of {total}"
+```
+
 ## CSS Customization
 
 Printdown loads styles in a predictable cascade:
@@ -313,6 +479,12 @@ function render(markdown: string, options?: RenderOptions): Promise<Buffer | Buf
 - `height?: number`: Viewport height in pixels (default: 800).
 - `deviceScaleFactor?: number`: Alias for `scale`.
 - `quality?: number`: Quality for JPEG and WebP output (0-100, default: 90).
+- `header?: string | boolean`: Header text/template for PDF and multi-page output.
+- `footer?: string | boolean`: Footer text/template for PDF and multi-page output.
+- `pageNumber?: boolean | string`: Shortcut to enable page numbers in footer.
+- `headerTemplate?: string`: Raw HTML header template for PDF output.
+- `footerTemplate?: string`: Raw HTML footer template for PDF output.
+- `displayHeaderFooter?: boolean`: Whether to show header and footer in PDF.
 - `pdf?: PDFExportOptions`: Playwright PDF options (margin, format, landscape, etc.).
 - `image?: ImageExportOptions`: Playwright screenshot options (fullPage, clip, etc.).
 - `markdown?: MarkdownRenderOptions`: Markdown parser and Shiki highlighter options.
@@ -366,6 +538,11 @@ Options:
   --page-height <height>      Page height in pixels for pages mode
   --margin-top <margin>       Top margin in pixels for pages mode
   --margin-bottom <margin>    Bottom margin in pixels for pages mode
+  --header <text>             Header text (supports {title}, {date}, {page}, {total}, and |)
+  --footer <text>             Footer text (supports {title}, {date}, {page}, {total}, and |)
+  -n, --page-number [format]  Show page number in footer (e.g., -n or -n 'Page {page} of {total}')
+  --header-template <html>    Custom HTML template for PDF print header
+  --footer-template <html>    Custom HTML template for PDF print footer
   --quality <quality>         JPEG / WebP image quality (0-100, default: 90)
   -v, --version               Display version number
   -h, --help                  Display this message