@dkothule/md2pdf 1.0.0 → 1.0.1

package/README.md

@@ -4,244 +4,170 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+`@dkothule/md2pdf` is a Markdown to PDF CLI for macOS and Linux with first-class Mermaid support.
+It keeps Mermaid diagrams sharp in PDF by rendering vector assets (SVG by default) and includes automatic fallback logic for Mermaid flowcharts/graphs when needed.
 
-## Why this tool
+## Why md2pdf
 
-- Mermaid diagrams are rendered as SVG for PDF output by default, so diagrams stay crisp at any zoom level.
-- Uses a PDF-safe Mermaid renderer config by default (`flowchart.htmlLabels=false`) to preserve diagram text in PDFs.
-- Improves flowchart edge-label readability by forcing opaque label backgrounds (prevents line strike-through in PDF output).
-- Auto-fallback for flowchart/graph diagrams: if SVG uses `foreignObject` labels, md2pdf can render Mermaid PDF for that diagram to preserve node text.
-- Mermaid PDF rendering uses fit-to-content page bounds by default (`MERMAID_PDF_FIT=true`) so diagrams do not force full-page layout.
-- Works on macOS and Linux (CLI).
-- macOS Finder Quick Action support for right-click conversion.
-- Configurable defaults via config file (PDF engine, margins, temp asset behavior, more).
-- Cleans Mermaid temp assets by default after conversion.
-
-## Package layout
-
-- `bin/`: user-facing CLI commands (`md2pdf`, Finder Quick Action installers).
-- `lib/`: internal runtime helpers (Pandoc Mermaid filter + wrapper).
-- `assets/`: bundled static assets (`table-style.tex`, `mermaid.config.json`).
-- `scripts/`: helper scripts exposed as secondary commands.
-- `tests/`: repo-only smoke tests and Mermaid samples (not published to npm).
-
-## Platform support
-
-- macOS: fully supported (CLI + Finder Quick Action).
-- Linux: supported for CLI conversion.
-- Finder context menu integration: macOS only.
+- Markdown to PDF from the terminal.
+- Mermaid to PDF with high-resolution vector rendering.
+- SVG-first pipeline for crisp diagrams at any zoom level.
+- Auto fallback to Mermaid PDF for diagrams that use `foreignObject` labels.
+- Fit-to-content PDF fallback (`--pdfFit`) to avoid full-page diagram artifacts.
+- Better edge-label readability in flowchart/graph diagrams.
+- Configurable defaults (`~/.config/md2pdf/config.env`, project `.md2pdfrc`, or `--config`).
+- Optional Finder Quick Action integration on macOS.
 
 ## Install
 
 ### 1) Install system dependencies
 
-From repo checkout:
+From repo checkout, install required tools:
 
 ```bash
 ./install-system-deps.sh
 ```
 
-You need:
+### 2) Install md2pdf CLI
+
+```bash
+npm i -g @dkothule/md2pdf
+python3 -m pip install pandocfilters
+```
+
+## System requirements
+
 - `pandoc`
-- a PDF engine (`xelatex` by default)
+- LaTeX PDF engine (`xelatex` default)
 - `librsvg` / `rsvg-convert`
-- `node` + `npm`
 - `python3`
-- Python package: `pandocfilters`
+- `node` + `npm`
 
-### 2) Install md2pdf
+## macOS Finder Quick Action (Optional)
 
-Global npm install:
+Install Finder context menu action:
 
 ```bash
-npm i -g @dkothule/md2pdf
-python3 -m pip install pandocfilters
+md2pdf-install-finder-action
 ```
 
-Repo-local setup:
+Uninstall Finder context menu action:
 
 ```bash
-./setup-local-deps.sh
+md2pdf-uninstall-finder-action
 ```
 
-## First conversion
+If Finder menu does not refresh immediately:
 
 ```bash
-md2pdf /path/to/file.md
+killall Finder
 ```
 
-Output defaults to `/path/to/file.pdf`.
+After installation, right-click any `.md` file in Finder:
+
+`Quick Actions` -> `Convert Markdown to PDF`
+
+![Finder Quick Action menu](docs/images/finder-quick-action.png)
+
+## Quick start
 
-Custom output:
+Convert Markdown to PDF (output goes beside input by default):
 
 ```bash
-md2pdf /path/to/file.md -o /path/to/output.pdf
+md2pdf ./notes.md
 ```
 
-## CLI options
+Custom output path:
 
 ```bash
-md2pdf --help
-md2pdf --version
-md2pdf --init
-md2pdf --init /path/to/config.env --force
+md2pdf ./notes.md -o ./build/notes.pdf
 ```
 
-## Where npm installs it
+Keep generated Mermaid assets for debugging:
 
-For global install (`npm i -g @dkothule/md2pdf`):
+```bash
+md2pdf ./notes.md --keep-mermaid-assets
+```
 
-- package files: `$(npm prefix -g)/lib/node_modules/@dkothule/md2pdf`
-- executable command: `$(npm prefix -g)/bin/md2pdf`
+## Mermaid support details
 
-For local project install:
+md2pdf uses:
 
-- package files: `./node_modules/@dkothule/md2pdf`
-- executable shim: `./node_modules/.bin/md2pdf`
+- `MERMAID_LATEX_FORMAT=svg` by default for vector quality in PDF.
+- `MERMAID_AUTO_PDF_FALLBACK=true` by default to preserve flowchart/graph node labels when SVG uses `foreignObject`.
+- `MERMAID_PDF_FIT=true` by default so Mermaid PDF fallback assets use tight bounds and do not force one-diagram-per-page.
 
 ## Configuration
 
-`md2pdf` loads config in this order (later overrides earlier):
+Config precedence (later overrides earlier):
 
 1. `$HOME/.config/md2pdf/config.env`
 2. `<input-markdown-directory>/.md2pdfrc`
 3. `--config /path/to/config.env`
-4. environment variables
+4. Environment variables
 
-Initialize default config automatically:
+Create starter config:
 
 ```bash
 md2pdf --init
 ```
 
-This creates:
-
-- `~/.config/md2pdf/config.env`
-
-Initialize to a custom path:
-
-```bash
-md2pdf --init ./md2pdf.config.env
-```
-
-If target file already exists, re-run with `--force` to overwrite.
-
-Manual template copy (optional):
-
-```bash
-mkdir -p ~/.config/md2pdf
-cp ./md2pdf.config.example ~/.config/md2pdf/config.env
-```
-
-If installed globally from npm, template path is:
+Create starter config at custom path:
 
 ```bash
-$(npm root -g)/@dkothule/md2pdf/md2pdf.config.example
+md2pdf --init ./md2pdf.config.env --force
 ```
 
 Example config:
 
 ```bash
 PDF_ENGINE=xelatex
-MERMAID_CONFIG=/absolute/path/to/mermaid.config.json
+LR_MARGIN=0.7in
+TB_MARGIN=0.5in
 MERMAID_LATEX_FORMAT=svg
 MERMAID_PDF_FIT=true
 MERMAID_AUTO_PDF_FALLBACK=true
-LR_MARGIN=0.7in
-TB_MARGIN=0.5in
 CLEANUP_MERMAID_ASSETS=true
 MERMAID_ASSET_PREFIX=md2pdf-mermaid
 ```
 
-Useful flags:
+## CLI reference
 
 ```bash
-md2pdf input.md --config ./my-config.env
-md2pdf input.md --keep-mermaid-assets
-md2pdf input.md --cleanup-mermaid-assets
-```
-
-## Mermaid temp assets
-
-When Mermaid blocks are present, md2pdf creates:
-
-- `<MERMAID_ASSET_PREFIX>-<run-id>-images/`
-
-By default, this folder is deleted after conversion (`CLEANUP_MERMAID_ASSETS=true`).
-
-## macOS Finder Quick Action
-
-Install:
-
-```bash
-md2pdf-install-finder-action
-```
-
-Or from repo:
-
-```bash
-./scripts/install_md2pdf_quick_action.sh
-```
-
-Use in Finder:
-
-- Right click `.md` file -> `Quick Actions` -> `Convert Markdown to PDF`
-
-Remove:
-
-```bash
-md2pdf-uninstall-finder-action
-```
-
-Or from repo:
-
-```bash
-./scripts/uninstall_md2pdf_quick_action.sh
+md2pdf --help
+md2pdf --version
+md2pdf --init
 ```
 
-If menu entries do not refresh immediately:
+Common options:
 
-```bash
-killall Finder
-```
+- `-o, --output <file>`: output PDF path
+- `--config <file>`: load additional config file
+- `--keep-mermaid-assets`: keep generated Mermaid temp files
+- `--cleanup-mermaid-assets`: remove generated Mermaid temp files (default)
 
-## Architecture and test samples
+## Test samples
 
-- Architecture doc: `docs/ARCHITECTURE.md`
-- Smoke test markdown: `tests/architecture-smoke-test.md`
-- Mermaid all-diagram sample pack: `tests/samples/mermaid-all-diagram-types.md`
+- Smoke test: `tests/architecture-smoke-test.md`
+- Mermaid sample pack: `tests/samples/mermaid-all-diagram-types.md`
 
-Run demo:
+Run:
 
 ```bash
 md2pdf ./tests/architecture-smoke-test.md
-```
-
-Run the full Mermaid sample suite:
-
-```bash
 md2pdf ./tests/samples/mermaid-all-diagram-types.md --keep-mermaid-assets
 ```
 
-## Publish (maintainer)
-
-```bash
-npm login
-npm pack --dry-run
-npm publish
-```
+## Troubleshooting
 
-Package: `@dkothule/md2pdf`
+- `mmdc not found`: install dependencies and verify `MERMAID_BIN`.
+- Flowchart/graph labels missing in PDF: keep `MERMAID_AUTO_PDF_FALLBACK=true`.
+- Diagram taking a full page: keep `MERMAID_PDF_FIT=true`.
+- PDF engine missing: install `xelatex` or set `PDF_ENGINE`.
 
-## Troubleshooting
+## Keywords
 
-- `mmdc not found`: install npm deps (`./setup-local-deps.sh`) or set `MERMAID_BIN`.
-- Flowchart/graph node labels missing in PDF: keep `MERMAID_AUTO_PDF_FALLBACK=true` (default) so affected SVG diagrams auto-fallback to Mermaid PDF per-diagram.
-- To force pure SVG only (disable fallback): set `MERMAID_AUTO_PDF_FALLBACK=false`.
-- Mermaid diagrams consuming a full page in output PDF: keep `MERMAID_PDF_FIT=true` (default) so Mermaid PDF assets use tight bounds.
-- Mermaid still generating `.svg` instead of `.pdf`: check `~/.config/md2pdf/config.env` and remove/adjust `MERMAID_LATEX_FORMAT=svg`.
-- PDF engine not found: install `xelatex` or set `PDF_ENGINE` to an installed engine.
-- Finder Quick Action not visible: run `killall Finder`.
+markdown to pdf, md to pdf, mermaid to pdf, mermaid svg, pandoc markdown pdf, markdown pdf cli, macOS markdown pdf, Linux markdown pdf
 
 ## License
 

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@dkothule/md2pdf",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Markdown to PDF converter with high-resolution Mermaid diagram rendering",
   "author": "Deepak Kothule",
   "license": "MIT",
+  "keywords": [
+    "markdown",
+    "md",
+    "pdf",
+    "markdown-to-pdf",
+    "md2pdf",
+    "mermaid",
+    "mermaid-cli",
+    "pandoc",
+    "documentation",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dkothule/md2pdf.git"
+  },
+  "homepage": "https://github.com/dkothule/md2pdf#readme",
+  "bugs": {
+    "url": "https://github.com/dkothule/md2pdf/issues"
+  },
   "publishConfig": {
     "access": "public"
   },