# Qmd Converter

> Convert PDF/EPUB documents into multi-chapter Quarto book projects using Pixi. Use when the user asks to "Convert this PDF/EPUB to a Quarto book" or "Make a qmd book from this file". Use when this capability is needed.

- Skill: `tomevault-io/qmd-converter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/qmd-converter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/qmd-converter/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/qmd-converter

---


# Quarto Book Converter

This skill converts PDF or EPUB files into a structured Quarto book project (specifically targeting the `mybook/` directory). It handles text extraction, chapter splitting, image management, and configuration updates.

## Workflow

1.  **Check Environment**:
    The script relies on `pymupdf`, `ebooklib`, `beautifulsoup4`, `pyyaml`, and `html2text`.
    **ALWAYS** check if these are installed in the current `pixi` environment before running the script.
    
    If you are unsure or if the user hasn't explicitly set up the environment, run:
    ```bash
    pixi add pymupdf ebooklib beautifulsoup4 pyyaml html2text
    ```

2.  **Execute Conversion**:
    Run the python conversion script. Assume the script is located at `scripts/convert_to_book.py` relative to this skill.
    
    ```bash
    pixi run python <path-to-skill>/scripts/convert_to_book.py <input_file_path> --output-dir mybook
    ```
    *(Replace `<input_file_path>` with the actual file path provided by the user)*

3.  **Verify Output**:
    - List files in `mybook/` to confirm `.qmd` chapters were created.
    - Check `mybook/images/` for extracted images.
    - Read `mybook/_quarto.yml` to confirm the `chapters` list was updated.

## Usage Guidelines

- **Input Files**: Ensure the user provides a valid path to a `.pdf` or `.epub` file.
- **Chapter Splitting**:
    - **EPUB**: Splits automatically based on internal structure.
    - **PDF**: Splits based on the Table of Contents (Outline). If no TOC exists, it creates a single large chapter.
- **Images**: Images are extracted to `mybook/images/` and referenced in the Markdown as `![](images/filename.ext)`.

## Troubleshooting

- **"ModuleNotFoundError"**: Run the `pixi add ...` command listed in Step 1.
- **"No chapters generated"**: The PDF might be image-only (scanned) without OCR, or the EPUB structure is non-standard.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/partrita) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->