oshea

A Node.js command-line tool that transforms Markdown files into beautifully styled PDFs.

It features a powerful, extensible plugin system, making it incredibly versatile for creating anything from CVs and cover letters to recipe books and custom reports. Built on markdown-it for Markdown parsing and puppeteer for PDF generation.

[!TIP] The rise of AI tooling has brought enormous growth to universal Markdown usage. oshea is ideal for anyone who writes in Markdown but needs polished, professional, reproducible output for resumes, reports, presentations, and more.

See Creating Plugins with Claude Skills for building plugins with Claude or Codex.

Quick Start

Convert a basic Markdown file to PDF bash oshea my-document.md Use a built-in plugin for styling bash oshea my-resume.md --plugin cv Or through your Markdown's front matter ```

yourName: "Jane Doe" oshea_plugin: cover-letter

{{ yourName }}

Creating a cover letter with professional formatting...

```bash
oshea my-letter.md --plugin cover-letter

Gallery

CV Layout

Cover Letter Layout

Recipe Layout

Business Card

Restaurant Menu

D3.js Slide

Installation

From NPM

npm install -g oshea

From GitHub

git clone https://github.com/brege/oshea.git
cd oshea
npm install -g

Documentation

• Docs for the main documentation index
  • Guides
  • Walkthroughs
  • References
  • Historical
• Paths registry README used by all app and test modules
• Plugins bundled in the app and how to use and build them
• Scripts for an index of maintainer scripts
• Tests for integration, end-to-end, and life-cycle tests with Mocha

Working with Plugins

Use any plugin with your markdown files:

oshea convert my-resume.md --plugin cv

Take a look at the Bundled Plugins page for more examples.

Watch mode

oshea can watch for changes to your markdown and plugin files with oshea --watch.

[!TIP] The convert command is implicit when a markdown file is provided. For generators (like building recipe books), the distinction between convert and generate becomes important.

Creating Custom Plugins

To customize layouts, you can archetype from existing plugins or create a new one from scratch.

oshea plugin create --from cover-letter my-better-letter --target-dir 'my-plugins'

Plugin structure

my-plugins/my-better-letter
├── .contract                       schema and in-situ testing
├── default.yaml                    plugin configuration (metadata and defaults)
├── style.css                       custom CSS properties
├── example.md                      example file
├── index.js                        handler
└── README.md                       plugin description (embedded --help text)

Plugins are portable and can be shared across projects. See Bundled Plugins index for more information.

Creating Plugins with Claude and Codex Skills

Use the skill-first workflow documented in the Claude Skills Guide. The technical contract that agents compose plugins from is in: Plugin Contract, AI Interaction Specification, and Archetyping Walkthrough.

Iterate with your agent on the plugin until your document is satisfactory. As of February 2026, this process takes about 5 minutes.

Usage & Commands

Cheat Sheet

See Cheat Sheet for many, many examples.

Tab-completion

echo 'source <(oshea completion)' >> ~/.bashrc
source ~/.bashrc

Managing Plugins

oshea plugin help cv              # plugin-specific help
oshea plugin list                 # list all plugins (add --short for brief)
oshea plugin validate my-plugin   # validate plugin structure and tests

Installing Plugins

Install a local plugin

oshea plugin add ./my-plugin

Install a plugin from GitHub

oshea plugin add https://github.com/user/my-plugin

See the Plugins Index for more information. There is also an index of known external plugins at github.com/brege/oshea-plugins.

Testing

This project has a rich testing framework based on its .mocharc.js. In addition to the in-situ tests bundled with each plugin, there are over 300 tests, ranging from unit, integration, end-to-end, and lifecycle tests, in a declarative, manifest-driven harness and factory mocking system.

See the Test Index for all test suite documentation.

License

MIT License