{"id":47767622,"url":"https://github.com/jeduden/mdsmith","last_synced_at":"2026-04-03T07:44:02.082Z","repository":{"id":337319398,"uuid":"1153065898","full_name":"jeduden/mdsmith","owner":"jeduden","description":"Lint and format the Markdown agents read and write","archived":false,"fork":false,"pushed_at":"2026-03-26T21:47:42.000Z","size":1597,"stargazers_count":0,"open_issues_count":19,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T09:40:53.204Z","etag":null,"topics":["ai-generated-code","ai-generated-content","formatter","go","golang","linter","markdown","readme","spec-driven","spec-driven-development","specification","style"],"latest_commit_sha":null,"homepage":"","language":"Go","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/jeduden.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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-08T21:03:38.000Z","updated_at":"2026-03-18T17:37:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeduden/mdsmith","commit_stats":null,"previous_names":["jeduden/tidymark","jeduden/mdsmith"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jeduden/mdsmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeduden%2Fmdsmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeduden%2Fmdsmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeduden%2Fmdsmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeduden%2Fmdsmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeduden","download_url":"https://codeload.github.com/jeduden/mdsmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeduden%2Fmdsmith/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31342173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T06:57:30.245Z","status":"ssl_error","status_checked_at":"2026-04-03T06:57:29.849Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ai-generated-code","ai-generated-content","formatter","go","golang","linter","markdown","readme","spec-driven","spec-driven-development","specification","style"],"created_at":"2026-04-03T07:44:01.545Z","updated_at":"2026-04-03T07:44:02.077Z","avatar_url":"https://github.com/jeduden.png","language":"Go","readme":"# 🔨 mdsmith\n\nA fast, auto-fixing Markdown linter and formatter for docs, READMEs,\nand AI-generated content. Checks style, readability, and structure.\nWritten in Go.\n\n\u003c!-- Rendered by .github/workflows/demo.yml on push to main --\u003e\n![mdsmith demo](assets/demo.gif)\n\n## ✨ Why mdsmith\n\n**📋 Progressive disclosure with catalogs.**\nThe [`catalog`](internal/rules/MDS019-catalog/README.md) rule generates summary\ntables from file front matter and keeps them in sync.\nLink each row to the full document —\nreaders see the overview first and drill down on demand.\nRun `mdsmith fix` and the table updates itself.\n\n**🤖 Keep AI verbosity in check.**\nAI tools produce walls of text.\n[`max-file-length`](internal/rules/MDS022-max-file-length/README.md)\ncaps document size,\n[`paragraph-readability`](internal/rules/MDS023-paragraph-readability/README.md)\nenforces a reading-grade ceiling,\nand [`paragraph-structure`](internal/rules/MDS024-paragraph-structure/README.md)\nlimits sentence count and length.\n[`token-budget`](internal/rules/MDS028-token-budget/README.md)\nadds a token-aware\nbudget with heuristic and tokenizer modes.\nSet the thresholds in `.mdsmith.yml` and let CI enforce them.\n\n**📖 AI-ready rule specs — no remote calls.**\n`mdsmith help rule` lists every rule with its ID and description.\n`mdsmith help rule \u003cname\u003e` prints the full spec: settings, examples,\ndiagnostics. All docs are compiled into the binary — works offline,\nworks in CI, works as a source for `.cursor/rules` or `AGENTS.md`.\n`mdsmith help metrics` and `mdsmith help metrics \u003cname\u003e` do the same\nfor shared file metrics.\n\n**🔧 Auto-fix.**\n`mdsmith fix` corrects most rules in place.\nWhitespace, heading style, code fences, bare URLs, list indentation,\ntable alignment, and generated sections — all handled.\nMulti-pass fixing resolves cascading changes automatically.\n\n## 📦 Installation\n\n```bash\ngo install github.com/jeduden/mdsmith/cmd/mdsmith@latest\n```\n\n## 🚀 Usage\n\n```text\nmdsmith \u003ccommand\u003e [flags] [files...]\n```\n\n### Commands\n\n| Command        | Description                                    |\n|----------------|------------------------------------------------|\n| `check`        | Lint files (default command)                   |\n| `fix`          | Auto-fix issues in place                       |\n| `query`        | Select files by CUE expression on front matter |\n| `help`         | Show help for docs and topics                  |\n| `metrics`      | List and rank Markdown metrics                 |\n| `merge-driver` | Git merge driver for regenerable sections      |\n| `init`         | Generate `.mdsmith.yml`                        |\n| `version`      | Print version, exit                            |\n\nFiles can be paths, directories (walked recursively for `*.md`),\nor glob patterns.\nWith no arguments and no piped input, mdsmith exits 0.\n\nWhen walking directories, mdsmith respects `.gitignore` files by default.\nFiles matched by `.gitignore` patterns are skipped, including patterns from\nnested `.gitignore` files in subdirectories and ancestor directories.\nExplicitly named file paths are never filtered by gitignore.\nUse `--no-gitignore` to disable this behavior and lint all files.\n\n### Flags\n\n| Flag             | Description      |\n|------------------|------------------|\n| `-c`, `--config` | Config path      |\n| `-f`, `--format` | `text` or `json` |\n| `--no-color`     | Plain output     |\n| `--no-gitignore` | Skip gitignore   |\n| `-q`, `--quiet`  | Quiet mode       |\n\n### Examples\n\n```bash\nmdsmith check docs/            # lint a directory\nmdsmith fix README.md          # auto-fix in place\nmdsmith check -f json docs/    # JSON output\nmdsmith metrics rank --by bytes --top 10 .\n```\n\n### Output\n\nDiagnostics are printed to stderr with source context when available:\n\n```text\nREADME.md:10:81 MDS001 line too long (135 \u003e 80)\n 8 | Context lines appear above and below the diagnostic with line numbers.\n 9 | They help you see the surrounding code at a glance.\n10 | This line is deliberately made long so it exceeds the eighty character limit and keeps going and going.\n·····················································································^\n11 | A dot path runs from column 1 to the caret, marking the line and column.\n12 | Up to two lines of context are shown on each side.\n```\n\nEach diagnostic shows a header (`file:line:col rule message`).\nWhen source context is available, up to 5 surrounding lines appear\nwith a dot path (`····^`) pointing to the exact column.\n\n### Exit codes\n\n| Code | Meaning                        |\n|------|--------------------------------|\n| 0    | No lint issues found           |\n| 1    | Lint issues found              |\n| 2    | Runtime or configuration error |\n\n## ⚙️ Configuration\n\nCreate a `.mdsmith.yml` in your project root, or run\n`mdsmith init` to generate one with every rule and its\ndefault settings.\nWithout a config file, rules run with their built-in\ndefaults.\n\n```yaml\nrules:\n  line-length:\n    max: 120\n  fenced-code-language: false\n\nignore:\n  - \"vendor/**\"\n\noverrides:\n  - files: [\"CHANGELOG.md\"]\n    rules:\n      no-duplicate-headings: false\n```\n\nRules can be `true` (enable with defaults), `false` (disable),\nor an object with settings.\nThe `overrides` list applies different rules per file pattern.\nLater overrides take precedence.\n\nConfig is discovered by walking up from the current directory to the repo root.\nUse `--config` to override.\n\n### Bootstrapping with `mdsmith init`\n\nRun `mdsmith init` to generate a `.mdsmith.yml` with every rule and its\ndefault enablement and settings. This pins the config to the current defaults so\nthat future\nmdsmith upgrades (which may change defaults) do not silently alter your\nlint results. Review the generated file and adjust settings to match your\nproject's conventions.\n\n```bash\nmdsmith init\n# creates .mdsmith.yml with all rule defaults\n```\n\nCommit the generated file to version control.\nThis ensures every contributor uses the same rule settings.\nUpgrades become an explicit, reviewable change.\n\n## 📚 Guides\n\nSee the [Guides index](docs/guides/index.md) for\ndirectives, structure enforcement, and migration.\n\n## 📏 Rules\n\nSee the\n[Rule Directory](internal/rules/index.md)\nfor the complete list with status and description.\n\n## 🛠️ Development\n\nRequires Go 1.24+. See\n[`docs/development/index.md`](docs/development/index.md) for the full\ncontributor guide (build commands, project layout,\nworkflow, code style, and PR conventions).\n\n## 📂 Documentation\n\n- [CLI design](docs/design/cli.md)\n- [Design archetypes](docs/design/archetypes/)\n- [Guides](docs/guides/)\n- [Background](docs/background/)\n- [Plans](plan/)\n\n## 📄 License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeduden%2Fmdsmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeduden%2Fmdsmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeduden%2Fmdsmith/lists"}