v0.5.0

FastMarkDocs v0.5.0

🚨 Breaking Changes

• Section-Based Documentation: Replace Tags: with Section: in markdown files
• Router Tags: Now scaffolding hints only; Section: controls documentation organization
• Linter: Requires Section: lines for all documented endpoints

✨ New Features

• Intelligent Section Inference: 6-step fallback chain (endpoint tags → router tags → path → file → function → "API")
• Smart Pattern Recognition: Auto-detects /health, /metrics, /auth patterns
• Enhanced Scaffolding: fmd-init suggests appropriate sections automatically
• Section Validation: Linter provides helpful suggestions for missing sections

🛠️ Improvements

• Cleaner Architecture: Separates FastAPI operational tags from documentation sections
• Better Developer Experience: Intelligent defaults reduce manual work
• Enhanced Coverage: 91% test coverage with 459 tests
• Robust Parsing: Improved error handling and validation

📚 Migration

• Migration Guide: Automated scripts and step-by-step instructions included
• Backward Compatible: Existing Tags: work during transition
• Simple Upgrade: Replace Tags: → Section:, run fmd-lint to validate

🔧 Technical

• Updated core data structures and OpenAPI generation
• Enhanced type safety and validation
• Improved scaffolder with intelligent inference

Migration: Update to fastmarkdocs>=0.5.0, replace Tags: with Section: in markdown files, validate with fmd-lint.

Full Changelog: v0.4.2...v0.5.0# FastMarkDocs v0.5.0

🚨 Breaking Changes

• Section-Based Documentation: Replace Tags: with Section: in markdown files
• Router Tags: Now scaffolding hints only; Section: controls documentation organization
• Linter: Requires Section: lines for all documented endpoints

✨ New Features

• Intelligent Section Inference: 6-step fallback chain (endpoint tags → router tags → path → file → function → "API")
• Smart Pattern Recognition: Auto-detects /health, /metrics, /auth patterns
• Enhanced Scaffolding: fmd-init suggests appropriate sections automatically
• Section Validation: Linter provides helpful suggestions for missing sections

🛠️ Improvements

• Cleaner Architecture: Separates FastAPI operational tags from documentation sections
• Better Developer Experience: Intelligent defaults reduce manual work
• Enhanced Coverage: 91% test coverage with 459 tests
• Robust Parsing: Improved error handling and validation

📚 Migration

• Migration Guide: Automated scripts and step-by-step instructions included
• Backward Compatible: Existing Tags: work during transition
• Simple Upgrade: Replace Tags: → Section:, run fmd-lint to validate

🔧 Technical

• Updated core data structures and OpenAPI generation
• Enhanced type safety and validation
• Improved scaffolder with intelligent inference

Migration: Update to fastmarkdocs>=0.5.0, replace Tags: with Section: in markdown files, validate with fmd-lint.

v0.4.2

Release Notes: v0.4.2

🐛 Bug Fixes

Fixed: fmd-lint False Positives for Multiple Endpoints per File

Critical Issue Resolved: The fmd-lint documentation linter was incorrectly reporting "missing documentation" errors when multiple API endpoints were documented in a single markdown file.

What was broken:

• Projects with multiple endpoints per markdown file would fail linting validation
• False positive "missing documentation" reports blocked CI/CD pipelines
• "Malformed code block" errors appeared for valid markdown syntax

What's fixed:

• Multiple endpoints per markdown file now validate correctly
• Enhanced endpoint extraction logic with robust error handling
• Improved code block parsing supports language-specific markers
• Eliminated false positive validation errors

🚀 Improvements

Enhanced Documentation Validation

• More reliable endpoint detection across complex markdown structures
• Better handling of edge cases in markdown parsing
• Improved error messages for actual documentation issues

Developer Experience

• Faster and more accurate documentation linting
• Reduced false positives in CI/CD validation workflows
• Better debugging information when real issues are found

💡 Impact

This release resolves a critical blocker for projects using fmd-lint to validate API documentation. Teams can now confidently organize multiple endpoints in single markdown files without encountering false validation errors.

Recommended for immediate upgrade if you're experiencing documentation linting issues with multi-endpoint files.

v0.4.1

Release Notes - v0.4.1

🐛 Bug Fixes

• Fixed duplicate subtitle generation: Eliminated redundant "App - Description - Description" patterns in OpenAPI descriptions by prioritizing general docs content over automatic subtitle concatenation
• Improved title preservation: Prevent overriding well-formed titles that already include the app name
• Enhanced quality checks: Updated linting to check entire codebase instead of just src/ directory

🔧 Improvements

• Broader compatibility: Lowered starlette dependency requirement to >=0.40.0 for better FastAPI version compatibility
• Code quality: Fixed import formatting issues across examples and test files

📦 Dependencies

• Updated mistune from 3.1.3 to 3.1.4
• Updated ruff from 0.12.10 to 0.12.12
• Updated safety from 3.6.0 to 3.6.1

🔒 Security

• Enhanced docs build safety to prevent potential path traversal issues

---

Full Changelog: v0.4.0...v0.4.1

v0.4.0

Multi-Format Response Examples Support - FastMarkDocs now automatically detects and handles non-JSON response examples including Prometheus metrics (text/plain), XML, YAML, HTML, and CSV formats. The enhanced ResponseExample type includes automatic content type detection while maintaining 100% backward compatibility with existing JSON examples.

Key Changes:

• Added automatic content type detection for diverse response formats
• Enhanced OpenAPI schema generation for non-JSON responses
• Fixed fmd-lint false positives for non-JSON endpoints
• Added comprehensive test coverage (25+ unit tests, 8 integration tests)
• Included sample Prometheus metrics documentation in test fixtures

v0.3.0

🚀 New Features

Duplicate Endpoint Detection

• Added duplicate endpoint detection to fmd-lint - The linter now identifies and reports when the same endpoint is documented multiple times across different files
• Enhanced CLI error reporting - Clear warnings show which files contain duplicate documentation with actionable suggestions
• CI/CD integration support - Duplicate endpoints cause linter failures (exit code 1), preventing inconsistent documentation from being merged

🐛 Bug Fixes

Cross-Platform Stability

• Fixed non-deterministic behavior - Resolved inconsistent results between different operating systems (macOS vs Ubuntu)
• Deterministic endpoint processing - Ensures consistent documentation generation across all environments

Documentation Processing

• Improved endpoint description extraction - Enhanced markdown processing to better separate endpoint descriptions from code examples
• Better content parsing - More accurate API documentation generation with cleaner content extraction

🔒 Security & Dependencies

• Updated vulnerable dependencies - Fixed security vulnerability in Starlette package
• Enhanced security compliance - Improved security posture with updated dependency versions

v0.2.7

• Prevent code samples from being included in the description, as they are already included in x-codesamples

v0.2.6

• Enhance OpenAPI tags with Overview section markdown
• Add support for tags in fmd-init
• Recursively scan for FastAPI REST endpoints we need to document
• Linter scans for TODO entries in documentation and reports them
• Fail lint when TODOs are still present in documentation
• Scaffolder always generates a general_docs.md

v0.2.4

• Exclusions now prevent orphaned documentation reports

v0.2.3

Unify analysis and spec generation code to remove code duplication

v0.2.2

• Add fmd-lint configuration file .fmd-lint.yaml