diff --git a/docs/architecture.md b/docs/architecture.md
index 22fc4d56..61739015 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -190,7 +190,7 @@ classDiagram
     class html {
         <<module>>
         +convert_html_tables()
-        +html_table_to_markdown()
+        +html_table_to_markdown() %% deprecated
     }
     class table {
         <<module>>
@@ -264,6 +264,9 @@ streaming helpers that combine the lower-level functions, including ellipsis
 replacement and footnote conversion. The `io` module handles filesystem
 operations, delegating the text processing to `process`.
 
+The helper `html_table_to_markdown` is retained for backward compatibility but
+is deprecated. New code should call `convert_html_tables` instead.
+
 ## Concurrency with `rayon`
 
 `mdtablefix` uses the `rayon` crate to process multiple files concurrently.
diff --git a/src/lib.rs b/src/lib.rs
index 9ae0f228..197edba1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -31,7 +31,7 @@ mod reflow;
 pub mod table;
 pub mod wrap;
 
-#[doc(hidden)]
+#[deprecated(note = "this function is legacy; use `convert_html_tables` instead")]
 #[must_use]
 pub fn html_table_to_markdown(lines: &[String]) -> Vec<String> {
     html::html_table_to_markdown(lines)