Use when generating markdown documents, reports, specs, or prose content - provides workflow to avoid formatting struggles and linting loops
Generate markdown documents cleanly without the view→edit→lint→fix loop.
The 150-line guidance on save-file was designed for code, not prose:
| Concern | Code | Prose/Markdown |
|---|---|---|
| Incremental verification | Critical - errors compound | Less relevant - auto-fix handles formatting |
| Hidden errors | One wrong char breaks things | Formatting is cosmetic |
| Build process | Each step should lint | Only final result matters |
For markdown: write complete content, let the hook auto-fix formatting.
1. save-file (full content, any length)
2. Hook runs markdownlint --fix automatically
3. Review any remaining errors (rare)
That's it.
The auto_lint.sh hook handles formatting automatically.
On every markdown file modification:
The mdsf tool formats code blocks using language-specific formatters configured
in ~/.config/mdsf/mdsf.json.
The auto-fixer handles formatting, but some issues require manual attention. Avoid these during generation:
❌ Wrong - the + at line start looks like a list item:
**Total:** 1 + 2 +
3 + 4 = 10
✅ Right - keep expressions on one line:
**Total:** 1 + 2 + 3 + 4 = 10
❌ Wrong:
\`\`\`
def foo():
pass
\`\`\`
✅ Right:
\`\`\`python
def foo():
pass
\`\`\`
❌ Wrong - row 2 has 2 columns, header has 3:
| A | B | C |
|---|---|---|
| 1 | 2 |
✅ Right:
| A | B | C |
|---|---|---|
| 1 | 2 | 3 |
| Scenario | Approach |
|---|---|
| Any markdown file | Use save-file with full content |
| Appending sections | Use str-replace-editor insert command |
| Fixing content issues | Use str-replace-editor (for content, not formatting) |
| Fixing formatting issues | Don't - let the hook handle it |
| Anti-pattern | Why It's Wrong | Instead |
|---|---|---|
| Manual blank line fixes | Hook does this automatically | Wait for hook |
| str-replace-editor for formatting | Wrong tool for prose | Let hook auto-fix |
| Multiple small writes | Creates boundary issues | Write complete content |
| Running markdownlint manually | Hook already runs it | Trust the hook |
| Chunking to stay under 150 lines | Guidance is for code, not prose | Write full content |
The hook reports errors it can't auto-fix. These are typically:
For these, use str-replace-editor to fix the content, not the formatting.
For documents with multiple sections, sketch an outline before writing:
1. Think through the structure (sections, flow)
2. Optionally share outline with user for approval
3. Then write full content
This catches structural issues before you've written 500 lines. Skip for simple documents (README, single-topic notes).
If your document includes code examples readers will copy/paste, test them before including. Broken examples erode trust faster than any other documentation failure.
For code-heavy documents (tutorials, API docs), consider running examples through a syntax checker or actually executing them.
For documents over 500 lines, consider:
topic-overview.md, topic-details.md)This aids navigation and makes updates easier.
User: "Create a performance analysis report"
1. Gather information (codebase-retrieval, view, etc.)
2. save-file with complete report content (any length)
3. Hook auto-fixes formatting
4. If errors remain: fix content issues only
5. Done
This replaces the old pattern of: write 150 lines → lint fails → fix → lint → fix → ... (15+ cycles)