Summary
make fmt currently cannot be used as a clean documentation gate because the
Markdown formatting step rewrites existing documents and then fails with
MD013/line-length errors. The affected documents need to be reviewed and
updated so their content intentionally reflects the formatter’s style rather
than leaving every branch to restore unrelated Markdown churn.
Affected documents
The current formatter run reports line-length failures in:
docs/netsuke-design.mddocs/ortho-config-users-guide.mddocs/rstest-bdd-users-guide.mddocs/rust-doctest-dry-guide.mddocs/rust-testing-with-rstest-fixtures.mddocs/snapshot-testing-in-netsuke-using-insta.mddocs/translators-guide.md
The failure was observed via:
make fmt runs:
cargo fmt --all
mdformat-all
The Rust formatting check passes, but mdformat-all invokes Markdown
formatting/linting and reports MD013/line-length violations after rewriting
documentation.
Problem
This creates two practical issues:
- Feature branches that touch documentation cannot rely on
make fmt as a
clean, all-or-nothing formatting gate.
- Agents and contributors must restore unrelated Markdown rewrites before
committing otherwise scoped changes, which makes review noisier and weakens
confidence in documentation formatting.
Required work
Update the affected documents so they conform to the repository’s formatter and
Markdown lint expectations.
The work should include:
- Reviewing the formatter changes rather than applying them blindly.
- Preserving technical meaning, examples, diagrams, tables, and code blocks.
- Wrapping prose to the documented 80-column style where appropriate.
- Using scoped
markdownlint disables only where wrapping would damage
readability or correctness, such as generated examples, long URLs, tables, or
Mermaid syntax.
- Confirming that the formatter’s output is acceptable and stable.
Acceptance criteria
make fmt exits successfully without leaving unrelated Markdown churn.make markdownlint exits successfully.make nixie exits successfully.- The affected documents still read correctly after reflowing.
- Any intentional exceptions are narrowly scoped and documented inline.
Notes
This issue is about bringing existing documentation into alignment with the
formatter. It should not change Rust code or alter product behaviour.
Summary
make fmtcurrently cannot be used as a clean documentation gate because theMarkdown formatting step rewrites existing documents and then fails with
MD013/line-lengtherrors. The affected documents need to be reviewed andupdated so their content intentionally reflects the formatter’s style rather
than leaving every branch to restore unrelated Markdown churn.
Affected documents
The current formatter run reports line-length failures in:
docs/netsuke-design.mddocs/ortho-config-users-guide.mddocs/rstest-bdd-users-guide.mddocs/rust-doctest-dry-guide.mddocs/rust-testing-with-rstest-fixtures.mddocs/snapshot-testing-in-netsuke-using-insta.mddocs/translators-guide.mdThe failure was observed via:
make fmtruns:The Rust formatting check passes, but
mdformat-allinvokes Markdownformatting/linting and reports
MD013/line-lengthviolations after rewritingdocumentation.
Problem
This creates two practical issues:
make fmtas aclean, all-or-nothing formatting gate.
committing otherwise scoped changes, which makes review noisier and weakens
confidence in documentation formatting.
Required work
Update the affected documents so they conform to the repository’s formatter and
Markdown lint expectations.
The work should include:
markdownlintdisables only where wrapping would damagereadability or correctness, such as generated examples, long URLs, tables, or
Mermaid syntax.
Acceptance criteria
make fmtexits successfully without leaving unrelated Markdown churn.make markdownlintexits successfully.make nixieexits successfully.Notes
This issue is about bringing existing documentation into alignment with the
formatter. It should not change Rust code or alter product behaviour.