{"id":28818440,"url":"https://github.com/gosayram/go-mdfmt","last_synced_at":"2026-04-12T23:36:19.849Z","repository":{"id":299038598,"uuid":"1001897269","full_name":"Gosayram/go-mdfmt","owner":"Gosayram","description":"A fast, reliable, and opinionated Markdown formatter written in Go. It provides a consistent, pluggable way to reformat .md files across projects - making your documentation readable, lintable, and style-consistent.","archived":false,"fork":false,"pushed_at":"2025-06-14T09:28:53.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-14T09:40:24.784Z","etag":null,"topics":["cli","devtools","formatter","go","go-mdfmt","golang","markdown","markdownformatter","mdfmt","prettify"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gosayram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T09:15:51.000Z","updated_at":"2025-06-14T09:28:56.000Z","dependencies_parsed_at":"2025-06-14T09:40:26.013Z","dependency_job_id":"df06c885-667d-4fd5-b8ba-05353028aa48","html_url":"https://github.com/Gosayram/go-mdfmt","commit_stats":null,"previous_names":["gosayram/go-mdfmt"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Gosayram/go-mdfmt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gosayram%2Fgo-mdfmt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gosayram%2Fgo-mdfmt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gosayram%2Fgo-mdfmt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gosayram%2Fgo-mdfmt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gosayram","download_url":"https://codeload.github.com/Gosayram/go-mdfmt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gosayram%2Fgo-mdfmt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260616539,"owners_count":23036867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","devtools","formatter","go","go-mdfmt","golang","markdown","markdownformatter","mdfmt","prettify"],"created_at":"2025-06-18T19:05:18.810Z","updated_at":"2025-10-30T20:39:42.233Z","avatar_url":"https://github.com/Gosayram.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-mdfmt\n\nA fast, reliable, and opinionated Markdown formatter written in Go. Provides consistent, configurable formatting for `.md` files across projects, making your documentation readable, lintable, and style-consistent.\n\n## Features\n\n**Core Formatting Capabilities**\n- **Text Reflow**: Wraps long paragraphs at configurable line width (default 80 characters)\n- **Heading Normalization**: Ensures consistent heading levels and spacing using ATX style\n- **List Standardization**: Consistent bullet and numbered list formatting with proper indentation\n- **Code Block Formatting**: Auto-corrects indentation and applies consistent fence styles\n- **Whitespace Management**: Removes excessive blank lines and trailing spaces\n- **Link Preservation**: Maintains markdown link structure and formatting\n\n**Operation Modes**\n- **Write Mode**: Format files in-place (`--write`)\n- **Check Mode**: Verify formatting without changes (`--check`) - ideal for CI/CD\n- **Diff Mode**: Preview changes before applying (`--diff`)\n- **List Mode**: Show files that need formatting (`--list`)\n- **Standard Output**: Display formatted content to stdout (default)\n\n**Configuration and Integration**\n- YAML-based configuration with sensible defaults\n- File pattern matching with ignore capabilities\n- Verbose and quiet output modes\n- CI/CD ready with meaningful exit codes\n- Cross-platform binary releases\n\n## Installation\n\n### Pre-built Binaries\n\nDownload the latest binary from the [releases page](https://github.com/Gosayram/go-mdfmt/releases):\n\n**Linux:**\n```bash\ncurl -L -o mdfmt https://github.com/Gosayram/go-mdfmt/releases/latest/download/mdfmt-0.2.6-linux-amd64\nchmod +x mdfmt\nsudo mv mdfmt /usr/local/bin/\n```\n\n**macOS:**\n```bash\ncurl -L -o mdfmt https://github.com/Gosayram/go-mdfmt/releases/latest/download/mdfmt-0.2.6-darwin-arm64\nchmod +x mdfmt\nsudo mv mdfmt /usr/local/bin/\n```\n\n**Windows:**\n```powershell\ncurl -L -o mdfmt.exe https://github.com/Gosayram/go-mdfmt/releases/latest/download/mdfmt-0.2.6-windows-amd64.exe\n```\n\n### From Source\n\n**Prerequisites:**\n- Go 1.24.4 or later\n- Git\n\n**Build from source:**\n```bash\ngit clone https://github.com/Gosayram/go-mdfmt.git\ncd go-mdfmt\nmake build\n# Binary will be available in bin/mdfmt\n```\n\n**Install from Go modules:**\n```bash\ngo install github.com/Gosayram/go-mdfmt/cmd/mdfmt@latest\n```\n\n## Quick Start\n\n### Basic Usage\n\n```bash\n# Format file to stdout\nmdfmt README.md\n\n# Format multiple files to stdout\nmdfmt docs/*.md\n\n# Format directory (finds all .md files)\nmdfmt docs/\n```\n\n### Write Changes to Files\n\n```bash\n# Format single file in-place\nmdfmt --write README.md\n\n# Format multiple files in-place\nmdfmt --write docs/*.md\n\n# Format all markdown files in project\nmdfmt --write .\n```\n\n### Check Formatting (CI/CD)\n\n```bash\n# Check if files are properly formatted\nmdfmt --check docs/\necho $? # Exit code: 0 = formatted, 1 = needs formatting, 2 = error\n\n# Show what would change\nmdfmt --diff README.md\n\n# List files that need formatting\nmdfmt --list docs/\n```\n\n## Command Line Interface\n\n```\nUSAGE:\n    mdfmt [OPTIONS] \u003cfiles...\u003e\n\nOPTIONS:\n    Operation modes (mutually exclusive):\n        -w, --write     Write formatted content back to files\n        -c, --check     Check if files are formatted correctly (exit 1 if not)\n        -l, --list      List files that need formatting\n        -d, --diff      Show diff of changes without writing files\n\n    Configuration:\n        --config \u003cfile\u003e Path to configuration file (.mdfmt.yaml)\n\n    Output control:\n        -v, --verbose   Verbose output (show processed files)\n        -q, --quiet     Quiet mode (suppress non-error output)\n\n    Information:\n        -h, --help      Show this help message\n        --version       Print version information\n\nEXIT CODES:\n    0   Success (no changes needed in check mode)\n    1   Files need formatting (check mode only)\n    2   Error occurred\n```\n\n## Configuration\n\nmdfmt uses YAML configuration files with automatic discovery. Configuration files are searched in this order:\n\n1. File specified by `--config` flag\n2. `.mdfmt.yaml` in current directory\n3. `.mdfmt.yaml` in parent directories (up to repository root)\n4. Built-in defaults\n\n### Configuration File Structure\n\nCreate `.mdfmt.yaml` in your project root:\n\n```yaml\n# Line width for paragraph reflow\nline_width: 80\n\n# Heading configuration\nheading:\n  style: \"atx\"              # Use # headings instead of === underline\n  normalize_levels: true    # Fix heading level jumps\n\n# List formatting\nlist:\n  bullet_style: \"-\"         # Use - for bullets (options: -, *, +)\n  number_style: \".\"         # Use 1. for numbered lists (options: ., ))\n  consistent_indentation: true\n\n# Code block formatting\ncode:\n  fence_style: \"```\"        # Use ``` for code blocks (options: ```, ~~~)\n  language_detection: true  # Auto-detect and add language labels\n\n# Whitespace handling\nwhitespace:\n  max_blank_lines: 2        # Maximum consecutive blank lines\n  trim_trailing_spaces: true\n  ensure_final_newline: true\n\n# File processing\nfiles:\n  extensions: [\".md\", \".markdown\", \".mdown\"]\n  ignore_patterns: [\"node_modules/**\", \".git/**\", \"vendor/**\"]\n```\n\n### Configuration Validation\n\nAll configuration options are validated on startup. Invalid configurations will result in descriptive error messages.\n\n## Development\n\n### Building from Source\n\n```bash\n# Install dependencies\nmake deps\n\n# Build for current platform\nmake build\n\n# Build for all platforms\nmake build-cross\n\n# Run tests\nmake test\n\n# Run linters and static analysis\nmake lint staticcheck\n\n# Format code\nmake fmt\n\n# Install to /usr/local/bin\nmake install\n```\n\n### Available Make Targets\n\n**Building and Running:**\n- `make build` - Build for current OS/architecture\n- `make build-cross` - Build binaries for multiple platforms\n- `make install` - Install binary to /usr/local/bin\n- `make run ARGS=\"README.md\"` - Run application locally\n\n**Testing and Validation:**\n- `make test` - Run all tests with coverage\n- `make test-race` - Run tests with race detection\n- `make benchmark` - Run performance benchmarks\n- `make check-all` - Run all code quality checks\n\n**Code Quality:**\n- `make fmt` - Format Go code\n- `make lint` - Run golangci-lint\n- `make staticcheck` - Run static analysis\n- `make vet` - Run go vet\n\n**Development:**\n- `make deps` - Install dependencies\n- `make clean` - Clean build artifacts\n- `make help` - Show all available targets\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Markdown Format Check\non: [push, pull_request]\n\njobs:\n  markdown-format:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v4\n      \n      - name: Download mdfmt\n        run: |\n          curl -L -o mdfmt https://github.com/Gosayram/go-mdfmt/releases/latest/download/mdfmt-0.2.6-linux-amd64\n          chmod +x mdfmt\n          sudo mv mdfmt /usr/local/bin/\n      \n      - name: Check markdown formatting\n        run: mdfmt --check --verbose .\n```\n\n### Pre-commit Hook\n\n```bash\n#!/bin/sh\n# .git/hooks/pre-commit\n\nmarkdown_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\\.md$')\n\nif [ -n \"$markdown_files\" ]; then\n    echo \"Checking markdown formatting...\"\n    if ! mdfmt --check $markdown_files; then\n        echo \"Markdown files need formatting. Run: mdfmt --write $markdown_files\"\n        exit 1\n    fi\nfi\n```\n\n### Makefile Integration\n\n```makefile\n.PHONY: fmt-markdown check-markdown\n\nfmt-markdown:\n\tmdfmt --write .\n\ncheck-markdown:\n\tmdfmt --check --diff .\n\n# Include in existing targets\nfmt: fmt-go fmt-markdown\ncheck: check-go check-markdown\n```\n\n## Architecture\n\ngo-mdfmt follows a modular architecture with clear separation of concerns:\n\n**Core Components:**\n- **Parser** (`pkg/parser`) - Goldmark-based Markdown AST parsing\n- **Formatter** (`pkg/formatter`) - Rule-based formatting engine\n- **Renderer** (`pkg/renderer`) - AST to Markdown conversion\n- **Config** (`pkg/config`) - YAML-based configuration management\n- **Processor** (`pkg/processor`) - File handling and batch processing\n\n**Internal Modules:**\n- **Version** (`internal/version`) - Build information and versioning\n\n**CLI Interface:**\n- **Main** (`cmd/mdfmt`) - Command-line interface and argument parsing\n\n## Performance\n\nmdfmt is designed for performance with large codebases:\n\n- **Memory Efficient**: Processes files individually, not batch-loaded\n- **Fast Parsing**: Uses goldmark parser for reliable AST generation\n- **Concurrent Safe**: Supports concurrent file processing\n- **Minimal Dependencies**: Small binary size with fast startup\n\n**Benchmarks** (on test machine):\n- Small files (\u003c 10KB): ~1ms per file\n- Medium files (10-100KB): ~5-15ms per file\n- Large files (\u003e 100KB): ~50-200ms per file\n\n## Security\n\n### Release Verification\n\nAll binaries are signed with Cosign for supply chain security:\n\n```bash\n# Download release files\ncurl -L -o mdfmt https://github.com/Gosayram/go-mdfmt/releases/download/v0.2.5/mdfmt-0.2.6-linux-amd64\ncurl -L -o mdfmt.sig https://github.com/Gosayram/go-mdfmt/releases/download/v0.2.5/mdfmt-0.2.6-linux-amd64.sig\ncurl -L -o cosign.pub https://github.com/Gosayram/go-mdfmt/releases/download/v0.2.5/cosign.pub\n\n# Verify signature\ncosign verify-blob --key cosign.pub --signature mdfmt.sig mdfmt\n\n# Verify checksum\ncurl -L -o mdfmt.sha256 https://github.com/Gosayram/go-mdfmt/releases/download/v0.2.5/mdfmt-0.2.6-linux-amd64.sha256\nsha256sum -c mdfmt.sha256\n```\n\n### Security Scanning\n\nThe project includes automated security scanning:\n- **Dependency Review**: Automated dependency vulnerability scanning\n- **CodeQL Analysis**: Static security analysis\n- **OpenSSF Scorecard**: Supply chain security assessment\n- **SLSA Compliance**: Software supply chain integrity\n\n## Comparison with Alternatives\n\n**vs Prettier:**\n- **Specialization**: Purpose-built for Markdown vs universal formatter\n- **Performance**: Native binary vs Node.js runtime overhead\n- **Configuration**: Markdown-specific options vs generic formatting rules\n- **Integration**: Better suited for Go/CLI environments\n\n**vs Other Markdown Tools:**\n- **Reliability**: Consistent AST-based parsing vs regex-based approaches\n- **Speed**: Optimized for large codebases and CI/CD pipelines\n- **Standards**: Follows CommonMark specification\n- **Maintenance**: Active development with regular releases\n\n## Contributing\n\nContributions are welcome. Please ensure all code follows the project standards:\n\n1. **Code Quality**: All Go code must pass `make check-all`\n2. **Testing**: Include tests for new functionality\n3. **Documentation**: Update relevant documentation\n4. **Commit Messages**: Use conventional commit format\n\n**Development Setup:**\n```bash\ngit clone https://github.com/Gosayram/go-mdfmt.git\ncd go-mdfmt\nmake deps\nmake build\nmake test\n```\n\n## License\n\nLicensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Support\n\n- **Issues**: Report bugs and feature requests on [GitHub Issues](https://github.com/Gosayram/go-mdfmt/issues)\n- **Documentation**: Additional documentation available in [docs/](docs/)\n- **Security**: Report security issues privately to project maintainers ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgosayram%2Fgo-mdfmt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgosayram%2Fgo-mdfmt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgosayram%2Fgo-mdfmt/lists"}