feat: add option to include DOCX comments

Author: garlic9912

README.md

@@ -88,6 +88,13 @@ You can also pipe content:
 cat path-to-file.pdf | markitdown
 ```
 
+Reviewer comments are excluded from DOCX output by default. Include them, along
+with references to their locations in the document, with `--include-comments`:
+
+```bash
+markitdown reviewed-document.docx --include-comments
+```
+
 ### Optional Dependencies
 MarkItDown has optional dependencies for activating various file formats. Earlier in this document, we installed all optional dependencies with the `[all]` option. However, you can also install them individually for more control. For example:
 
@@ -258,6 +265,17 @@ result = md.convert("test.xlsx")
 print(result.text_content)
 ```
 
+To include reviewer comments when converting a DOCX file, pass
+`include_comments=True`. The option can be supplied to an individual conversion
+or to the `MarkItDown` constructor:
+
+```python
+result = md.convert("reviewed-document.docx", include_comments=True)
+
+md_with_comments = MarkItDown(include_comments=True)
+result = md_with_comments.convert("reviewed-document.docx")
+```
+
 Document Intelligence conversion in Python:
 
 ```python

packages/markitdown/src/markitdown/__main__.py

@@ -138,6 +138,12 @@ def main():
         help="Keep data URIs (like base64-encoded images) in the output. By default, data URIs are truncated.",
     )
 
+    parser.add_argument(
+        "--include-comments",
+        action="store_true",
+        help="Include reviewer comments when converting DOCX files.",
+    )
+
     parser.add_argument("filename", nargs="?")
     args = parser.parse_args()
 
@@ -244,15 +250,23 @@ def main():
     else:
         markitdown = MarkItDown(enable_plugins=args.use_plugins)
 
+    conversion_kwargs: Dict[str, Any] = {
+        "keep_data_uris": args.keep_data_uris,
+    }
+    if args.include_comments:
+        conversion_kwargs["include_comments"] = True
+
     if args.filename is None:
         result = markitdown.convert_stream(
             sys.stdin.buffer,
             stream_info=stream_info,
-            keep_data_uris=args.keep_data_uris,
+            **conversion_kwargs,
         )
     else:
         result = markitdown.convert(
-            args.filename, stream_info=stream_info, keep_data_uris=args.keep_data_uris
+            args.filename,
+            stream_info=stream_info,
+            **conversion_kwargs,
         )
 
     _handle_output(args, result)

packages/markitdown/src/markitdown/_markitdown.py

@@ -126,6 +126,7 @@ def __init__(
         self._llm_prompt: Union[str | None] = None
         self._exiftool_path: Union[str | None] = None
         self._style_map: Union[str | None] = None
+        self._include_comments: Union[bool | None] = None
 
         # Register the converters
         self._converters: List[ConverterRegistration] = []
@@ -151,6 +152,7 @@ def enable_builtins(self, **kwargs) -> None:
             self._llm_prompt = kwargs.get("llm_prompt")
             self._exiftool_path = kwargs.get("exiftool_path")
             self._style_map = kwargs.get("style_map")
+            self._include_comments = kwargs.get("include_comments")
 
             if self._exiftool_path is None:
                 self._exiftool_path = os.getenv("EXIFTOOL_PATH")
@@ -597,6 +599,12 @@ def _convert(
                 if "style_map" not in _kwargs and self._style_map is not None:
                     _kwargs["style_map"] = self._style_map
 
+                if (
+                    "include_comments" not in _kwargs
+                    and self._include_comments is not None
+                ):
+                    _kwargs["include_comments"] = self._include_comments
+
                 if "exiftool_path" not in _kwargs and self._exiftool_path is not None:
                     _kwargs["exiftool_path"] = self._exiftool_path
 

packages/markitdown/src/markitdown/converters/_docx_converter.py

@@ -27,6 +27,8 @@
 
 ACCEPTED_FILE_EXTENSIONS = [".docx"]
 
+COMMENT_STYLE_MAP = "comment-reference => "
+
 
 class DocxConverter(HtmlConverter):
     """
@@ -76,6 +78,10 @@ def convert(
             )
 
         style_map = kwargs.get("style_map", None)
+        if kwargs.get("include_comments", False):
+            style_map = (
+                f"{style_map}\n{COMMENT_STYLE_MAP}" if style_map else COMMENT_STYLE_MAP
+            )
         pre_process_stream = pre_process_docx(file_stream)
         return self._html_converter.convert_string(
             mammoth.convert_to_html(pre_process_stream, style_map=style_map).value,

packages/markitdown/tests/test_cli_misc.py

@@ -1,14 +1,21 @@
 #!/usr/bin/env python3 -m pytest
 import subprocess
+import sys
+from pathlib import Path
 from markitdown import __version__
 
+
+TEST_FILES_DIR = Path(__file__).parent / "test_files"
+
 # This file contains CLI tests that are not directly tested by the FileTestVectors.
 # This includes things like help messages, version numbers, and invalid flags.
 
 
 def test_version() -> None:
     result = subprocess.run(
-        ["python", "-m", "markitdown", "--version"], capture_output=True, text=True
+        [sys.executable, "-m", "markitdown", "--version"],
+        capture_output=True,
+        text=True,
     )
 
     assert result.returncode == 0, f"CLI exited with error: {result.stderr}"
@@ -17,7 +24,9 @@ def test_version() -> None:
 
 def test_invalid_flag() -> None:
     result = subprocess.run(
-        ["python", "-m", "markitdown", "--foobar"], capture_output=True, text=True
+        [sys.executable, "-m", "markitdown", "--foobar"],
+        capture_output=True,
+        text=True,
     )
 
     assert result.returncode != 0, f"CLI exited with error: {result.stderr}"
@@ -27,6 +36,23 @@ def test_invalid_flag() -> None:
     assert "SYNTAX" in result.stderr, "Expected 'SYNTAX' to appear in STDERR"
 
 
+def test_include_docx_comments() -> None:
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "markitdown",
+            str(TEST_FILES_DIR / "test_with_comment.docx"),
+            "--include-comments",
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, f"CLI exited with error: {result.stderr}"
+    assert "This is a test comment. 12df-321a" in result.stdout
+
+
 if __name__ == "__main__":
     """Runs this file's tests from the command line."""
     test_version()

packages/markitdown/tests/test_module_misc.py

@@ -253,13 +253,39 @@ def test_file_uris() -> None:
 
 
 def test_docx_comments() -> None:
-    # Test DOCX processing, with comments and setting style_map on init
-    markitdown_with_style_map = MarkItDown(style_map="comment-reference => ")
-    result = markitdown_with_style_map.convert(
-        os.path.join(TEST_FILES_DIR, "test_with_comment.docx")
-    )
+    docx_file = os.path.join(TEST_FILES_DIR, "test_with_comment.docx")
+
+    # Comments remain excluded by default for backwards compatibility.
+    result = MarkItDown().convert(docx_file)
+    validate_strings(result, [], exclude_strings=DOCX_COMMENT_TEST_STRINGS[-2:])
+
+    # Comments can be enabled for a single conversion.
+    result = MarkItDown().convert(docx_file, include_comments=True)
+    validate_strings(result, DOCX_COMMENT_TEST_STRINGS)
+    assert "(#comment-0)" in result.text_content
+    assert "(#comment-ref-0)" in result.text_content
+
+    # The option can also be set when constructing a reusable converter.
+    markitdown_with_comments = MarkItDown(include_comments=True)
+    result = markitdown_with_comments.convert(docx_file)
     validate_strings(result, DOCX_COMMENT_TEST_STRINGS)
 
+    # Per-conversion options take precedence over constructor options.
+    result = markitdown_with_comments.convert(docx_file, include_comments=False)
+    validate_strings(result, [], exclude_strings=DOCX_COMMENT_TEST_STRINGS[-2:])
+
+
+def test_docx_comments_preserve_custom_style_map() -> None:
+    docx_file = os.path.join(TEST_FILES_DIR, "test_with_comment.docx")
+    result = MarkItDown().convert(
+        docx_file,
+        include_comments=True,
+        style_map="p[style-name='heading 1'] => h6:fresh",
+    )
+
+    assert "###### Abstract" in result.text_content
+    validate_strings(result, DOCX_COMMENT_TEST_STRINGS[-2:])
+
 
 def test_docx_equations() -> None:
     markitdown = MarkItDown()