{"id":47767622,"url":"https://github.com/jeduden/mdsmith","last_synced_at":"2026-06-07T10:01:08.930Z","repository":{"id":337319398,"uuid":"1153065898","full_name":"jeduden/mdsmith","owner":"jeduden","description":"fast, auto-fixing Markdown linter and formatter. Checks style, readability, structure, and cross-file integrity.","archived":false,"fork":false,"pushed_at":"2026-05-03T21:23:40.000Z","size":174957,"stargazers_count":4,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T21:27:34.373Z","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":".github/CODEOWNERS","security":"docs/security/2026-04-05-adversarial-markdown.md","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-05-03T21:01:56.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":14,"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":32783528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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-06-07T10:01:08.924Z","avatar_url":"https://github.com/jeduden.png","language":"Go","funding_links":[],"categories":["Text Processing","Template Engines"],"sub_categories":["Markup Languages"],"readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"website/static/img/logo-lockup-inverse.svg\"\u003e\n\u003cimg src=\"website/static/img/logo-lockup.svg\" alt=\"mdsmith\" width=\"320\"\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n[![Build][ci-badge]][ci-link]\n[![Quality][grc-badge]][grc-link]\n[![Coverage][cov-badge]][cov-link]\n\n\u003c?include\nfile: docs/brand/fragments/headline.fragment.md\n?\u003e\n\u003c!-- Generated by `mdsmith-release sync-messaging` from\ndocs/brand/messaging.md — do not edit by hand. --\u003e\n\nMark*down*, smithed.\n\u003c?/include?\u003e\n\n\u003c?include\nfile: docs/brand/fragments/eyebrow.fragment.md\n?\u003e\n\u003c!-- Generated by `mdsmith-release sync-messaging` from\ndocs/brand/messaging.md — do not edit by hand. --\u003e\n\nMarkdown as a single source of truth\n\u003c?/include?\u003e\n\n\u003c?include\nfile: docs/brand/fragments/tagline.fragment.md\n?\u003e\n\u003c!-- Generated by `mdsmith-release sync-messaging` from\ndocs/brand/messaging.md — do not edit by hand. --\u003e\n\nWrite content; mdsmith keeps your Markdown neat and consistent — fast\nenough to stay out of your way. Auto-fix on save, instant navigation,\ncross-file integrity, and generated sections that keep a single source of\ntruth in sync across files and pipelines.\n\u003c?/include?\u003e\n\nOne static Go binary checks this whole repository in well under a\nsecond. That is an order of magnitude faster than Node\nmarkdownlint. It does more per file than the Rust linters. The\nfigures are re-measured on every merge and refreshed each release.\nSee the [latest cross-tool benchmark][bench-live] for the current\nper-tool ratios on both corpora.\n\n\u003c!-- Rendered by .github/workflows/demo.yml on push to main; published to the assets branch --\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"mdsmith auto-fixing and checking Markdown\" width=\"880\"\nsrc=\"https://raw.githubusercontent.com/jeduden/mdsmith/assets/assets/demo.gif\"\u003e\n\u003c/p\u003e\n\n\u003c?include\nfile: docs/features/index.md\nstrip-frontmatter: \"true\"\nheading-level: \"2\"\n?\u003e\n## Why mdsmith\n\nmdsmith is a Markdown linter and formatter written in Go. It\nchecks style, readability, structure, and cross-file integrity,\nand auto-fixes what fixes cleanly. Where markdownlint-compatible\nlinters stop at per-file style, mdsmith adds the cross-file graph,\ngenerated sections, structure schemas, and readability budgets.\nTogether they keep a whole docs tree consistent as it grows, so\nthe same Markdown can drive your README, your docs site, and\ndownstream pipelines.\n\nOne rule engine runs everywhere you work: in CI, in your editor\nthrough `mdsmith lsp`, and in your coding agent through a Claude\nCode plugin. The check that blocks a merge is the same one you see\nas you type, so feedback never depends on which tool you opened.\n\n### Clean, consistent Markdown\n\nCatch style, formatting, and readability problems on every file.\n`mdsmith fix` rewrites the ones with a single correct fix;\n`mdsmith check` is the read-only gate for CI.\n\n**[Auto-fix Markdown formatting](docs/features/auto-fix.md).**\n`mdsmith fix` rewrites whitespace, headings, code fences, bare\nURLs, list indentation, and table alignment in place, looping\nuntil edits stabilize. `mdsmith check` runs the same rules\nread-only for CI.\n\n**[Conventions and flavors](docs/features/markdown-conventions.md).**\nPin one convention to apply a curated rule preset and a target\nrenderer flavor together. `MDS034` flags syntax the flavor will\nnot render; a placeholder vocabulary leaves template tokens like\n`{name}` alone.\n\n**[Size and readability limits](docs/features/size-and-readability.md).**\nCap file, section, and token-budget size, enforce a reading grade\nand sentence count, and flag verbatim copy-paste between files.\nThree rules ship on by default; two are opt-in.\n\n### One engine, every surface\n\nThe same engine runs in CI, in your editor, and in your coding\nagent, from one fast static binary you can install through any\nchannel.\n\n**[Live diagnostics wherever you write](docs/features/live-diagnostics.md).**\n`mdsmith lsp` serves diagnostics, quick-fixes, and navigation\n(definition, references, symbol search, and a call hierarchy) to\nany LSP-aware editor over stdio.\n\n**[Editors and agents](docs/features/editor-agent-integration.md).**\nA bundled VS Code extension and a Claude Code plugin drive that\nsame server, so diagnostics, fix-on-save, and navigation reach\nyour editor and your agent with no separate install. The `.vsix`\nis republished to Open VSX for Cursor, VSCodium, and Theia.\n\n**[Fast on every run](docs/features/performance.md).**\nOne static Go binary, no runtime to start. The workspace walk runs\nacross all cores, and includes are linted once. A full check of\nthis repository's Markdown takes about 0.5 s, an order of\nmagnitude faster than Node markdownlint.\n\n**[Installs everywhere](docs/features/install-everywhere.md).**\nThe same version-stamped binary ships through go install, npm,\npip, uvx, Homebrew, mise, asdf, and GitHub Releases. No\npostinstall network call, so locked-down CI installs offline.\n\n### A connected docs tree\n\nmdsmith reads the links, includes, and headings that tie your\nfiles together, so a rename or a move never strands a reference.\n\n**[Cross-file integrity](docs/features/cross-file-integrity.md).**\n`MDS027` flags broken links and missing anchors across the\nworkspace, `MDS020` validates each file against its section\nschema, and `MDS033` keeps files in their allowed folders.\n\n**[Rename without breaking links](docs/features/rename.md).**\nRename a heading and mdsmith rewrites every workspace anchor link\nthat resolved to its slug in one atomic edit. Link-reference\nlabels rename with their uses; a colliding slug fails loudly\ninstead of breaking links.\n\n**[See the dependency graph](docs/features/dependency-graph.md).**\n`mdsmith deps` lists what a file pulls in (includes, catalogs,\nbuild sources, and links), or every file that points at it with\n`--incoming`. The editor walks the same graph as a call hierarchy.\n\n**[File kinds and schemas](docs/features/file-kinds-schemas.md).**\nTag each file with a `kind`, then validate its headings, section\norder, and front matter against a schema. Declare the schema\ninline on the kind or share it from a `proto.md` template, so a\nwhole directory obeys one contract.\n\n### Markdown as a single source of truth\n\nEach file stays the single source of truth. mdsmith keeps the\ngenerated parts in sync, and can project the file out as JSON,\nYAML, or msgpack.\n\n**[Self-maintaining sections](docs/features/self-maintaining-sections.md).**\nOn `mdsmith fix`, `\u003c?toc?\u003e` rebuilds a heading table of contents,\n`\u003c?catalog?\u003e` generates an index from front matter, and\n`\u003c?include?\u003e` splices in another file. A Git merge driver resolves\nconflicts inside those blocks.\n\n**[Build artifacts in sync](docs/features/build-artifacts.md).**\nThe `\u003c?build?\u003e` directive declares an artifact and a recipe;\n`mdsmith fix` rebuilds the section body from the recipe output so\nthe doc never quotes a stale file. `MDS040` shell-safety-checks\nthe recipe without running it.\n\n**[Markdown as a data source](docs/features/markdown-as-data.md).**\n`mdsmith extract` projects a schema-conformant file to a JSON,\nYAML, or msgpack tree, and `\u003c?include extract:?\u003e` reads one value\nback into another file. `mdsmith export` writes a portable,\ndirective-free copy that renders on any Markdown tool.\n\n### Built for your pipeline\n\nRelease gates, a Git merge driver, transparent config, and a\ncoverage-gated build make mdsmith safe to wire into a shared\nrepository.\n\n**[Gate releases on doc status](docs/features/release-gating.md).**\n`mdsmith list query 'status: \"✅\"' plan/` selects files by a CUE\nexpression on front matter, and `mdsmith metrics rank` orders\nfiles by any shared metric. Both print plain lines ready to pipe\ninto a release script.\n\n**[Git-native, conflict-free](docs/features/git-native.md).**\nA Git merge driver re-runs the directive and keeps the regenerated\nbody when two branches both touch a generated block. A\npre-merge-commit hook re-runs `mdsmith fix` and re-stages the\nresult, so generated content never blocks a merge.\n\n**[Config you can explain](docs/features/config-transparency.md).**\nConfig layers deep-merge rule by rule: defaults, convention,\nkinds, then per-glob overrides. `mdsmith check --explain` and\n`mdsmith kinds resolve` show which layer set each effective value.\n\n**[Quality you can verify](docs/features/quality.md).**\nThe CI, Go Report Card, and Codecov badges report live project\nhealth. mdsmith lints its own docs with the rules it ships, and a\ncoverage gate blocks any merge that drops below the line.\n\u003c?/include?\u003e\n\n## 🚀 Quickstart\n\n```bash\ngo install github.com/jeduden/mdsmith/cmd/mdsmith@latest  # or npm / pip / brew (see Installation)\nmdsmith check .   # lint every Markdown file; non-zero exit on failure (CI-ready)\nmdsmith fix .     # auto-fix what fixes cleanly, in place\n```\n\n`check` prints each problem — location, rule, and a source snippet\nwith a caret under the offending column — then a summary, exiting non-zero:\n\n```text\ndocs/guide.md:1:81 MDS001 line too long (89 \u003e 80)\n1 | # This heading runs deliberately long so that it spills well past the eighty-column limit\n····················································································^\nstats: checked=1 fixed=0 failures=1 unfixed=1\n```\n\n## 📦 Installation\n\nCLI:\n\n```bash\ngo install github.com/jeduden/mdsmith/cmd/mdsmith@latest\nnpm install -g @mdsmith/cli    # or: npx @mdsmith/cli\npip install mdsmith            # or: uvx mdsmith / pipx install mdsmith\nbrew install jeduden/mdsmith/mdsmith   # macOS / Linux (Homebrew)\n```\n\nEditor extension (LSP-backed; runs `mdsmith lsp`):\n\n```bash\ncode --install-extension jeduden.mdsmith     # VS Code, Codespaces (Marketplace)\ncodium --install-extension jeduden.mdsmith   # Cursor, VSCodium, Theia, Gitpod (Open VSX)\n```\n\nClaude Code plugin (diagnostics + cross-file navigation in your agent):\n\n```text\n/plugin marketplace add jeduden/mdsmith\n/plugin install mdsmith-lsp@mdsmith\n/reload-plugins\n```\n\nMore: the [install guide](docs/guides/install.md) covers asdf, mise,\nand direct downloads; [VS Code setup](docs/guides/editors/vscode.md)\ncovers settings and troubleshooting.\n\n## 🚀 Usage\n\n```text\nmdsmith \u003ccommand\u003e [flags] [files...]\n```\n\n### Commands\n\n\u003c?catalog\nglob:\n  - \"docs/reference/cli/*.md\"\nsort: command\nheader: |\n  | Command | Description |\n  |---------|-------------|\nrow: \"| [`{command}`]({filename}) | {summary} |\"\n?\u003e\n| Command                                                      | Description                                                                          |\n| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |\n| [`check`](docs/reference/cli/check.md)                       | Lint Markdown files for style issues.                                                |\n| [`deps`](docs/reference/cli/deps.md)                         | List a file's dependency-graph edges (includes, links, catalogs, builds).            |\n| [`export`](docs/reference/cli/export.md)                     | Write a portable, directive-free copy of a Markdown file.                            |\n| [`extract`](docs/reference/cli/extract.md)                   | Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.             |\n| [`fix`](docs/reference/cli/fix.md)                           | Auto-fix lint issues in Markdown files in place.                                     |\n| [`help`](docs/reference/cli/help.md)                         | Show built-in documentation for rules, metrics, and concept pages.                   |\n| [`init`](docs/reference/cli/init.md)                         | Generate a default `.mdsmith.yml` config in the current directory.                   |\n| [`kinds`](docs/reference/cli/kinds.md)                       | Inspect declared file kinds and resolve effective rule config per file.              |\n| [`list`](docs/reference/cli/list.md)                         | Selection-style commands that walk the workspace and emit matches.                   |\n| [`list backlinks`](docs/reference/cli/backlinks.md)          | List workspace links that point at a file.                                           |\n| [`list query`](docs/reference/cli/query.md)                  | Select Markdown files by a CUE expression on front matter.                           |\n| [`lsp`](docs/reference/cli/lsp.md)                           | Run a Language Server Protocol server on stdio for editor integrations.              |\n| [`merge-driver`](docs/reference/cli/merge-driver.md)         | Git merge driver that resolves conflicts inside generated sections.                  |\n| [`metrics`](docs/reference/cli/metrics.md)                   | List and rank shared Markdown metrics (file length, token estimate, readability, …). |\n| [`pre-merge-commit`](docs/reference/cli/pre-merge-commit.md) | Install / manage a pre-merge-commit hook that runs `mdsmith fix` after a merge.      |\n| [`rename`](docs/reference/cli/rename.md)                     | Rename a heading or link-reference label and rewrite every dependent edit.           |\n| [`version`](docs/reference/cli/version.md)                   | Print the mdsmith build version and exit.                                            |\n\u003c?/catalog?\u003e\n\nThat command table and the feature list above are generated by mdsmith's own directives.\n\nFiles can be paths, directories (walked for `*.md`/`*.markdown`), or\nglobs; directories respect `.gitignore` (`--no-gitignore` overrides).\nThe [CLI reference](docs/reference/cli.md) covers shared flags, exit\ncodes, output, and merge semantics; each page has its own examples.\n\n## ⚙️ Configuration\n\n`mdsmith init` writes a `.mdsmith.yml` of all rules at their defaults;\nwithout one, built-in defaults apply.\n\n```yaml\nrules:\n  line-length:\n    max: 120\n  fenced-code-language: false\n\noverrides:\n  - glob: [\"CHANGELOG.md\"]\n    rules:\n      no-duplicate-headings: false\n```\n\nEach rule is `true` (default), `false` (off), or an object of settings.\n`overrides` apply per glob; later entries win. Config is found by walking\nup to the repo root. Commit it so contributors share one ruleset and\nupgrades stay reviewable.\n\n## 📚 More\n\n- [How mdsmith compares](docs/background/markdown-linters.md) to other linters\n- [Guides](docs/guides/index.md) — directives, structure, migration\n- [Rule directory](internal/rules/index.md) — every rule with status\n- [CLI reference](docs/reference/cli.md)\n- [Contributor guide](docs/development/index.md) — Go 1.24+, build, test, style\n\n## 📄 License\n\n[MIT](LICENSE)\n\n\u003c!-- badges --\u003e\n\n[ci-badge]: https://github.com/jeduden/mdsmith/actions/workflows/ci.yml/badge.svg?branch=main\n[ci-link]: https://github.com/jeduden/mdsmith/actions/workflows/ci.yml?query=branch%3Amain\n[grc-badge]: https://goreportcard.com/badge/github.com/jeduden/mdsmith\n[grc-link]: https://goreportcard.com/report/github.com/jeduden/mdsmith\n[cov-badge]: https://codecov.io/gh/jeduden/mdsmith/branch/main/graph/badge.svg\n[cov-link]: https://codecov.io/gh/jeduden/mdsmith/branch/main\n[bench-live]: https://github.com/jeduden/mdsmith/blob/assets/assets/benchmarks/results.fragment.md\n","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"}