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.
oshea is built on:
markdown-it for Markdown parsing, and
puppeteer for high-quality PDF generation.
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.
Convert a basic Markdown file to PDF
oshea my-document.mdUse a built-in plugin for styling
oshea my-resume.md --plugin cvCreate a cover letter with professional formatting
oshea my-letter.md --plugin cover-letterThis tool allows you to produce high-quality and re-usable, aesthetic documents.
CV Layout |
Cover Letter Layout |
Recipe Layout |
Business Card |
Restaurant Menu |
D3.js Slide |
Install oshea globally
git clone https://github.com/brege/oshea.git
cd oshea
npm install -gUse any plugin with your markdown files:
oshea convert my-resume.md --plugin cvTake 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.
Note: The
convertcommand is implicit when a markdown file is provided. For generators (like building recipe books), the distinction betweenconvertandgeneratebecomes important.
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'This creates a complete plugin structure:
my-plugins/my-better-letter
├── .contract # schema and in-situ testing
├── my-better-letter.config.yaml # plugin configuration (page size, versioning, etc)
├── my-better-letter.css # custom CSS properties
├── my-better-letter-example.md # example file
├── index.js # handler
└── README.md # plugin description (embedded --help text)This allows for great flexibility and re-usability. Plugins are portable and can be shared across projects.
Use the helper script to build a context package for an AI prompt.
node scripts/ai/ai-context-generator.js --plugin default --filename ai-context.txtSee the AI Assisted Plugin Development Guide for more information. This uses built-in assets like the Plugin Contract, appends all plugin files, and an interaction spec to onboard and guide the AI.
The command above specifies a base plugin to archetype from, the "default" plugin, although any plugin will work. This is how the D3.js Slide was created..
The collections manager makes it easy to manage plugins and collections of plugins.
oshea collection add my-plugins
# or add individual plugins
oshea plugin add my-plugins/my-better-letterEnable plugins for use anywhere:
oshea plugin enable my-plugins/my-better-letter
# or enable entire collections
oshea collection enable my-pluginsThis workflow lets you maintain a development repository with a self-activating testing area while providing production copies for use anywhere.
Many workflows and walkthroughs are available:
- Walkthrough: A Plugin's Full Lifecycle
- Walkthrough: Customizing a Plugin with Archetyping
- Walkthrough: Updating and Syncing Plugins
- Walkthrough: Creating a Deck of Digital Notecards
Other guides:
- Batch Processing - Creating a set of PDFs from a directory of markdown files.
Alternatively, the
generatecommand is used to generate one PDF from a set of markdown files. - Plugin Development Guide - Manual configurations and complex workflows.
- Configuration Hierarchies - Nitty-gritty details on the config hierarchy and how it's used.
Cheatsheet: docs/refs/cheat-sheet.md
Dynamic Tab-completion
echo 'source <(oshea completion)' >> ~/.bashrc
source ~/.bashrcPlugin Management Commands
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 testsCollection Commands
oshea collection list # List collections
oshea collection add https://github.com/brege/oshea-plugins # Add remote collection
oshea update # Update plugins/collectionsThe project and all its documentation (and many supporting files) is all indexed by the librarian.
Each directory below has a mini-README (cf. main index.md) that links to all documentation within the directory.
The librarian, together with the postman, ensures all documentation is properly indexed and linked.
- Docs - Documentation index (guides, reference, walkthroughs, vision, development sequence)
- Linting - Scripts to improve code quality and document indexes and interlinking
- Paths - The centralized path registry used by all app, test and auxiliary modules
- Plugins - Bundled plugins, and a higher level plugin overview
- Scripts - Utility scripts (using AI, batch processing, project management, etc.)
- Tests - Unit, integration and end-to-end tests. Life cycle, smoke, and linting tests. The test framework and how to use mocha
- Config precedence:
--configflag > user~/.config/oshea/config.yaml>config.example.yaml - Plugin precedence:
--pluginflag > front matter > local*.config.yaml> default
This project has a rich testing framework. 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. The best place to start is the Test Index.
npm test
npm test -- --group collectionsYou can run the last tests that failed npm run test:last-fails. You can use the npm run test:watch command, which runs the tests in watch mode as well.
Plugins are easy to test.
oshea plugin validate my-plugins/my-better-letterThis checks if your plugin is self-activating, if the in-situ tests pass, and if the plugin's directory structure is valid, among other verifications.
Development history.
- [
v0.10] [ polish ] ← [ linting ] ← [ release candidate ] ← [ refactor ] ← [ reorg ] - [
v0.9] [ dream-board ] - [
v0.8] [ dream-board ] [ changelog ] - [
v0.7] [ dream-board ] [ changelog ] - [
v0.6(and earlier) ] [ roadmap]
This project is licensed under the MIT License.