Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: github/markdownlint-github
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v0.3.1
Choose a base ref
...
head repository: github/markdownlint-github
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: main
Choose a head ref
Loading
18 changes: 0 additions & 18 deletions .eslintrc.js

This file was deleted.

24 changes: 24 additions & 0 deletions .eslintrc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"root": true,
"parserOptions": {
"ecmaVersion": 2020
},
"env": {
"es6": true,
"node": true,
"jest": true
},
"plugins": ["github"],
"extends": ["plugin:github/recommended"],
"rules": {
"filenames/match-regex": "off",
"i18n-text/no-en": "off",
"import/extensions": ["error", { "js": "ignorePackages"}],
"import/no-unresolved": [
"error",
{
"ignore": ["^markdownlint/.+"]
}
]
}
}
26 changes: 26 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
version: 2
updates:
- package-ecosystem: npm
directory: "/"
schedule:
interval: weekly
groups:
all-dependencies:
patterns:
- "*"
update-types:
- "minor"
- "patch"
open-pull-requests-limit: 99
- package-ecosystem: github-actions
directory: '/'
schedule:
interval: weekly
open-pull-requests-limit: 99
groups:
all-dependencies:
patterns:
- "*"
update-types:
- "minor"
- "patch"
26 changes: 26 additions & 0 deletions .github/workflows/accessibility-alt-text-bot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Accessibility-alt-text-bot
on:
issues:
types: [opened, edited]
pull_request:
types: [opened, edited]
issue_comment:
types: [created, edited, deleted]
discussion:
types: [created, edited]
discussion_comment:
types: [created, edited, deleted]

permissions:
issues: write
pull-requests: write
discussions: write

jobs:
accessibility_alt_text_bot:
name: Check alt text is set on issue or pull requests
runs-on: ubuntu-latest
if: ${{ github.event.issue || github.event.pull_request || github.event.discussion }}
steps:
- name: Get action 'github/accessibility-alt-text-bot'
uses: github/accessibility-alt-text-bot@v1.7.1
9 changes: 6 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
name: Run linter and tests
permissions:
contents: read
pull-requests: write
on:
push:
branches:
@@ -8,9 +11,9 @@ jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v3
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 14
node-version: 22
- run: npm install
- run: npm test
13 changes: 8 additions & 5 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
name: Publish

permissions:
contents: read
pull-requests: write
id-token: write
on:
release:
types: [created]
@@ -8,10 +11,10 @@ jobs:
publish-npm:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 16
node-version: 22
registry-url: https://registry.npmjs.org/
cache: npm
- run: npm ci
@@ -21,6 +24,6 @@ jobs:
npm version ${TAG_NAME} --git-tag-version=false
env:
TAG_NAME: ${{github.event.release.tag_name}}
- run: npm whoami; npm --ignore-scripts publish
- run: npm whoami; npm --ignore-scripts publish --provenance
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
12 changes: 0 additions & 12 deletions .markdownlint-cli2.cjs

This file was deleted.

15 changes: 15 additions & 0 deletions .markdownlint-cli2.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import { init } from "./index.js";

const configOptions = await init({
default: false,
"heading-increment": true,
"no-alt-text": true,
"single-h1": true,
"no-emphasis-as-heading": true,
"first-line-heading": true,
});
const options = {
config: configOptions,
customRules: ["./index.js"],
};
export default options;
2 changes: 1 addition & 1 deletion .nvmrc
Original file line number Diff line number Diff line change
@@ -1 +1 @@
14
18
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Changelog

## 0.2.0

* BREAKING change: Convert to ECMAScript modules (ESM)

## 0.1.0

* Initial release
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -6,8 +6,8 @@ Thank you for your interest in contributing.

Depending on your needs, you may have one of two development paths:

- via integrating with an existing usage (ideal for modifying the interface of our rules)
- via unit testing (ideal for adding a new rule)
* via integrating with an existing usage (ideal for modifying the interface of our rules)
* via unit testing (ideal for adding a new rule)

For that reason we've included two paths to develop. Feel free to use either, or both.

@@ -32,8 +32,8 @@ It may be useful to work on this in tandem with a codebase that uses the rules.
If you go to the `node_modules` directory in your codebase and try to navigate into the package, you'll notice that whatever changes you make in your local development directory will be reflected in the codebase.
3. Reset symlinks at any time by reversing the steps via `npm unlink`.
- in your codebase: `npm unlink @github/markdownlint-github`
- in this directory: `npm unlink`
* in your codebase: `npm unlink @github/markdownlint-github`
* in this directory: `npm unlink`
### Unit and Interface Testing
55 changes: 32 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -12,65 +12,71 @@ See opinions codified in [index.js](./index.js).

The following are custom rules defined in this plugin.

- [**GH001** _no-default-alt-text_](./docs/rules/GH001-no-default-alt-text.md)
- [**GH002** _no-generic-link-text_](./docs/rules/GH002-no-generic-link-text.md)
* [**GH001** _no-default-alt-text_](./docs/rules/GH001-no-default-alt-text.md)
* [**GH002** _no-generic-link-text_](./docs/rules/GH002-no-generic-link-text.md)
* [**GH003** _no-empty-alt-text_](./docs/rules/GH003-no-empty-alt-text.md)

See [`markdownlint` rules](https://github.com/DavidAnson/markdownlint#rules--aliases) for documentation on rules pulled in from `markdownlint`.

## Usage

**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.

1. Create a `.markdownlint-cli2.cjs` file in the root of your repository.
1. Create a `.markdownlint-cli2.mjs` file in the root of your repository.

```bash
touch .markdownlint-cli2.cjs
touch .markdownlint-cli2.mjs
```

2. Install packages.

- ```bash
npm install -D markdownlint-cli2 # if updating existing package, check for updates
npm install -D @github/markdownlint-github [--@github:registry=https://registry.npmjs.org]
npm install -D markdownlint-cli2-formatter-pretty
```
```bash
npm install -D markdownlint-cli2 # if updating existing package, check for updates
npm install -D @github/markdownlint-github [--@github:registry=https://registry.npmjs.org]
npm install -D markdownlint-cli2-formatter-pretty
```

3. Add/modify your linting script in `package.json`.

```bash
markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\"
```json
"scripts": {
"lint:markdown": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\""
}
```

4. Edit `.markdownlint-cli2.cjs` file to suit your needs. Start with
4. Edit `.markdownlint-cli2.mjs` file to suit your needs. Start with

```js
const options = require('@github/markdownlint-github').init()
module.exports = {
config: options,
import configOptions, {init} from "@github/markdownlint-github"
const options = {
config: init(),
customRules: ["@github/markdownlint-github"],
outputFormatters: [
[ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ] // ensures the error message includes a link to the rule documentation
]
}
export default options
```
Or, you can also pass in configuration options that you wish to override the default. Read more at [Customizing configurations](#customizing-configurations).
Or, you can also pass in configuration options that you wish to override the default. Read more at [Customizing configurations](#customizing-configurations).
This looks like:
```js
const options = require('@github/markdownlint-github').init({
import configOptions, {init} from "@github/markdownlint-github"
const overriddenOptions = init({
'fenced-code-language': false, // Custom overrides
})
module.exports = {
config: options,
const options = {
config: overriddenOptions,
customRules: ["@github/markdownlint-github"],
outputFormatters: [
[ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ]
]
}
export default options
```
5. 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.cjs` configuration. When you make edits to your configuration, you will need to reload the VSCode window (`Ctrl+Shift+P` -> `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.
5. 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` -> `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.
### Customizing configurations
@@ -86,13 +92,15 @@ To review configurations supported by `markdownlint`, see [`markdownlint-cli2` c
You 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.
The 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.cjs` file:
The 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:
```js
module.exports = require('@github/markdownlint-github').init({
import configOptions, {init} from "@github/markdownlint-github"
const options = init({
"some-rule": true,
customRules: ["@github/markdownlint-github", "some-rule.js"],
})
export default options
```
See [`markdownlint-cli2` configuration](https://github.com/DavidAnson/markdownlint-cli2#configuration).
@@ -101,7 +109,8 @@ Consider upstreaming any rules you find useful as proposals to this repository.
## License
This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE.txt) for the full terms.
This project is licensed under the terms of the MIT open source license. Please
refer to [the MIT license](./LICENSE.txt) for the full terms.
## Maintainers
27 changes: 27 additions & 0 deletions docs/rules/GH003-no-empty-alt-text.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# GH003 No Empty Alt Text

## Rule details

⚠️ This rule is _off_ by default and is only applicable for GitHub rendered markdown.

Currently, all images on github.com are automatically wrapped in an anchor tag.

As a result, images that are intentionally marked as decorative (via `alt=""`) end up rendering as a link without an accessible name. This is confusing and inaccessible for assistive technology users.

This rule can be enabled to enforce that the alt attribute is always set to descriptive text.

This rule should be removed once this behavior is updated on GitHub's UI.

## Examples

### Incorrect 👎

```html
<img src="cat.png" alt="">
```

### Correct 👍

```html
<img src="mona.png" alt="Mona Lisa, the Octocat">
```
Loading