@brngdsn/docly

# 📄 Docly - Markdown to PDF Converter & PDF Merger **Docly** is a command-line tool that converts Markdown files into PDFs using **Puppeteer** for rendering and **Marked.js** for Markdown parsing. It also supports merging multiple PDF files into one and extracting specific pages from PDFs. Syntax highlighting for code blocks is provided by **Highlight.js**, and PDF manipulation is handled by **pdf-lib**. --- ## 🚀 Features - ✅ Convert Markdown to PDF effortlessly. - ✅ Merge multiple PDFs from a directory into one. - ✅ Extract specific pages from existing PDFs. - ✅ Supports custom sorting of PDFs during merge (default: natural numeric order). - ✅ Clean CLI interface with robust error handling. - ✅ **NEW:** Full support for images with relative paths in Markdown files. - ✅ **NEW:** Cover page support - render images as full-page front or back covers. --- ## 📦 Installation Ensure you have **Node.js 20.8.0 or higher** installed. ### 1️⃣ Install Docly globally: ```sh npm install -g docly ``` ### 2️⃣ Or, use it directly with `npx`: ```sh npx docly --help ``` --- ## 🛠 Usage ### Convert a Markdown file to PDF: ```sh docly -m input.md -p output.pdf ``` or ```sh docly --markdown input.md --pdf output.pdf ``` #### Image Support Docly now fully supports images in your Markdown files: - **Relative paths**: Images referenced with relative paths (e.g., `./images/diagram.png`) are automatically resolved relative to the Markdown file's location - **Absolute paths**: Full system paths are supported - **Web URLs**: External images from the web (http/https) work as expected - **Automatic sizing**: Images are automatically sized to fit within the PDF page width while maintaining aspect ratio - **Captions**: Regular images display their alt text as captions below the image in a smaller, italic font Example Markdown with images: ```markdown # My Document ![Figure 1: Architecture Diagram](./assets/architecture.png) ![User Interface Screenshot](../images/ui-screenshot.png) ![](./logo.png)  ![Web image](https://example.com/image.jpg) ``` **Note**: For best results, ensure your image files exist at the specified paths relative to your Markdown file. #### Cover Pages Docly supports rendering images as full-page covers: - **Front Cover**: Use `![cover:front](./cover-image.jpg)` to add a front cover - **Back Cover**: Use `![cover:back](./back-cover.jpg)` to add a back cover - Cover images are rendered on their own page with no margins - Images are cropped to fill the entire page (both width and height) - **Recommendation**: For best results, use cover directives in separate markdown files Example cover page (cover.md): ```markdown ![cover:front](./front-cover.jpg) ``` Then merge with your main document using the PDF merge feature: ```bash docly -m cover.md -p cover.pdf docly -m document.md -p document.pdf docly -g ./ -p final-book.pdf ``` ### Merge multiple PDFs into one: Provide a directory containing PDF files using the `-g` or `--group` flag. Optionally, specify a sort order with `-s` or `--sort` (`asc` or `desc`). By default, files are sorted in natural ascending order. ```sh docly -g ./pdfs -p merged.pdf ``` Example with descending sort: ```sh docly -g ./pdfs -p merged.pdf -s desc ``` ### Extract pages from a PDF: Extract specific pages from an existing PDF using the `-e` or `--extract` flag along with `-r` or `--range` to specify which pages to extract. ```sh docly -e input.pdf -r "1-3" -p output.pdf ``` Supported page range formats: - Single page: `"5"` - Page range: `"1-3"` - Multiple pages: `"1,3,5"` - Combined: `"1-3,5,7-9"` Examples: ```sh # Extract first page only docly -e document.pdf -r "1" -p first-page.pdf # Extract pages 1 through 5 docly -e document.pdf -r "1-5" -p pages1-5.pdf # Extract pages 1, 3, and 5 docly -e document.pdf -r "1,3,5" -p selected-pages.pdf # Extract pages 1-3 and 7-10 docly -e document.pdf -r "1-3,7-10" -p combined-pages.pdf ``` --- ## 🖥 Example Output ### Markdown to PDF Conversion: ```sh docly -m README.md -p output.pdf ``` **Output:** ``` Converting "README.md" to "output.pdf"... Conversion successful. ``` ### PDF Merge: ```sh docly -g ./pdfs -p "Agentic Engineering.pdf" ``` **Output:** ``` Merging PDFs from "./pdfs" into "Agentic Engineering.pdf"... Merge successful. ``` ### PDF Page Extraction: ```sh docly -e "Full Document.pdf" -r "1-3,5" -p "Selected Pages.pdf" ``` **Output:** ``` Extracting pages "1-3,5" from "Full Document.pdf" to "Selected Pages.pdf"... Extracted 4 page(s) from 10 total pages Extraction successful. ``` --- ## 🔧 Dependencies - [**Commander.js**](https://github.com/tj/commander.js) – CLI argument parsing. - [**Marked.js**](https://marked.js.org/) – Markdown to HTML conversion. - [**Puppeteer**](https://pptr.dev/) – PDF generation. - [**Highlight.js**](https://highlightjs.org/) – Syntax highlighting. - [**pdf-lib**](https://pdf-lib.js.org/) – PDF manipulation and merging. --- ## 🛠 Development Setup Clone the repo and install dependencies: ```sh git clone https://github.com/brngdsn/docly.git cd docly npm install ``` Run the CLI locally: ```sh node bin/docly.js -m test.md -p test.pdf ``` or for merging PDFs: ```sh node bin/docly.js -g ./pdfs -p merged.pdf ``` --- ## 📝 License This project is licensed under the **MIT License**. --- ## 💡 Contributing Feel free to open an issue or submit a pull request! 🚀