mduck 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+# CLI Markdown to PDF and HTML - mduck
+
+Convert Markdown files to styled HTML and PDF.
+
+## Open source notice
+
+This project is part of the [Open Collective](https://opencollective.com/simplyhexagonal) project [Simply Hexagonal](https://simplyhexagonal.org)
+and is open to updates by its users, we ensure that PRs are relevant to the community.
+In other words, if you find a bug or want a new feature, please help us by becoming one of the
+[contributors](#contributors-) ✌️ ! See the [contributing section](#contributing).
+
+## Like this module? ❤
+
+Please consider:
+
+- [Buying me a coffee](https://www.buymeacoffee.com/jeanlescure) ☕
+- Supporting me on [Patreon](https://www.patreon.com/jeanlescure) 🏆
+- Starring this repo on [Github](https://github.com/simplyhexagonal/mduck) 🌟
+
+## AI and Compliance Notice
+
+The [⛩️ OpenKai](https://openkai.org/) quality framework for AI-assisted production was used in the creation of this project, making it ISO 42001 compliant by ensuring human oversight and governance. 
+
+30% Human · 70% AI · 100% epic
+
+## Run Without Installing
+
+### `bunx`
+
+```bash
+bunx mduck convert ./notes.md
+```
+
+```bash
+bunx mduck convert ./notes.md ./dist/
+```
+
+```bash
+bunx mduck convert ./notes.md ./dist/notes.html --template ./my-template.html
+```
+
+### `npx`
+
+```bash
+npx mduck convert ./notes.md
+```
+
+```bash
+npx mduck convert ./notes.md ./dist/
+```
+
+```bash
+npx mduck convert ./notes.md ./dist/notes.html --template ./my-template.html
+```
+
+## Install Globally
+
+### With Bun
+
+```bash
+bun add -g mduck
+```
+
+### With npm
+
+```bash
+npm install -g mduck
+```
+
+Then run:
+
+```bash
+mduck --help
+```
+
+## Commands
+
+### `convert`
+
+```bash
+mduck convert <input-file> [output-file] [--template <template-path>]
+```
+
+- `<input-file>` is required.
+- `[output-file]` is optional.
+- If output is omitted, output HTML uses input path with `.html` extension.
+- If output is an existing directory, output file uses input basename + `.html`.
+- PDF is always generated next to the resolved HTML output, with `.pdf` extension.
+- `--template` (or `-t`) accepts absolute or relative path to an HTML template file.
+
+Examples:
+
+```bash
+mduck convert ./docs/readme.md
+```
+
+```bash
+mduck convert ./docs/readme.md ./output/
+```
+
+```bash
+mduck convert ./docs/readme.md ./output/custom.html
+```
+
+```bash
+mduck convert ./docs/readme.md ./output/ --template ./custom.template.html
+```
+
+### `eject-template`
+
+Write the built-in default template to disk so you can customize it.
+
+```bash
+mduck eject-template [output-template-html-path]
+```
+
+- No path: writes `./mduck.template.html`
+- File path: writes exactly there
+- Directory path: writes `mduck.template.html` in that directory
+
+Examples:
+
+```bash
+mduck eject-template
+```
+
+```bash
+mduck eject-template ./templates/
+```
+
+```bash
+mduck eject-template ./templates/my-template.html
+```
+
+## Troubleshooting
+
+### Puppeteer error: browser not found
+
+If you see an error saying Chromium/Chrome cannot be found, install Puppeteer's browser binary:
+
+```bash
+npx puppeteer browsers install chrome
+```
+
+If you use Bun:
+
+```bash
+bunx puppeteer browsers install chrome
+```
+
+## Contributing
+
+Yes, thank you! This plugin is community-driven, most of its features are from different authors.
+Please update the docs and tests and add your name to the `package.json` file.
+
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td align="center"><a href="https://jeanlescure.cr"><img src="https://avatars.githubusercontent.com/u/3330339?v=4" width="100px;" alt="Jean M. Lescure"/><br /><sub><b>Jean M. Lescure</b></sub></a><br /><a href="#maintenance-jeanlescure" title="Maintenance">🚧</a> <a href="https://github.com/simplyhexagonal/mduck/commits?author=jeanlescure" title="Code">💻</a> <a href="https://github.com/simplyhexagonal/mduck/commits?author=jeanlescure" title="Documentation">📖</a> <a href="https://github.com/simplyhexagonal/mduck/commits?author=jeanlescure" title="Tests">⚠️</a></td>
+  </tr>
+</table>
+
+<!-- markdownlint-enable -->
+<!-- prettier-ignore-end -->
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+## License
+
+Copyright (c) 2026 [mduck Contributors](https://github.com/simplyhexagonal/mduck/#contributors-).<br/>
+Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).