{"id":15048103,"url":"https://github.com/github/markdownlint-github","last_synced_at":"2025-04-13T02:10:39.169Z","repository":{"id":65974864,"uuid":"518744654","full_name":"github/markdownlint-github","owner":"github","description":"An opinionated collection of markdownlint rules used by GitHub.","archived":false,"fork":false,"pushed_at":"2025-04-07T18:03:19.000Z","size":420,"stargazers_count":80,"open_issues_count":5,"forks_count":3,"subscribers_count":182,"default_branch":"main","last_synced_at":"2025-04-12T21:07:51.609Z","etag":null,"topics":["markdownlint","markdownlint-rule"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/github.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-28T07:27:27.000Z","updated_at":"2025-04-07T18:03:21.000Z","dependencies_parsed_at":"2024-01-09T03:54:36.764Z","dependency_job_id":"e96aad25-598f-450a-a4e2-b7e97944b165","html_url":"https://github.com/github/markdownlint-github","commit_stats":{"total_commits":107,"total_committers":11,"mean_commits":9.727272727272727,"dds":0.4579439252336449,"last_synced_commit":"7d5ebcb09a76c417e378136bae0243afd58eec45"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fmarkdownlint-github","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fmarkdownlint-github/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fmarkdownlint-github/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fmarkdownlint-github/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/markdownlint-github/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654090,"owners_count":21140236,"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":["markdownlint","markdownlint-rule"],"created_at":"2024-09-24T21:08:08.059Z","updated_at":"2025-04-13T02:10:39.138Z","avatar_url":"https://github.com/github.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdownlint-github\n\nThis repository provides GitHub's recommended [`markdownlint`](https://github.com/DavidAnson/markdownlint) configurations, and additional rules for use on GitHub open source and internal projects.\n\n## Opinions\n\nIn addition to defaults defined by `markdownlint`, we use this repository to enforce rules not defined by default, including our own custom rules.\n\nSee opinions codified in [index.js](./index.js).\n\n## Rules\n\nThe following are custom rules defined in this plugin.\n\n* [**GH001** _no-default-alt-text_](./docs/rules/GH001-no-default-alt-text.md)\n* [**GH002** _no-generic-link-text_](./docs/rules/GH002-no-generic-link-text.md)\n* [**GH003** _no-empty-alt-text_](./docs/rules/GH003-no-empty-alt-text.md)\n\nSee [`markdownlint` rules](https://github.com/DavidAnson/markdownlint#rules--aliases) for documentation on rules pulled in from `markdownlint`.\n\n## Usage\n\n**Important**: We support the use of `markdownlint` through [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) instead of `markdownlint-cli` for compatibility with the [`vscode-markdownlint`](https://github.com/DavidAnson/vscode-markdownlint) plugin.\n\n1. Create a `.markdownlint-cli2.mjs` file in the root of your repository.\n\n    ```bash\n    touch .markdownlint-cli2.mjs\n    ```\n\n2. Install packages.\n\n    ```bash\n    npm install -D markdownlint-cli2 # if updating existing package, check for updates\n    npm install -D @github/markdownlint-github [--@github:registry=https://registry.npmjs.org]\n    npm install -D markdownlint-cli2-formatter-pretty\n    ```\n\n3. Add/modify your linting script in `package.json`.\n\n    ```json\n    \"scripts\": {\n      \"lint:markdown\": \"markdownlint-cli2 \\\"**/*.{md,mdx}\\\" \\\"!node_modules\\\"\"\n    }\n    ```\n\n4. Edit `.markdownlint-cli2.mjs` file to suit your needs. Start with\n\n    ```js\n    import configOptions, {init} from \"@github/markdownlint-github\"\n    const options = {\n        config: init(),\n        customRules: [\"@github/markdownlint-github\"],\n        outputFormatters: [\n          [ \"markdownlint-cli2-formatter-pretty\", { \"appendLink\": true } ] // ensures the error message includes a link to the rule documentation\n        ]\n    }\n    export default options\n    ```\n\n    Or, you can also pass in configuration options that you wish to override the default. Read more at [Customizing configurations](#customizing-configurations).\n    This looks like:\n\n    ```js\n    import configOptions, {init} from \"@github/markdownlint-github\"\n    const overriddenOptions = init({\n        'fenced-code-language': false, // Custom overrides\n    })\n    const options = {\n        config: overriddenOptions,\n        customRules: [\"@github/markdownlint-github\"],\n        outputFormatters: [\n          [ \"markdownlint-cli2-formatter-pretty\", { \"appendLink\": true } ]\n        ]\n    }\n    export default options\n    ```\n\n5. Install the [`vscode-markdownlint`](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) plugin to ensure `markdownlint` violations are surfaced in the file. This plugin should flag rules based off your `.markdownlint-cli2.mjs` configuration. When you make edits to your configuration, you will need to reload the VSCode window (`Ctrl+Shift+P` -\u003e `Reload Window`) to ensure the extension syncs. If your project runs on Codespaces, consider adding this extension to your `.devcontainer/devcontainer.json` so that this extension is installed to new Codespaces by default.\n\n### Customizing configurations\n\nYou may determine that the defaults set by this plugin are not suitable for your project.\n\nThis plugin will pull in the the defaults defined by `markdownlint`, several of which pertain to stylistic practices. You may choose to disable these rules if you determine it doesn't provide value for your project.\n\nHowever, others of these rules should **NOT** be disabled because they encourage best accessibility practices. Disabling these rules will negatively impact accessibility. These rules are defined in [accessibility.json](./style/accessibility.json).\n\nTo review configurations supported by `markdownlint`, see [`markdownlint-cli2` configuration](https://github.com/DavidAnson/markdownlint-cli2#configuration).\n\n### Advanced: Adding custom rules in your codebase\n\nYou may write custom rules within your repository. Follow the [custom rules guide in `markdownlint`](https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md) to write your rule.\n\nThe rule will need to be enabled in the configuration. For instance, if you introduce `some-rule.js` with the name \"some-rule\", you must set the path of the custom rule in the `.markdownlint-cli2.mjs` file:\n\n```js\nimport configOptions, {init} from \"@github/markdownlint-github\"\nconst options = init({\n    \"some-rule\": true,\n    customRules: [\"@github/markdownlint-github\", \"some-rule.js\"],\n})\nexport default options\n```\n\nSee [`markdownlint-cli2` configuration](https://github.com/DavidAnson/markdownlint-cli2#configuration).\n\nConsider upstreaming any rules you find useful as proposals to this repository.\n\n## License\n\nThis project is licensed under the terms of the MIT open source license. Please\nrefer to [the MIT license](./LICENSE.txt) for the full terms.\n\n## Maintainers\n\nSee [CODEOWNERS](./CODEOWNERS).\n\n## Contributing\n\nPlease read [Contributing Guide](./CONTRIBUTING.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fmarkdownlint-github","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fmarkdownlint-github","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fmarkdownlint-github/lists"}