feat: add keepHtmlEntities option (closes #166)

Author: tim-gromeyer

cli/main.cpp

@@ -60,16 +60,20 @@ constexpr const char *const DESCRIPTION =
     "  -r, --replace\tOverwrite the output file (if it already exists) without "
     "asking.\n";
 
+  constexpr const char *const EXTRA_OPTIONS =
+    "  -E, --preserve-entities\tKeep HTML entities (e.g.  ) in output.\n";
+
 struct Options {
   bool print = false;
   bool replace = false;
+  bool preserveEntities = false;
   string inputFile;
   string outputFile;
   string inputText;
 };
 
 void printHelp(const string &programName) {
-  cout << programName << DESCRIPTION;
+  cout << programName << DESCRIPTION << EXTRA_OPTIONS;
 }
 
 void printVersion() { cout << "Version " << VERSION << endl; }
@@ -115,6 +119,8 @@ Options parseCommandLine(int argc, char **argv) {
       options.print = true;
     } else if (arg == "-r" || arg == "--replace") {
       options.replace = true;
+    } else if (arg == "-E" || arg == "--preserve-entities") {
+      options.preserveEntities = true;
     } else if (arg == "-o" || arg == "--output") {
       if (i + 1 < argc) {
         options.outputFile = argv[i + 1];
@@ -153,7 +159,10 @@ int main(int argc, char **argv) {
     return EXIT_FAILURE;
   }
 
-  html2md::Converter converter(input);
+  // Pass CLI-driven option to the converter
+  html2md::Options copt;
+  copt.keepHtmlEntities = options.preserveEntities;
+  html2md::Converter converter(input, &copt);
   string md = converter.convert();
 
   if (options.print) {

include/html2md.h

@@ -133,13 +133,22 @@ struct Options {
    */
   bool escapeNumberedList = true;
 
+  /*!
+   * \brief Whether to keep HTML entities (e.g. ` `) in the output
+   *
+   * If true, the converter will not replace HTML entities configured in the
+   * internal conversion map. Default is false (current behaviour).
+   */
+  bool keepHtmlEntities = false;
+
   inline bool operator==(html2md::Options o) const {
     return splitLines == o.splitLines && unorderedList == o.unorderedList &&
            orderedList == o.orderedList && includeTitle == o.includeTitle &&
            softBreak == o.softBreak && hardBreak == o.hardBreak &&
            formatTable == o.formatTable && forceLeftTrim == o.forceLeftTrim &&
            compressWhitespace == o.compressWhitespace &&
-           escapeNumberedList == o.escapeNumberedList;
+           escapeNumberedList == o.escapeNumberedList &&
+           keepHtmlEntities == o.keepHtmlEntities;
   };
 };
 

python/bindings.cpp

@@ -31,6 +31,8 @@ PYBIND11_MODULE(pyhtml2md, m) {
                      "into a single space")
       .def_readwrite("escapeNumberedList", &html2md::Options::escapeNumberedList,
                      "Whether to escape numbered lists (e.g. '4.' -> '4\\.')")
+     .def_readwrite("keepHtmlEntities", &html2md::Options::keepHtmlEntities,
+                  "Whether to keep HTML entities (e.g. ' ') in the output")
       .def("__eq__", &html2md::Options::operator==);
 
   py::class_<html2md::Converter>(m, "Converter")

src/html2md.cpp

@@ -164,26 +164,32 @@ void Converter::CleanUpMarkdown() {
   std::string buffer;
   buffer.reserve(md_.size());
 
-  // Replace HTML symbols during the initial pass
-  for (size_t i = 0; i < md_.size();) {
-    bool replaced = false;
-
-    // C++11 compatible iteration over htmlSymbolConversions_
-    for (const auto &symbol_replacement : htmlSymbolConversions_) {
-      const std::string &symbol = symbol_replacement.first;
-      const std::string &replacement = symbol_replacement.second;
-
-      if (md_.compare(i, symbol.size(), symbol) == 0) {
-        buffer.append(replacement);
-        i += symbol.size();
-        replaced = true;
-        break;
+  // Replace HTML symbols during the initial pass unless the user requested
+  // to keep HTML entities intact (e.g. keep `&nbsp;`)
+  if (!option.keepHtmlEntities) {
+    for (size_t i = 0; i < md_.size();) {
+      bool replaced = false;
+
+      // C++11 compatible iteration over htmlSymbolConversions_
+      for (const auto &symbol_replacement : htmlSymbolConversions_) {
+        const std::string &symbol = symbol_replacement.first;
+        const std::string &replacement = symbol_replacement.second;
+
+        if (md_.compare(i, symbol.size(), symbol) == 0) {
+          buffer.append(replacement);
+          i += symbol.size();
+          replaced = true;
+          break;
+        }
       }
-    }
 
-    if (!replaced) {
-      buffer.push_back(md_[i++]);
+      if (!replaced) {
+        buffer.push_back(md_[i++]);
+      }
     }
+  } else {
+    // Keep entities as-is: copy through without transforming
+    buffer.append(md_);
   }
 
   // Use swap instead of move assignment for better pre-C++11 compatibility

tests/main.cpp

@@ -533,6 +533,49 @@ bool testTableFormatting() {
   return true;
 }
 
+bool testPreserveNbsp() {
+  testOption("preserveNbsp");
+
+  string html = R"(<p class="" style="text-autospace:none"><span style="font-size:11.0pt;mso-fareast-language:EN-US">redacted1</span></p>
+<p class=""><span style="font-size:11.0pt;mso-fareast-language:EN-US">&nbsp;</span></p>
+<p class=""><span style="font-size:11.0pt;mso-fareast-language:EN-US">&nbsp;</span></p>
+<div>
+<p class=""><span style="font-size:11.0pt;mso-ligatures:standardcontextual;mso-fareast-language:EN-US">&nbsp;</span></p>
+<p class="" style="text-autospace:none"><b><span style="font-size:10.0pt;font-family:&quot;Arial&quot;,sans-serif;color:#244061"><img width="239" height="30" style="width: 2.493in; height: 0.3125in; max-width: 100%;" id="" src=""></span></b><b><span style="font-size:10.0pt;font-family:&quot;Arial&quot;,sans-serif;color:#244061"></span></b></p>
+<p class="" style="text-autospace:none"><b><span style="font-size:10.0pt;font-family:&quot;Arial&quot;,sans-serif;color:#244061;mso-ligatures:standardcontextual">redacted2</span></b></p>)";
+
+  html2md::Options o;
+  o.splitLines = false;
+  o.keepHtmlEntities = true;
+
+  html2md::Converter c(html, &o);
+  auto md = c.convert();
+
+  // We expect the output to contain HTML non-breaking spaces preserved
+  size_t count = 0;
+  size_t pos = 0;
+  while ((pos = md.find("&nbsp;", pos)) != string::npos) {
+    ++count;
+    pos += 6;
+  }
+
+  if (count < 3) {
+    cout << "Failed preserve &nbsp;: only " << count << " occurrences found\n"
+         << "Generated Markdown:\n" << md << "\n";
+    return false;
+  }
+
+  // Also ensure that redacted1 and redacted2 are present in correct order
+  auto p1 = md.find("redacted1");
+  auto p2 = md.find("redacted2");
+  if (p1 == string::npos || p2 == string::npos || p1 >= p2) {
+    cout << "redacted texts missing or in wrong order\n" << md << "\n";
+    return false;
+  }
+
+  return true;
+}
+
 int main(int argc, const char **argv) {
   // List to store all markdown files in this dir
   vector<string> files;
@@ -596,6 +639,7 @@ int main(int argc, const char **argv) {
                 &testInvalidTags,
                 &testEscapingNumberedList,
                 &testTableFormatting,
+                &testPreserveNbsp,
               };
 
   for (const auto &test : tests)