From bdd070cdd493a86d25cfbb95e47e887d951fdc7e Mon Sep 17 00:00:00 2001
From: Emir Ayar <emirayar@amazon.lu>
Date: Fri, 9 Jan 2026 13:45:39 +0100
Subject: [PATCH] feat: add --slide-numbers option to include slide number
 comments

Adds a new --slide-numbers flag that inserts HTML comments (<-cli Slide N -->)
at the beginning of each slide in the output. This helps with:
- Referencing specific slides in the converted markdown
- Navigating large presentations
- Correlating markdown content with original PPTX slides

The feature is opt-in and works with all output formats (markdown, wiki, madoko, quarto).

Relates to #60
---
 pptx2md/__main__.py  |  5 +++++
 pptx2md/outputter.py | 12 ++++++++++++
 pptx2md/types.py     |  3 +++
 3 files changed, 20 insertions(+)

diff --git a/pptx2md/__main__.py b/pptx2md/__main__.py
index 2f5d592..23175d6 100644
--- a/pptx2md/__main__.py
+++ b/pptx2md/__main__.py
@@ -54,6 +54,10 @@ def parse_args() -> ConversionConfig:
         "--keep-similar-titles",
         action="store_true",
         help="keep similar titles (allow for repeated slide titles - One or more - Add (cont.) to the title)")
+    arg_parser.add_argument(
+        "--slide-numbers",
+        action="store_true",
+        help="add slide number comments (<!-- Slide N -->) to the output")
 
     args = arg_parser.parse_args()
 
@@ -81,6 +85,7 @@ def parse_args() -> ConversionConfig:
         min_block_size=args.min_block_size,
         page=args.page,
         keep_similar_titles=args.keep_similar_titles,
+        slide_numbers=args.slide_numbers,
     )
 
 
diff --git a/pptx2md/outputter.py b/pptx2md/outputter.py
index 3beadd6..f5dd612 100644
--- a/pptx2md/outputter.py
+++ b/pptx2md/outputter.py
@@ -36,6 +36,10 @@ def output(self, presentation_data: ParsedPresentation):
         last_element = None
         last_title = None
         for slide_idx, slide in enumerate(presentation_data.slides):
+            # Add slide number comment if enabled
+            if self.config.slide_numbers:
+                self.put_slide_number(slide_idx + 1)
+
             all_elements = []
             if slide.type == SlideType.General:
                 all_elements = slide.elements
@@ -84,6 +88,10 @@ def output(self, presentation_data: ParsedPresentation):
     def put_header(self):
         pass
 
+    def put_slide_number(self, number):
+        """Output slide number comment. Override in subclasses for format-specific output."""
+        self.ofile.write(f'<!-- Slide {number} -->\n')
+
     def put_title(self, text, level):
         pass
 
@@ -336,6 +344,10 @@ def put_elements(elements: List[SlideElement]):
                 last_element = element
 
         for slide_idx, slide in enumerate(presentation_data.slides):
+            # Add slide number comment if enabled
+            if self.config.slide_numbers:
+                self.put_slide_number(slide_idx + 1)
+
             if slide.type == SlideType.General:
                 put_elements(slide.elements)
             elif slide.type == SlideType.MultiColumn:
diff --git a/pptx2md/types.py b/pptx2md/types.py
index 0de9e4f..3afa7b3 100644
--- a/pptx2md/types.py
+++ b/pptx2md/types.py
@@ -81,6 +81,9 @@ class ConversionConfig(BaseModel):
     keep_similar_titles: bool = False
     """Keep similar titles (allow for repeated slide titles - One or more - Add (cont.) to the title)"""
 
+    slide_numbers: bool = False
+    """Add slide number comments (<!-- Slide N -->) to the output"""
+
 
 class ElementType(str, Enum):
     Title = "Title"