@dkothule/md2pdf 1.0.0 → 1.0.2

package/README.md

@@ -4,244 +4,203 @@
 
 [![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:
-
-```bash
-./install-system-deps.sh
-```
+### Frictionless install (recommended)
 
-You need:
-- `pandoc`
-- a PDF engine (`xelatex` by default)
-- `librsvg` / `rsvg-convert`
-- `node` + `npm`
-- `python3`
-- Python package: `pandocfilters`
+Prerequisite: Node.js + npm installed (required to install the npm package).
 
-### 2) Install md2pdf
-
-Global npm install:
+1) Install md2pdf:
 
 ```bash
 npm i -g @dkothule/md2pdf
-python3 -m pip install pandocfilters
 ```
 
-Repo-local setup:
+2) Install runtime dependencies (system packages + `pandocfilters`):
 
 ```bash
-./setup-local-deps.sh
+md2pdf-install-system-deps
 ```
 
-## First conversion
+Use `--yes` to skip the confirmation prompt (helpful for automation):
 
 ```bash
-md2pdf /path/to/file.md
+md2pdf-install-system-deps --yes
 ```
 
-Output defaults to `/path/to/file.pdf`.
-
-Custom output:
+3) Verify:
 
 ```bash
-md2pdf /path/to/file.md -o /path/to/output.pdf
-```
-
-## CLI options
-
-```bash
-md2pdf --help
 md2pdf --version
-md2pdf --init
-md2pdf --init /path/to/config.env --force
+md2pdf --help
 ```
 
-## Where npm installs it
+`md2pdf-install-system-deps` supports macOS (Homebrew) and Debian/Ubuntu.
+Run `md2pdf-install-system-deps --help` to see options.
 
-For global install (`npm i -g @dkothule/md2pdf`):
+### Manual fallback (if helper script does not support your Linux distro)
 
-- package files: `$(npm prefix -g)/lib/node_modules/@dkothule/md2pdf`
-- executable command: `$(npm prefix -g)/bin/md2pdf`
+Install these dependencies yourself:
 
-For local project install:
+- `pandoc`
+- LaTeX PDF engine (`xelatex` default)
+- `librsvg` / `rsvg-convert`
+- `python3` + `pip`
+- `node` + `npm`
 
-- package files: `./node_modules/@dkothule/md2pdf`
-- executable shim: `./node_modules/.bin/md2pdf`
+Then install the Python dependency:
 
-## Configuration
+```bash
+python3 -m pip install pandocfilters
+```
 
-`md2pdf` loads config in this order (later overrides earlier):
+## System requirements
 
-1. `$HOME/.config/md2pdf/config.env`
-2. `<input-markdown-directory>/.md2pdfrc`
-3. `--config /path/to/config.env`
-4. environment variables
+- `pandoc`
+- LaTeX PDF engine (`xelatex` default)
+- `librsvg` / `rsvg-convert`
+- `python3`
+- `node` + `npm`
+
+## macOS Finder Quick Action (Optional)
 
-Initialize default config automatically:
+Install Finder context menu action:
 
 ```bash
-md2pdf --init
+md2pdf-install-finder-action
 ```
 
-This creates:
+Uninstall Finder context menu action:
 
-- `~/.config/md2pdf/config.env`
+```bash
+md2pdf-uninstall-finder-action
+```
 
-Initialize to a custom path:
+If Finder menu does not refresh immediately:
 
 ```bash
-md2pdf --init ./md2pdf.config.env
+killall Finder
 ```
 
-If target file already exists, re-run with `--force` to overwrite.
+After installation, right-click any `.md` file in Finder:
 
-Manual template copy (optional):
+`Quick Actions` -> `Convert Markdown to PDF`
 
-```bash
-mkdir -p ~/.config/md2pdf
-cp ./md2pdf.config.example ~/.config/md2pdf/config.env
-```
+![Finder Quick Action menu](docs/images/finder-quick-action.png)
 
-If installed globally from npm, template path is:
+## Quick start
+
+Convert Markdown to PDF (output goes beside input by default):
 
 ```bash
-$(npm root -g)/@dkothule/md2pdf/md2pdf.config.example
+md2pdf ./notes.md
 ```
 
-Example config:
+Custom output path:
 
 ```bash
-PDF_ENGINE=xelatex
-MERMAID_CONFIG=/absolute/path/to/mermaid.config.json
-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
+md2pdf ./notes.md -o ./build/notes.pdf
 ```
 
-Useful flags:
+Keep generated Mermaid assets for debugging:
 
 ```bash
-md2pdf input.md --config ./my-config.env
-md2pdf input.md --keep-mermaid-assets
-md2pdf input.md --cleanup-mermaid-assets
+md2pdf ./notes.md --keep-mermaid-assets
 ```
 
-## Mermaid temp assets
-
-When Mermaid blocks are present, md2pdf creates:
+## Mermaid support details
 
-- `<MERMAID_ASSET_PREFIX>-<run-id>-images/`
+md2pdf uses:
 
-By default, this folder is deleted after conversion (`CLEANUP_MERMAID_ASSETS=true`).
+- `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.
 
-## macOS Finder Quick Action
+## Configuration
 
-Install:
+Config precedence (later overrides earlier):
 
-```bash
-md2pdf-install-finder-action
-```
+1. `$HOME/.config/md2pdf/config.env`
+2. `<input-markdown-directory>/.md2pdfrc`
+3. `--config /path/to/config.env`
+4. Environment variables
 
-Or from repo:
+Create starter config:
 
 ```bash
-./scripts/install_md2pdf_quick_action.sh
+md2pdf --init
 ```
 
-Use in Finder:
-
-- Right click `.md` file -> `Quick Actions` -> `Convert Markdown to PDF`
-
-Remove:
+Create starter config at custom path:
 
 ```bash
-md2pdf-uninstall-finder-action
+md2pdf --init ./md2pdf.config.env --force
 ```
 
-Or from repo:
+Example config:
 
 ```bash
-./scripts/uninstall_md2pdf_quick_action.sh
+PDF_ENGINE=xelatex
+LR_MARGIN=0.7in
+TB_MARGIN=0.5in
+MERMAID_LATEX_FORMAT=svg
+MERMAID_PDF_FIT=true
+MERMAID_AUTO_PDF_FALLBACK=true
+CLEANUP_MERMAID_ASSETS=true
+MERMAID_ASSET_PREFIX=md2pdf-mermaid
 ```
 
-If menu entries do not refresh immediately:
+## CLI reference
 
 ```bash
-killall Finder
+md2pdf --help
+md2pdf --version
+md2pdf --init
 ```
 
-## Architecture and test samples
+Common options:
 
-- 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`
+- `-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)
 
-Run demo:
+## Test samples
 
-```bash
-md2pdf ./tests/architecture-smoke-test.md
-```
+- Smoke test: `tests/architecture-smoke-test.md`
+- Mermaid sample pack: `tests/samples/mermaid-all-diagram-types.md`
 
-Run the full Mermaid sample suite:
+Run:
 
 ```bash
+md2pdf ./tests/architecture-smoke-test.md
 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, md2pdf, mermaid to pdf, mermaid svg, pandoc markdown pdf, markdown pdf cli, macOS markdown pdf, Linux markdown pdf
 
 ## License
 

package/install-system-deps.sh

@@ -3,8 +3,99 @@
 # Copyright (c) 2026 Deepak Kothule
 set -euo pipefail
 
+YES=0
 OS="$(uname -s)"
 
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Install md2pdf runtime dependencies (system packages + pandocfilters).
+
+Options:
+  -y, --yes   Skip confirmation prompt and proceed immediately
+  -h, --help  Show this help message
+
+Supported platforms:
+  - macOS (Homebrew)
+  - Debian/Ubuntu Linux (apt)
+EOF
+}
+
+parse_args() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -y|--yes)
+        YES=1
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        echo "Error: unknown option: $1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+    shift
+  done
+}
+
+confirm_install() {
+  if [[ "$YES" -eq 1 ]]; then
+    return
+  fi
+
+  if [[ ! -t 0 ]]; then
+    echo "Non-interactive shell detected. Re-run with --yes to proceed." >&2
+    exit 1
+  fi
+
+  echo "This command will install system packages for md2pdf and may prompt for sudo password."
+  echo "Detected OS: $OS"
+  printf "Continue? [y/N] "
+  local response
+  read -r response
+
+  case "${response,,}" in
+    y|yes)
+      ;;
+    *)
+      echo "Aborted."
+      exit 0
+      ;;
+  esac
+}
+
+has_pandocfilters() {
+  python3 - <<'PY' >/dev/null 2>&1
+import pandocfilters
+PY
+}
+
+install_python_dependency() {
+  if has_pandocfilters; then
+    echo "Python dependency already installed: pandocfilters"
+    return
+  fi
+
+  echo "Installing Python dependency: pandocfilters"
+  if python3 -m pip install --user pandocfilters; then
+    return
+  fi
+
+  if python3 -m pip install pandocfilters --break-system-packages; then
+    return
+  fi
+
+  echo "Failed to install pandocfilters automatically." >&2
+  echo "Please install manually with one of:" >&2
+  echo "  python3 -m pip install --user pandocfilters" >&2
+  echo "  python3 -m pip install pandocfilters --break-system-packages" >&2
+  exit 1
+}
+
 install_macos() {
   if ! command -v brew >/dev/null 2>&1; then
     echo "Homebrew is required on macOS. Install from https://brew.sh and retry."
@@ -12,7 +103,11 @@ install_macos() {
   fi
 
   brew update
-  brew install pandoc librsvg node python
+  brew install pandoc librsvg python
+
+  if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+    brew install node
+  fi
 
   if ! command -v xelatex >/dev/null 2>&1; then
     echo "Installing BasicTeX for xelatex..."
@@ -26,14 +121,20 @@ install_debian_ubuntu() {
   sudo apt-get install -y \
     pandoc \
     librsvg2-bin \
-    nodejs \
-    npm \
     python3 \
     python3-venv \
     python3-pip \
+    python3-pandocfilters \
     texlive-xetex
+
+  if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+    sudo apt-get install -y nodejs npm
+  fi
 }
 
+parse_args "$@"
+confirm_install
+
 if [[ "$OS" == "Darwin" ]]; then
   install_macos
 elif [[ "$OS" == "Linux" ]]; then
@@ -49,4 +150,6 @@ else
   exit 1
 fi
 
-echo "System dependencies installed."
+install_python_dependency
+
+echo "Runtime dependencies installed."

package/package.json

@@ -1,9 +1,29 @@
 {
   "name": "@dkothule/md2pdf",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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"
   },
@@ -24,6 +44,7 @@
   ],
   "bin": {
     "md2pdf": "./bin/md2pdf",
+    "md2pdf-install-system-deps": "./install-system-deps.sh",
     "md2pdf-install-finder-action": "./scripts/install_md2pdf_quick_action.sh",
     "md2pdf-uninstall-finder-action": "./scripts/uninstall_md2pdf_quick_action.sh"
   },