marknative-skill 0.1.0

package/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: marknative
+description: Render Markdown files to paginated PNG/SVG images using the marknative CLI. Use this skill whenever asked to convert, render, or export Markdown to image formats.
+metadata:
+  author: liyown
+  homepage: https://github.com/liyown/marknative
+  source: https://github.com/liyown/marknative/tree/main/packages/marknative-skill
+user-invocable: false
+---
+
+# marknative — Markdown to PNG/SVG renderer
+
+`marknative` renders Markdown (CommonMark + GFM + LaTeX math) to paginated PNG or SVG pages without a browser. Runs entirely server-side via skia-canvas.
+
+## Installation
+
+```bash
+npm install -g marknative
+# or run without installing:
+npx marknative <file.md>
+```
+
+## Basic usage
+
+```bash
+# Render file → page-01.png, page-02.png … next to the source
+marknative README.md
+
+# Write to a directory
+marknative README.md -o out/
+
+# Single output file
+marknative README.md -o README.png
+
+# SVG output
+marknative README.md -f svg -o diagram.svg
+
+# Pipe from stdin
+cat notes.md | marknative -o preview.png
+echo "# Hello" | marknative -f svg
+```
+
+## All flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--format <fmt>` | `-f` | `png` | Output format: `png` or `svg` |
+| `--output <path>` | `-o` | next to input | File path or directory. Trailing `/` forces directory |
+| `--theme <name\|json>` | `-t` | `light` | Built-in theme name or JSON ThemeOverrides object |
+| `--scale <n>` | `-s` | `2` | PNG pixel-density multiplier (1=fast, 2=default, 3=high-res) |
+| `--single-page` | | `false` | Render all content into one image (no pagination) |
+| `--code-theme <t>` | | auto | Shiki theme for code blocks |
+| `--json` | | `false` | Print JSON manifest instead of file paths |
+| `--help` | `-h` | | Show help |
+
+**Built-in themes:** `light`, `dark`, `github`, `solarized`, `sepia`, `rose`, `nord`, `dracula`, `ocean`, `forest`
+
+## JSON mode — for agents and scripts
+
+```bash
+marknative report.md --json
+```
+
+```json
+{
+  "pages": [
+    { "index": 1, "path": "/abs/path/report-01.png", "format": "png" },
+    { "index": 2, "path": "/abs/path/report-02.png", "format": "png" }
+  ]
+}
+```
+
+Extract paths:
+
+```bash
+marknative report.md --json | jq -r '.pages[].path'
+marknative report.md --json | jq -r '.pages[0].path'
+```
+
+## Output path rules
+
+- **No `--output`**: file placed next to input, or `cwd` when reading stdin
+- **`--output` with extension, single page**: written to that exact path
+- **`--output` without extension or trailing `/`**: directory mode — files named `<stem>-01.png`, `<stem>-02.png`, …
+- **SVG single-page + no `--output`**: SVG written to stdout
+
+## Performance
+
+| `--scale` | Time/page | Use case |
+|-----------|-----------|----------|
+| `1` | ~29 ms | Quick preview |
+| `2` | ~99 ms | Default (screen quality) |
+| `3` | ~214 ms | High-res / print |
+
+First render per process is slower (~1–3 s) due to skia-canvas, MathJax, and Shiki cold-start.
+
+## Common patterns
+
+```bash
+# Quick preview
+marknative doc.md -s 1 -o /tmp/preview.png
+
+# Dark theme, single page
+marknative slide.md -t dark --single-page -o slide.png
+
+# High-res export
+marknative doc.md -s 3 -o print/
+
+# Custom JSON theme
+marknative doc.md -t '{"colors":{"background":"#1e1e2e","text":"#cdd6f4"}}'
+
+# SVG to PDF via pipe
+marknative doc.md -f svg | rsvg-convert -o doc.pdf
+
+# Render from stdin, JSON output
+echo "# Title\n\nContent" | marknative --json -o /tmp/out/
+```
+
+## Math support
+
+LaTeX via MathJax — inline `$E = mc^2$` and block `$$\sum_{i=1}^n i$$` both work.
+
+## Programmatic API (Node.js / Bun)
+
+```typescript
+import { renderMarkdown } from 'marknative'
+
+const pages = await renderMarkdown(markdownString, {
+  format: 'png',
+  scale: 2,
+  singlePage: false,
+  theme: 'dark',
+  codeHighlighting: { theme: 'github-dark' },
+})
+// pages: Array<{ format: 'png'|'svg', data: Buffer|string }>
+```
+
+## Gotchas
+
+- `--output` without extension → treated as **directory**, not a file
+- Page numbers are zero-padded: `page-01.png`, not `page-1.png`
+- SVG produces one file per page when `--output` is a directory
+- Cold-start adds ~1–3 s to the very first render call per process

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "marknative-skill",
+  "version": "0.1.0",
+  "description": "Claude Code skill for marknative — teaches agents how to render Markdown to PNG/SVG via CLI",
+  "license": "MIT",
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skill",
+    "marknative",
+    "markdown",
+    "render",
+    "png",
+    "svg"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liyown/marknative.git",
+    "directory": "packages/marknative-skill"
+  },
+  "homepage": "https://github.com/liyown/marknative#readme",
+  "bugs": {
+    "url": "https://github.com/liyown/marknative/issues"
+  }
+}