Add YAML frontmatter preservation support

AGENTS.md

@@ -29,7 +29,7 @@
   documentation should omit examples where the example serves only to reiterate
   the test logic.
 - **Keep file size manageable.** No single code file may be longer than 400
-  lines.  Long switch statements or dispatch tables should be broken up by
+  lines. Long switch statements or dispatch tables should be broken up by
   feature and constituents colocated with targets. Large blocks of test data
   should be moved to external data files.
 
@@ -118,13 +118,15 @@ project:
 - Run `make check-fmt`, `make lint`, and `make test` before committing. These
   targets wrap the following commands, so contributors understand the exact
   behaviour and policy enforced:
+
   - `make check-fmt` executes:
 
     ```sh
     cargo fmt --workspace -- --check
     ```
 
     validating formatting across the entire workspace without modifying files.
+
   - `make lint` executes:
 
     ```sh
@@ -133,6 +135,7 @@ project:
 
     linting every target with all features enabled and denying all Clippy
     warnings.
+
   - `make test` executes:
 
     ```sh
@@ -142,37 +145,60 @@ project:
     running the full workspace test suite. Use `make fmt`
     (`cargo fmt --workspace`) to apply formatting fixes reported by the
     formatter check.
+
 - Clippy warnings MUST be disallowed.
+
 - Fix any warnings emitted during tests in the code itself rather than
   silencing them.
+
 - Where a function is too long, extract meaningfully named helper functions
   adhering to separation of concerns and CQRS.
+
 - Where a function has too many parameters, group related parameters in
   meaningfully named structs.
+
 - Where a function is returning a large error, consider using `Arc` to reduce
   the amount of data returned.
+
 - Write unit and behavioural tests for new functionality. Run both before and
   after making any change.
+
 - Every module **must** begin with a module level (`//!`) comment explaining the
   module's purpose and utility.
+
 - Document public APIs using Rustdoc comments (`///`) so documentation can be
   generated with cargo doc.
+
 - Prefer immutable data and avoid unnecessary `mut` bindings.
+
 - Handle errors with the `Result` type instead of panicking where feasible.
+
 - Use explicit version ranges in `Cargo.toml` and keep dependencies up-to-date.
+
 - Avoid `unsafe` code unless absolutely necessary, and document any usage
   clearly.
+
 - Place function attributes **after** doc comments.
+
 - Do not use `return` in single-line functions.
+
 - Use predicate functions for conditional criteria with more than two branches.
+
 - Lints must not be silenced except as a **last resort**.
+
 - Lint rule suppressions must be tightly scoped and include a clear reason.
+
 - Prefer `expect` over `allow`.
+
 - Use `rstest` fixtures for shared setup.
+
 - Replace duplicated tests with `#[rstest(...)]` parameterized cases.
+
 - Prefer `mockall` for mocks/stubs.
+
 - Use `concat!()` to combine long string literals rather than escaping newlines
   with a backslash.
+
 - Prefer single line versions of functions where appropriate. i.e.,
 
   ```rust

README.md

@@ -74,6 +74,38 @@ mdtablefix [--version] [--wrap] [--renumber] [--breaks] [--ellipsis] [--fences]
 - If no files are specified, input is read from stdin and output is written to
   stdout.
 
+## YAML frontmatter
+
+Documents that begin with a YAML frontmatter block have that block preserved
+exactly while the remainder of the document is formatted. A frontmatter block
+starts with a line containing exactly `---` and ends with a line containing
+exactly `---` or `...`. Only a block at the very beginning of the document is
+recognized as frontmatter.
+
+Before:
+
+```markdown
+---
+title: My Document
+author: Jane Doe
+---
+|Character|Catchphrase|
+|---|---|
+|Speedy|Here come the cats!|
+```
+
+After running `mdtablefix`:
+
+```markdown
+---
+title: My Document
+author: Jane Doe
+---
+| Character | Catchphrase         |
+| --------- | ------------------- |
+| Speedy    | Here come the cats! |
+```
+
 ## Concurrency
 
 When multiple file paths are supplied, `mdtablefix` processes them in parallel

docs/architecture.md

@@ -20,15 +20,21 @@ pub fn process_stream_inner(lines: &[String], opts: Options) -> Vec<String>
 
 The function combines several helpers documented in `docs/`:
 
+- `frontmatter::split_leading_yaml_frontmatter` detects and splits a leading
+  YAML frontmatter block from the document body. A valid frontmatter block
+  starts with `---` on the first line and ends with `---` or `...` before any
+  body content. The prefix is preserved verbatim while only the body is
+  processed. This shielding also applies to CLI-only transforms such as
+  `renumber_lists` and `format_breaks`.
 - `fences::compress_fences` and `attach_orphan_specifiers` normalize code block
   delimiters. The latter keeps indentation from the language line when the
   fence lacks it. Language specifiers explicitly set to `null`
   (case-insensitive) or consisting solely of whitespace are treated as absent.
   `compress_fences` also tolerates spaces within comma-separated specifiers,
   e.g. `TOML, Ini` becomes `toml,ini`.
 - `html::convert_html_tables` transforms basic HTML tables into Markdown so \
-    they can be reflowed like regular tables. See \
-    [HTML table support](#html-table-support-in-mdtablefix).
+  they can be reflowed like regular tables. See \
+  [HTML table support](#html-table-support-in-mdtablefix).
 - `wrap::wrap_text` applies optional line wrapping. It relies on the
   `unicode-width` crate for accurate character widths.
 - `wrap::tokenize_markdown` emits `Token` values for custom processing.
@@ -48,7 +54,7 @@ incoming lines are buffered or emitted. Once the end of a table or fence is
 reached, buffered lines are flushed and possibly reformatted. The simplified
 behaviour is illustrated below.
 
-```mermaid
+````mermaid
 stateDiagram-v2
 
     [*] --> Streaming: Start
@@ -72,7 +78,7 @@ stateDiagram-v2
     InHtmlTable --> InHtmlTable: Line inside table tag
 
     InCodeFence --> Streaming: Line is a fence delimiter
-```
+````
 
 Before:
 

docs/documentation-style-guide.md

@@ -9,9 +9,9 @@ Apply these rules to keep the documentation clear and consistent for developers.
   [Oxford English Dictionary](https://public.oed.com/) locale `en-GB`, which
   denotes English for the Great Britain market:
   - suffix -ize in words like _realize_ and _organization_ instead of
-     -ise endings,
+    -ise endings,
   - suffix ‑lyse in words not traced to the Greek ‑izo, ‑izein suffixes,
-     such as _analyse_, _paralyse_ and _catalyse_,
+    such as _analyse_, _paralyse_ and _catalyse_,
   - suffix -our in words such as _colour_, _behaviour_ and _neighbour_,
   - suffix -re in words such as _calibre_, _centre_ and _fibre_,
   - double "l" in words such as _cancelled_, _counsellor_ and _cruellest_,
@@ -87,7 +87,7 @@ contents of the manual.
   they do not execute during documentation tests.
 - Put function attributes after the doc comment.
 
-```rust,no_run
+````rust,no_run
 /// Returns the sum of `a` and `b`.
 ///
 /// # Parameters
@@ -106,7 +106,7 @@ contents of the manual.
 pub fn add(a: i32, b: i32) -> i32 {
     a + b
 }
-```
+````
 
 ## Diagrams and images