marp2pptx 0.1.0__tar.gz

marp2pptx-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: marp2pptx
+Version: 0.1.0
+Summary: Convert Marp Markdown files to polished PPTX presentations
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: requests>=2.32.5
+
+### Marp PPTX Post-Processing: Status & Next Steps
+
+#### 1. Marp HTML Structure (Key Concepts)
+
+**Slides:**
+- Each slide is represented by a `<svg data-marpit-svg ...>` element.
+- Inside each SVG, there are one or more layers, each as a `<foreignObject>` with width/height attributes.
+- Each `<foreignObject>` contains a `<section>` element, which holds the content for that layer.
+
+**Headers:**
+- If a slide has a header, a `<header>` element is placed under the `<section>` element.
+- Split background images are never placed in the header.
+
+**Marpit Advanced Backgrounds:**
+- Advanced backgrounds (true and split) are always placed in a `<div data-marpit-advanced-background-container="true">`.
+- This div can contain one or more `<figure>` elements, each with a background image.
+- The direction (horizontal/vertical) is set by `data-marpit-advanced-background-direction`.
+- Split backgrounds are indicated by attributes like `data-marpit-advanced-background-split` on the `<section>`.
+
+#### 2. What We're Trying to Achieve
+
+We want to post-process a Marp-exported PowerPoint (`.pptx`) so that all background images specified with Marp’s advanced image syntax are visually correct in the exported `.pptx`. This includes:
+
+- **True backgrounds** (`![bg](...)`): Fill the slide, appear behind content, and match Marp’s CSS background-size/position logic (cover, contain, auto, etc.).
+- **Multiple backgrounds** (`![bg](...)` x N, with `horizontal`/`vertical`): Stack images in the correct order and direction, matching Marp’s advanced backgrounds.
+   - **Split backgrounds** (`![bg left]`, `![bg right]`, `![bg left:33%]`, etc.): Place the image as a foreground element in a defined region (not as a slide-wide background), shrinking the content area as Marp does. Only `left` and `right` split directions are supported (not `top` or `bottom`).
+- **Cropping and placement**: All cropping, scaling, and placement (e.g., `right:35%`, `left:38% 70%`, `w:100% h:50%`) should visually match Marp’s HTML/PDF output.
+
+Reference: [Marpit image syntax documentation](https://marpit.marp.app/image-syntax)
+
+----
+
+#### 3. What We've Done So Far
+
+- **HTML Parsing:**
+   - The script parses Marp HTML output, extracting slide backgrounds, split info, image URLs, and layout instructions, by walking the SVG/foreignObject/section/container/figure structure.
+   - It builds a slide model for PPTX generation, replacing the old markdown/image logic.
+
+- **True Backgrounds & Multiple Backgrounds:**
+   - Images fill the slide or are stacked horizontally/vertically, matching Marp's stacking logic.
+
+- **Advanced Background Scaling:**
+   - Implemented full support for Marp's `background-size` property, parsed from the generated HTML.
+   - **Supported keywords**: `cover` (fills the area, cropping if necessary), `contain` and `fit` (scales to fit within the area), `auto` (uses original image size), and percentage values (e.g., `50%`, which scales the image relative to the container).
+
+- **Split Backgrounds:**
+   - Split backgrounds (left, right, with percentage) are placed in the correct region and cropped to fill only the split space. Only `left` and `right` split directions are supported.
+   - Multiple images in a split region are distributed equally within the split space (always horizontally), matching Marp's stacking logic.
+
+- **Debugging and Logging:**
+   - Extensive debug logging shows all image shapes, sizes, and the matching process for troubleshooting.
+
+- **Robust Image Mapping**: Refactored the processing logic to map all images from the Marp HTML (including headers, content, and backgrounds) one-to-one with the picture shapes in the PPTX slide. This ensures that transformations are applied *only* to the correct background shapes, preventing unintended modifications to other images on the slide.
+
+----
+
+### 4. CLI & Pipeline Automation
+
+The script has been refactored into a full command-line interface to automate the entire Marp to post-processed PPTX pipeline.
+
+- **End-to-End Automation**: The script now orchestrates the three main steps of the conversion process:
+    1.  **HTML Generation**: It calls `npx @marp-team/marp-cli` to convert the source Markdown file into an HTML file.
+    2.  **Initial PPTX Generation**: It uses the same CLI tool to create a raw, editable PPTX file (`*_raw.pptx`).
+    3.  **Post-Processing**: It runs the existing background image processing logic on the generated HTML and raw PPTX files.
+- **File Management**:
+    - **Smart Naming**: Automatically creates an intermediate `_raw.pptx` file and saves the final output as `<input_name>.pptx`.
+    - **Automatic Cleanup**: Deletes the intermediate HTML and `_raw.pptx` files by default to keep the workspace clean.
+    - **Keep Intermediates**: A `--debug` flag is available to prevent cleanup for debugging purposes.
+- **Improved Usability**:
+    - **CLI Arguments**: The script now uses `argparse` for robust handling of command-line arguments, including the input file, output file, and other options.
+    - **Help Documentation**: A `--help` command provides clear instructions on how to use the script and its available options.
+    - **Enhanced Typing**: Static typing has been improved throughout the codebase for better maintainability and reliability.
+
+----
+
+### 5. Testing
+
+The new CLI simplifies testing significantly. To process a Marp Markdown file, run the script with the input file path.
+
+Set the name of the Marp markdown file:
+```powershell
+$MARP_MARKDOWN_FILE = "sample.marp.md"
+```
+
+Run the end-to-end processing pipeline with a single command:
+```powershell
+uv run marp_pptx_postprocess.py ./${MARP_MARKDOWN_FILE}
+```
+
+The script will handle the intermediate steps and produce a final, post-processed PPTX file named `sample.marp.pptx`.
+
+To inspect the final output:
+```powershell
+explorer "${MARP_MARKDOWN_FILE}.pptx"
+```
+
+To run the pipeline and keep the intermediate files for debugging:
+```powershell
+uv run marp_pptx_postprocess.py ./${MARP_MARKDOWN_FILE} --debug
+```
+
+This will leave the following files for inspection:
+- `${MARP_MARKDOWN_FILE}.html`
+- `${MARP_MARKDOWN_FILE}_raw.pptx`
+- `${MARP_MARKDOWN_FILE}.pptx` (final output)
+
+----
+
+### 6. Next Steps (Advanced Placement)
+
+#### Recent Progress
+- Implemented a fix to widen all text boxes by 4cm (1133 pixels) to prevent unwanted text wrapping in headings when viewed in LibreOffice.
+- This adjustment ensures that headings display correctly without wrapping issues.
+
+The next major step is to handle explicit `width` and `height` parameters for background images, which are specified in the markdown but not always available in the final HTML `background-size` property.
+
+- **Parameters to Support:**
+    - **Explicit `width` and `height`**: Keywords like `width: 300px` or `h: 50%`.
+    - **Shorthand `w` and `h`**: e.g., `w:300px`.
+    - **Positional arguments**: e.g. `![bg 50%]` or `![bg 300px 200px]`. The script will need to parse the original markdown to get these.
+
+- **Goal:** Correctly position and scale images that use these markdown-specific parameters.
+
+- **Content Area Shrinking:**
+    - For split backgrounds, shrink the content area as Marp does, so content is not covered by split backgrounds.
+
+
+# Install and run tool
+## Run as module without installing:
+```bash
+python -m marp2pptx --help
+```
+## Install locally and run:
+```bash
+uv pip install -e .
+```
+```bash
+marp2pptx --help
+```
+to unsinstall:
+```bash
+uv pip uninstall marp2pptx
+```
+
+## Install globally and run:
+```bash
+uv pip install -e --global .
+```
+```bash
+marp2pptx --help
+```
+to unsinstall:
+```bash
+uv pip uninstall marp2pptx --global
+```

marp2pptx-0.1.0/README.md

@@ -0,0 +1,155 @@
+### Marp PPTX Post-Processing: Status & Next Steps
+
+#### 1. Marp HTML Structure (Key Concepts)
+
+**Slides:**
+- Each slide is represented by a `<svg data-marpit-svg ...>` element.
+- Inside each SVG, there are one or more layers, each as a `<foreignObject>` with width/height attributes.
+- Each `<foreignObject>` contains a `<section>` element, which holds the content for that layer.
+
+**Headers:**
+- If a slide has a header, a `<header>` element is placed under the `<section>` element.
+- Split background images are never placed in the header.
+
+**Marpit Advanced Backgrounds:**
+- Advanced backgrounds (true and split) are always placed in a `<div data-marpit-advanced-background-container="true">`.
+- This div can contain one or more `<figure>` elements, each with a background image.
+- The direction (horizontal/vertical) is set by `data-marpit-advanced-background-direction`.
+- Split backgrounds are indicated by attributes like `data-marpit-advanced-background-split` on the `<section>`.
+
+#### 2. What We're Trying to Achieve
+
+We want to post-process a Marp-exported PowerPoint (`.pptx`) so that all background images specified with Marp’s advanced image syntax are visually correct in the exported `.pptx`. This includes:
+
+- **True backgrounds** (`![bg](...)`): Fill the slide, appear behind content, and match Marp’s CSS background-size/position logic (cover, contain, auto, etc.).
+- **Multiple backgrounds** (`![bg](...)` x N, with `horizontal`/`vertical`): Stack images in the correct order and direction, matching Marp’s advanced backgrounds.
+   - **Split backgrounds** (`![bg left]`, `![bg right]`, `![bg left:33%]`, etc.): Place the image as a foreground element in a defined region (not as a slide-wide background), shrinking the content area as Marp does. Only `left` and `right` split directions are supported (not `top` or `bottom`).
+- **Cropping and placement**: All cropping, scaling, and placement (e.g., `right:35%`, `left:38% 70%`, `w:100% h:50%`) should visually match Marp’s HTML/PDF output.
+
+Reference: [Marpit image syntax documentation](https://marpit.marp.app/image-syntax)
+
+----
+
+#### 3. What We've Done So Far
+
+- **HTML Parsing:**
+   - The script parses Marp HTML output, extracting slide backgrounds, split info, image URLs, and layout instructions, by walking the SVG/foreignObject/section/container/figure structure.
+   - It builds a slide model for PPTX generation, replacing the old markdown/image logic.
+
+- **True Backgrounds & Multiple Backgrounds:**
+   - Images fill the slide or are stacked horizontally/vertically, matching Marp's stacking logic.
+
+- **Advanced Background Scaling:**
+   - Implemented full support for Marp's `background-size` property, parsed from the generated HTML.
+   - **Supported keywords**: `cover` (fills the area, cropping if necessary), `contain` and `fit` (scales to fit within the area), `auto` (uses original image size), and percentage values (e.g., `50%`, which scales the image relative to the container).
+
+- **Split Backgrounds:**
+   - Split backgrounds (left, right, with percentage) are placed in the correct region and cropped to fill only the split space. Only `left` and `right` split directions are supported.
+   - Multiple images in a split region are distributed equally within the split space (always horizontally), matching Marp's stacking logic.
+
+- **Debugging and Logging:**
+   - Extensive debug logging shows all image shapes, sizes, and the matching process for troubleshooting.
+
+- **Robust Image Mapping**: Refactored the processing logic to map all images from the Marp HTML (including headers, content, and backgrounds) one-to-one with the picture shapes in the PPTX slide. This ensures that transformations are applied *only* to the correct background shapes, preventing unintended modifications to other images on the slide.
+
+----
+
+### 4. CLI & Pipeline Automation
+
+The script has been refactored into a full command-line interface to automate the entire Marp to post-processed PPTX pipeline.
+
+- **End-to-End Automation**: The script now orchestrates the three main steps of the conversion process:
+    1.  **HTML Generation**: It calls `npx @marp-team/marp-cli` to convert the source Markdown file into an HTML file.
+    2.  **Initial PPTX Generation**: It uses the same CLI tool to create a raw, editable PPTX file (`*_raw.pptx`).
+    3.  **Post-Processing**: It runs the existing background image processing logic on the generated HTML and raw PPTX files.
+- **File Management**:
+    - **Smart Naming**: Automatically creates an intermediate `_raw.pptx` file and saves the final output as `<input_name>.pptx`.
+    - **Automatic Cleanup**: Deletes the intermediate HTML and `_raw.pptx` files by default to keep the workspace clean.
+    - **Keep Intermediates**: A `--debug` flag is available to prevent cleanup for debugging purposes.
+- **Improved Usability**:
+    - **CLI Arguments**: The script now uses `argparse` for robust handling of command-line arguments, including the input file, output file, and other options.
+    - **Help Documentation**: A `--help` command provides clear instructions on how to use the script and its available options.
+    - **Enhanced Typing**: Static typing has been improved throughout the codebase for better maintainability and reliability.
+
+----
+
+### 5. Testing
+
+The new CLI simplifies testing significantly. To process a Marp Markdown file, run the script with the input file path.
+
+Set the name of the Marp markdown file:
+```powershell
+$MARP_MARKDOWN_FILE = "sample.marp.md"
+```
+
+Run the end-to-end processing pipeline with a single command:
+```powershell
+uv run marp_pptx_postprocess.py ./${MARP_MARKDOWN_FILE}
+```
+
+The script will handle the intermediate steps and produce a final, post-processed PPTX file named `sample.marp.pptx`.
+
+To inspect the final output:
+```powershell
+explorer "${MARP_MARKDOWN_FILE}.pptx"
+```
+
+To run the pipeline and keep the intermediate files for debugging:
+```powershell
+uv run marp_pptx_postprocess.py ./${MARP_MARKDOWN_FILE} --debug
+```
+
+This will leave the following files for inspection:
+- `${MARP_MARKDOWN_FILE}.html`
+- `${MARP_MARKDOWN_FILE}_raw.pptx`
+- `${MARP_MARKDOWN_FILE}.pptx` (final output)
+
+----
+
+### 6. Next Steps (Advanced Placement)
+
+#### Recent Progress
+- Implemented a fix to widen all text boxes by 4cm (1133 pixels) to prevent unwanted text wrapping in headings when viewed in LibreOffice.
+- This adjustment ensures that headings display correctly without wrapping issues.
+
+The next major step is to handle explicit `width` and `height` parameters for background images, which are specified in the markdown but not always available in the final HTML `background-size` property.
+
+- **Parameters to Support:**
+    - **Explicit `width` and `height`**: Keywords like `width: 300px` or `h: 50%`.
+    - **Shorthand `w` and `h`**: e.g., `w:300px`.
+    - **Positional arguments**: e.g. `![bg 50%]` or `![bg 300px 200px]`. The script will need to parse the original markdown to get these.
+
+- **Goal:** Correctly position and scale images that use these markdown-specific parameters.
+
+- **Content Area Shrinking:**
+    - For split backgrounds, shrink the content area as Marp does, so content is not covered by split backgrounds.
+
+
+# Install and run tool
+## Run as module without installing:
+```bash
+python -m marp2pptx --help
+```
+## Install locally and run:
+```bash
+uv pip install -e .
+```
+```bash
+marp2pptx --help
+```
+to unsinstall:
+```bash
+uv pip uninstall marp2pptx
+```
+
+## Install globally and run:
+```bash
+uv pip install -e --global .
+```
+```bash
+marp2pptx --help
+```
+to unsinstall:
+```bash
+uv pip uninstall marp2pptx --global
+```

marp2pptx-0.1.0/marp2pptx/__init__.py

@@ -0,0 +1,3 @@
+from . import render_div_as_image as render_div_as_image  
+from . import postprocessing as postprocessing
+from . import marp_convert as marp_convert

marp2pptx-0.1.0/marp2pptx/__main__.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env -S uv run --script
+
+import argparse
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from pptx import Presentation
+
+# Import from new modules
+from .marp_convert import (
+    get_npx_path,
+    marp_generate_in_parallel,
+)
+from .preprocessing import (
+    preprocess_markdown,
+)
+from .postprocessing import (
+    parse_marp_html,
+    widen_text_shapes,
+    normalize_font_names,
+    remove_redundant_marp_white_rectangles,
+    process_native_marp_images,
+    process_styled_divs,
+)
+
+# Module logger
+logger = logging.getLogger(__name__)
+
+
+def open_pptx_file(pptx_path: Path) -> None:
+    """
+    Open a PPTX file in the default viewer.
+    """
+    try:
+        # Use os.startfile on Windows, open on macOS, xdg-open on Linux
+        if sys.platform == "win32":
+            os.startfile(str(pptx_path))
+        elif sys.platform == "darwin":
+            subprocess.run(["open", str(pptx_path)], check=True)
+        else:
+            subprocess.run(["xdg-open", str(pptx_path)], check=True)
+        
+        logger.info(f"Opening PPTX file: {pptx_path}")
+    except Exception as e:
+        logger.error(f"Failed to open PPTX file: {e}")
+
+
+def convert_command(args) -> None:
+    """
+    Execute the convert command to transform a Marp Markdown file to PPTX.
+    """
+    input_md_file = Path(args.input_file)
+    if not input_md_file.is_file():
+        logger.error(f"Input file not found: {input_md_file}")
+        sys.exit(1)
+
+    # Define file paths based on user's requirements
+    preprocessed_md_path = Path(f"{args.input_file}-m2p.preprocessed.marp.md")
+    html_path = Path(f"{args.input_file}-m2p.html")
+    raw_pptx_path = Path(f"{args.input_file}-m2p_raw.pptx")
+    final_pptx_path = (
+        Path(args.output) if args.output else Path(f"{args.input_file}-m2p.pptx")
+    )
+
+    # Include output files in cleanup list
+    intermediate_files = [preprocessed_md_path, html_path, raw_pptx_path]
+    conversion_successful = False
+
+    try:
+        # --- Step 1: Preprocess Markdown ---
+        logger.info("Preprocessing Markdown to remove invisible characters...")
+        preprocess_markdown(input_md_file, preprocessed_md_path)
+        logger.debug(f"Preprocessed Markdown created: {preprocessed_md_path}")
+
+        # run HTML + raw PPTX generation concurrently to improve throughput
+        marp_generate_in_parallel(preprocessed_md_path, html_path, raw_pptx_path)
+
+        # --- Step 3: Post-process the PPTX ---
+        logger.info(f"Post-processing raw PPTX to create final file: {final_pptx_path}")
+
+        process_pptx_html(
+            Path(html_path),
+            Path(raw_pptx_path),
+            Path(final_pptx_path),
+            save_rendered_divs=args.debug and logger.isEnabledFor(logging.DEBUG),
+            run_styled_divs=args.experimental,
+        )
+        logger.info(f"Successfully created final PPTX: {final_pptx_path}")
+        conversion_successful = True
+
+    except FileNotFoundError:
+        logger.error(
+            f"Error: '{get_npx_path()}' command not found. Is Node.js and npm installed and in your PATH?"
+        )
+        sys.exit(1)
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Marp CLI failed to execute. The command was: {' '.join(e.cmd)}")
+        # Stderr is not captured when streaming, so we can't print it here.
+        # The error from the subprocess itself should be visible in the console.
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"An unexpected error occurred: {e}")
+        logger.debug("Full traceback:", exc_info=True)
+        sys.exit(1)
+
+    finally:
+        # --- Step 4: Cleanup ---
+        if not args.debug:
+            logger.info("Cleaning up intermediate files...")
+            for f in intermediate_files:
+                try:
+                    if f.is_file():
+                        os.remove(f)
+                        logger.debug(f"Removed {f}")
+                except OSError as e:
+                    logger.warning(f"Could not remove intermediate file {f}: {e}")
+            logger.info("Cleanup complete.")
+        else:
+            logger.info("Intermediate files kept as requested.")
+    
+    # Opening PPTX after the entire process is complete
+    if conversion_successful and args.open_pptx:
+        open_pptx_file(final_pptx_path)
+
+
+def cleanup_command(args) -> None:
+    """
+    Execute the clean-up command to remove debug files.
+    """
+    Path(args.input_file)
+    
+    # Define debug file paths
+    preprocessed_md_path = Path(f"{args.input_file}-m2p.preprocessed.marp.md")
+    html_path = Path(f"{args.input_file}-m2p.html")
+    raw_pptx_path = Path(f"{args.input_file}-m2p_raw.pptx")
+    
+    debug_files = [preprocessed_md_path, html_path, raw_pptx_path]
+    
+    removed_count = 0
+    for f in debug_files:
+        try:
+            if f.is_file():
+                os.remove(f)
+                logger.info(f"Removed {f}")
+                removed_count += 1
+            else:
+                logger.debug(f"File not found: {f}")
+        except OSError as e:
+            logger.warning(f"Could not remove file {f}: {e}")
+    
+    if removed_count > 0:
+        logger.info(f"Cleanup complete. Removed {removed_count} file(s).")
+    else:
+        logger.info("No debug files found to remove.")
+
+
+def open_pptx_command(args) -> None:
+    """
+    Execute the open-pptx command to open the generated PPTX file.
+    """
+    pptx_path = Path(f"{args.input_file}-m2p.pptx")
+    
+    if not pptx_path.is_file():
+        logger.error(f"PPTX file not found: {pptx_path}")
+        sys.exit(1)
+    
+    open_pptx_file(pptx_path)
+
+
+def process_pptx_html(
+    html_path: Path,
+    pptx_path: Path,
+    output_path: Path,
+    save_rendered_divs: bool = False,
+    run_styled_divs: bool = True,
+) -> None:
+    """
+    Processes a PPTX file using information from a Marp HTML file to fix backgrounds.
+
+    If `save_rendered_divs` is True and `rendered_output_dir` is provided, styled div
+    screenshots will be copied there (used when --debug + debug).
+
+    Parameters:
+        run_styled_divs: when False, skip the `process_styled_divs` pipeline. This
+            allows the CLI to disable the experimental styled-div rendering step.
+    """
+    slides_data = parse_marp_html(html_path)
+    logger.debug("Parsed Marp HTML -> slides_data length: %d", len(slides_data))
+    logger.debug("Slides data content presence:")
+    for _i, _sd in enumerate(slides_data):
+        logger.debug(f"  slide[{_i}] content present: {bool(_sd.get('content'))}")
+
+    # global CSS for styled-div rendering is computed inside `process_styled_divs`.
+    # (moved there to reduce the number of arguments passed into the helper.)
+
+    prs = Presentation(str(pptx_path))
+    # Handle native Marp image/background sizing (extracted to helper)
+    process_native_marp_images(
+        prs=prs,
+        slides_data=slides_data,
+    )
+    # Widen text boxes to avoid wrapping issues in some viewers (extracted to helper).
+    widen_text_shapes(prs=prs, extra_width_cm=.7)
+
+
+    # Handle styled HTML <div> elements that contain images. This was extracted to
+    # the dedicated pipeline function `process_styled_divs` which fixes a known
+    # Marp->PPTX conversion gap for custom HTML/CSS (rounded portraits, object-fit,
+    # background-image on divs, inline border-radius, etc.).
+    # This behavior is experimental and can be disabled via the CLI flag
+    # `--experimental` (disabled by default).
+    if run_styled_divs:
+        process_styled_divs(
+            prs=prs,
+            slides_data=slides_data,
+            html_path=html_path,
+            save_rendered_divs=save_rendered_divs,
+        )
+    else:
+        logger.info("Skipping experimental styled-div rendering (disabled)")
+
+    # Normalize font names (fix known Marp->PPTX mismatches such as 'SegoeUI' -> 'Segoe UI')
+    try:
+        normalize_font_names(prs)
+    except Exception:
+        logger.debug("process_pptx_html: normalize_font_names failed", exc_info=True)
+
+    try:
+        removed_shapes = remove_redundant_marp_white_rectangles(prs)
+        logger.info("Removed %d redundant white rectangle(s)", removed_shapes)
+    except Exception:
+        logger.debug("process_pptx_html: remove_redundant_marp_white_rectangles failed", exc_info=True)
+
+    # Save the modified presentation
+    prs.save(str(output_path))
+
+
+def main() -> None:
+    """
+    Main function to run the CLI tool.
+    """
+    # configure module logging when running as a script (don't configure at import time)
+    logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+
+    parser = argparse.ArgumentParser(
+        description="Process a Marp Markdown file to create a polished PPTX.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    
+    # Create subparsers for commands
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Create the 'convert' subcommand
+    convert_parser = subparsers.add_parser(
+        "convert",
+        help="""Convert a Marp Markdown file to a polished PPTX.
+This script automates the pipeline:
+1. Preprocess Markdown to remove invisible characters.
+2. Convert Markdown to HTML using Marp CLI (runs in parallel with step 3).
+3. Convert Markdown to a raw PPTX using Marp CLI (runs in parallel with step 2).
+4. Post-process the raw PPTX, using the HTML to fix background image layouts, creating the final PPTX.
+5. Clean up intermediate files (preprocessed Markdown, HTML, raw PPTX) unless specified otherwise.
+""",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    convert_parser.add_argument(
+        "input_file",
+        type=str,
+        help='Path to the input Marp Markdown file (e.g., "sample.marp.md")',
+    )
+    convert_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help='Path for the final output PPTX file. Defaults to "<input_file>.pptx" (e.g., "sample.marp.md.pptx").',
+    )
+    convert_parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Keep the intermediate HTML and raw PPTX files for debugging.",
+    )
+    convert_parser.add_argument(
+        "--experimental",
+        action="store_true",
+        help="Enable experimental styled-div rendering (disabled by default).",
+    )
+    convert_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose debug logging."
+    )
+    convert_parser.add_argument(
+        "--open-pptx",
+        action="store_true",
+        help="Open the generated PPTX file in the default viewer after successful conversion.",
+    )
+    
+    # Create the 'clean-up' subcommand
+    cleanup_parser = subparsers.add_parser(
+        "clean-up",
+        help="Remove debug files (preprocessed Markdown, HTML, raw PPTX) generated by the convert command.",
+    )
+    cleanup_parser.add_argument(
+        "input_file",
+        type=str,
+        help='Path to the Marp Markdown file (e.g., "sample.marp.md")',
+    )
+    cleanup_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose debug logging."
+    )
+    
+    # Create the 'open-pptx' subcommand
+    open_parser = subparsers.add_parser(
+        "open-pptx",
+        help="Open the generated PPTX file in the default viewer.",
+    )
+    open_parser.add_argument(
+        "input_file",
+        type=str,
+        help='Path to the Marp Markdown file (e.g., "sample.marp.md")',
+    )
+    
+    args = parser.parse_args()
+    
+    # Check if a command was provided
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if hasattr(args, 'verbose') and args.verbose:
+        logger.setLevel(logging.DEBUG)
+
+    # Dispatch to appropriate command function
+    if args.command == "convert":
+        convert_command(args)
+    elif args.command == "clean-up":
+        cleanup_command(args)
+    elif args.command == "open-pptx":
+        open_pptx_command(args)
+
+
+if __name__ == "__main__":
+    main()
+