printdown 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sota Misaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# Printdown
+
+A customizable Markdown renderer for generating beautifully styled PDFs and images with CSS.
+
+Printdown turns Markdown into clean, publication-grade PDFs, PNGs, JPEGs, and WebPs using Playwright (Chromium), markdown-it, and Shiki for syntax highlighting.
+
+## Features
+
+- **Modern Visual Language**: Clean, minimal, editorial default theme with crisp typography and vibrant accents.
+- **Multi-Format Output**: Generate A4 formatted **PDF**, high-resolution **PNG** (2x Retina), compressed **JPEG**, and modern **WebP**.
+- **Multi-Page Image Export**: Export individual page images sliced to standard PDF/A4 proportions (`--pages` or `pages: true`).
+- **Marker Pen Highlights**: Physical marker pen effect with `==text==` (blue) and `=={amber}text==` (amber).
+- **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.
+- **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.
+- **Japanese & Multilingual Typography**: Balanced typography for Japanese and English mixed documents with robust fallbacks.
+- **CLI & Node.js API**: Use via command-line interface or programmatic TypeScript/JavaScript API.
+
+## Installation
+
+```bash
+pnpm add printdown
+# or
+npm install printdown
+# or
+yarn add printdown
+```
+
+Make sure Playwright Chromium is installed:
+
+```bash
+npx playwright install chromium
+```
+
+## Quick Start
+
+### Programmatic API
+
+```typescript
+import { render, renderFile, renderPages } from "printdown";
+
+// Render a Markdown string to PDF
+await render("# Hello, world!\n\nThis is a **printdown** document with ==highlight==.", {
+  output: "document.pdf",
+});
+
+// Render a Markdown file to PNG
+const pngBuffer = await renderFile("./document.md", {
+  output: "./document.png",
+  format: "png",
+});
+
+// Render a Markdown file to WebP
+const webpBuffer = await renderFile("./document.md", {
+  output: "./document.webp",
+  format: "webp",
+});
+
+// Render into multiple page images (A4 sized pages: document-1.png, document-2.png...)
+const pageBuffers = await renderPages(markdown, {
+  output: "./document.png",
+  format: "png",
+});
+```
+
+### Command Line Interface (CLI)
+
+```bash
+# Render document.md to document.pdf (default)
+npx printdown document.md
+
+# Specify output file and format (pdf, png, jpeg, webp)
+npx printdown document.md -o output.png -f png
+npx printdown document.md -o output.webp -f webp
+
+# Export multiple page images matching PDF/A4 dimensions
+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
+
+# Apply custom CSS
+npx printdown document.md -o output.pdf --css ./custom.css
+
+# Customize width and image quality
+npx printdown document.md -o output.jpeg -f jpeg --width 1000 --quality 95
+```
+
+## Marker Pen / Highlight Syntax
+
+Printdown includes a physical marker pen style that paints a translucent accent under the lower portion of the text across multi-line breaks.
+
+### Default Blue Highlight
+
+```markdown
+This is ==essential text== highlighted in blue.
+```
+
+### Amber Highlight
+
+```markdown
+This is =={amber}warning text== highlighted in warm amber.
+```
+
+### Highlights with Inline Code
+
+```markdown
+Run ==`pnpm add printdown`== to install.
+Warning: =={amber}`sudo rm -rf /`== is destructive.
+```
+
+## Badges
+
+Printdown provides status and category badges, available via `<Badge>` HTML tags or concise Markdown syntax.
+
+### Component Syntax
+
+```markdown
+<Badge>Solid</Badge>
+<Badge variant="soft">Soft</Badge>
+<Badge variant="outline">Outline</Badge>
+
+<!-- Custom Colors (blue, amber, neutral) -->
+
+<Badge color="amber">Amber Solid</Badge>
+<Badge variant="soft" color="amber">Amber Soft</Badge>
+<Badge variant="outline" color="neutral">v1.2.0</Badge>
+```
+
+### Markdown Inline Syntax
+
+```markdown
+[badge:New]
+[badge(soft):Beta]
+[badge(outline):v1.0]
+[badge(amber):Warning]
+[badge(soft,amber):Notice]
+[badge(outline,amber):Draft]
+```
+
+## Keyboard Keys (Kbd)
+
+Display crisp, physical-styled keyboard shortcuts.
+
+### Component Syntax
+
+```markdown
+Press <Kbd icon="command" /> + <Kbd>K</Kbd> to open the command palette.
+Use <Kbd icon="arrow-up" /> or <Kbd icon="arrow-down" /> to navigate.
+<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>
+```
+
+### Supported Icons
+
+`command` (or `cmd`), `arrow-up` (or `up`), `arrow-down` (or `down`), `arrow-left` (or `left`), `arrow-right` (or `right`), `shift`, `option` (or `alt`), `enter` (or `return`).
+
+### Markdown Inline Syntax
+
+```markdown
+[kbd(command)] + [kbd:K]
+[kbd(shift)] + [kbd:Tab]
+[kbd:Enter]
+```
+
+## CSS Customization
+
+Printdown loads styles in a predictable cascade:
+
+```text
+Default Theme CSS -> User CSS
+```
+
+You can customize the appearance by overriding CSS variables or providing custom rules:
+
+```typescript
+import { render } from "printdown";
+
+await render(markdown, {
+  output: "output.pdf",
+  css: `
+    :root {
+      --printdown-primary: oklch(0.5 0.2 140);
+      --printdown-font-sans: 'Helvetica Neue', sans-serif;
+    }
+
+    .printdown h1 {
+      border-bottom: 2px solid var(--printdown-primary);
+    }
+  `,
+});
+```
+
+You can also pass a path to an external CSS file:
+
+```typescript
+await render(markdown, {
+  output: "output.pdf",
+  css: "./styles/custom.css",
+});
+```
+
+### Available CSS Variables
+
+| Variable                  | Description                                |
+| :------------------------ | :----------------------------------------- |
+| `--printdown-primary`     | Main accent color (default: Deep blue)     |
+| `--printdown-bg`          | Page background color (default: `#ffffff`) |
+| `--printdown-text`        | Body text color                            |
+| `--printdown-text-strong` | Bold and heading text color                |
+| `--printdown-text-muted`  | Subtle secondary text color                |
+| `--printdown-border`      | Border separator color                     |
+| `--printdown-font-sans`   | Sans-serif font stack                      |
+| `--printdown-font-mono`   | Monospace code font stack                  |
+
+## API Reference
+
+### `render(markdown, options)`
+
+Renders a Markdown string into a PDF, PNG, JPEG, or WebP buffer (or `Buffer[]` when `pages: true`).
+
+```typescript
+function render(markdown: string, options?: RenderOptions): Promise<Buffer | Buffer[]>;
+```
+
+#### `RenderOptions`
+
+- `output?: string`: File path to write output to. In `pages` mode, appends `-1`, `-2` or replaces `%d`.
+- `format?: 'pdf' | 'png' | 'jpeg' | 'webp'`: Target format (default inferred from `output` extension, or `'pdf'`).
+- `pages?: boolean`: Export individual page images matching PDF/A4 dimensions.
+- `pageHeight?: number`: Height in pixels for each page when in `pages` mode.
+- `pageMarginTop?: number`: Top margin in pixels for each page in `pages` mode.
+- `pageMarginBottom?: number`: Bottom margin in pixels for each page in `pages` mode.
+- `theme?: 'default' | boolean | Theme`: Theme to apply. Set to `false` to disable default theme.
+- `css?: string | string[]`: Custom CSS string or path to CSS file(s).
+- `title?: string`: HTML document `<title>`.
+- `baseUrl?: string`: Base URL / directory for resolving relative images.
+- `scale?: number`: Image resolution scale multiplier (e.g. 1 for 1x, 2 for 2x retina, 3 for 3x, default: 2).
+- `width?: number`: Viewport width in pixels (default: 820 for PDF/pages, 1200 for single image).
+- `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).
+- `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.
+
+### `renderPages(markdown, options)`
+
+Renders Markdown into an array of page image buffers.
+
+```typescript
+function renderPages(markdown: string, options?: RenderOptions): Promise<Buffer[]>;
+```
+
+### `renderFile(filePath, options)`
+
+Reads a Markdown file from disk and renders it.
+
+```typescript
+function renderFile(filePath: string, options?: RenderFileOptions): Promise<Buffer | Buffer[]>;
+```
+
+### `renderFilePages(filePath, options)`
+
+Reads a Markdown file from disk and renders it to multiple page images.
+
+```typescript
+function renderFilePages(filePath: string, options?: RenderFileOptions): Promise<Buffer[]>;
+```
+
+### `renderToHtml(markdown, options)`
+
+Compiles Markdown into an HTML document with theme and user styles without launching Chromium.
+
+```typescript
+function renderToHtml(markdown: string, options?: RenderOptions): Promise<string>;
+```
+
+## CLI Options
+
+```text
+Usage:
+  printdown <file> [options]
+
+Options:
+  -o, --output <path>         Output file path (e.g., output.pdf, output.png, output.webp)
+  -f, --format <format>       Output format (pdf, png, jpeg, webp)
+  -p, --pages                 Export multiple page images matching PDF/A4 page size
+  -s, --scale <scale>         Image resolution scale multiplier (e.g., 1, 2, 3)
+  -c, --css <path>            Path to custom CSS file or inline CSS string
+  -t, --theme <theme>         Theme to use (default: 'default', 'false' to disable)
+  --width <width>             Viewport width in pixels
+  --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
+  --quality <quality>         JPEG / WebP image quality (0-100, default: 90)
+  -v, --version               Display version number
+  -h, --help                  Display this message
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.