Document footnotes option

README.md

@@ -54,6 +54,9 @@ mdtablefix [--wrap] [--renumber] [--breaks] [--ellipsis] [--fences] [--footnotes
 - Use `--footnotes` to convert bare numeric references and the final numbered
   list into GitHub-flavoured footnote links.
 
+  A bare numeric reference is a trailing number after punctuation, like
+  `An example.1`.
+
 - Use `--in-place` to modify files in-place.
 
 - If no files are specified, input is read from stdin and output is written to
@@ -141,10 +144,41 @@ fn main() -> std::io::Result<()> {
 }
 ```
 
+The `footnotes` option also rewrites bare numeric references:
+
+```rust
+use mdtablefix::{process_stream_opts, Options};
+
+let lines = vec![
+    "A tip.1".to_string(),
+    "",
+    "1. Footnote text".to_string(),
+];
+let opts = Options { footnotes: true, ..Default::default() };
+let out = process_stream_opts(&lines, opts);
+assert_eq!(out[0], "A tip.[^1]");
+```
+
+It converts a trailing numbered list into footnote definitions:
+
+```rust
+use mdtablefix::{process_stream_opts, Options};
+
+let lines = vec![
+    "More text.".to_string(),
+    "".to_string(),
+    "1. First note".to_string(),
+    "2. Second note".to_string(),
+];
+let opts = Options { footnotes: true, ..Default::default() };
+let out = process_stream_opts(&lines, opts);
+assert_eq!(out[2], "[^1] First note");
+```
+
 - `process_stream_opts(lines: &[String], opts: Options) -> Vec<String>`
   rewrites tables in memory. The options enable paragraph wrapping, ellipsis
   substitution, fence normalization and footnote conversion when `footnotes` is
-  set to `true`.
+  set to `true`. The flag is `false` by default.
 
 - `rewrite(path: &Path) -> std::io::Result<()>` modifies a Markdown file on
   disk in-place.

docs/architecture.md

@@ -94,10 +94,18 @@ returns the updated stream for writing to disk or further manipulation.
 ## Footnote Conversion
 
 `mdtablefix` can optionally convert bare numeric references into
-GitHub-flavoured Markdown footnotes. The `convert_footnotes` function performs
-this operation and is exposed via the higher-level `process_stream_opts`
-helper. Set `Options { footnotes: true, ..Default::default() }` when calling
-`process_stream_opts` to enable the conversion logic.
+GitHub-flavoured Markdown footnotes. A bare numeric reference is a number that
+appears after punctuation with no footnote formatting, for example:
+
+```markdown
+An example of a bare numeric reference.1
+```
+
+`convert_footnotes` performs this operation and is exposed via the higher-level
+`process_stream_opts` helper. Set
+`Options { footnotes: true, ..Default::default() }` when calling
+`process_stream_opts` to enable the conversion logic. The parameter defaults to
+`false`.
 
 Inline references that appear after punctuation are rewritten as footnote links.
 

src/process.rs

@@ -41,7 +41,7 @@ pub struct Options {
     pub ellipsis: bool,
     /// Normalise code block fences.
     pub fences: bool,
-    /// Convert bare numeric references to footnotes.
+    /// Convert bare numeric references into GitHub-flavoured footnote links (default: `false`).
     pub footnotes: bool,
 }
 
@@ -234,7 +234,9 @@ pub fn process_stream_no_wrap(lines: &[String]) -> Vec<String> {
 /// Runs [`process_stream_inner`] with custom [`Options`].
 ///
 /// This is exposed for advanced use cases where callers want precise
-/// control over the processing pipeline.
+/// control over the processing pipeline. Set `footnotes: true` in `opts`
+/// to convert bare numeric references into GitHub-flavoured footnote
+/// links. The flag defaults to `false`.
 ///
 /// # Examples
 ///