10 Commits

28 changed files with 4128 additions and 4872 deletions

View File

@ -1 +0,0 @@
{ "extends": ["@commitlint/config-conventional"] }

View File

@ -1,11 +0,0 @@
{
"extends": ["conventions", "prettier"],
"plugins": ["prettier", "import", "unicorn"],
"parserOptions": {
"project": "./tsconfig.json"
},
"rules": {
"prettier/prettier": "error",
"import/extensions": ["error", "always"]
}
}

View File

@ -4,16 +4,16 @@ on:
push:
branches: [develop]
pull_request:
branches: [master, develop]
branches: [main, develop]
jobs:
lint:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v4.1.1"
- uses: "actions/checkout@v4.2.2"
- name: "Setup Node.js"
uses: "actions/setup-node@v4.0.2"
uses: "actions/setup-node@v4.1.0"
with:
node-version: "lts/*"
cache: "npm"
@ -21,9 +21,15 @@ jobs:
- name: "Install dependencies"
run: "npm clean-install"
- run: 'npm run lint:commit -- --to "${{ github.sha }}"'
- run: "npm run lint:editorconfig"
- run: "npm run lint:markdown"
- run: "npm run lint:eslint"
- run: "npm run lint:prettier"
- run: "npm run lint:javascript"
- run: "node --run lint:editorconfig"
- run: "node --run lint:markdown"
- run: "node --run lint:eslint"
- run: "node --run lint:prettier"
- run: "node --run lint:typescript"
commitlint:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v4.2.2"
- uses: "wagoid/commitlint-github-action@v6.2.0"

View File

@ -2,7 +2,7 @@ name: "Release"
on:
push:
branches: [master]
branches: [main]
jobs:
release:
@ -13,13 +13,13 @@ jobs:
pull-requests: "write"
id-token: "write"
steps:
- uses: "actions/checkout@v4.1.1"
- uses: "actions/checkout@v4.2.2"
with:
fetch-depth: 0
persist-credentials: false
- name: "Setup Node.js"
uses: "actions/setup-node@v4.0.2"
uses: "actions/setup-node@v4.1.0"
with:
node-version: "lts/*"
cache: "npm"
@ -31,7 +31,7 @@ jobs:
run: "npm audit signatures"
- name: "Release"
run: "npm run release"
run: "node --run release"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

View File

@ -4,16 +4,23 @@ on:
push:
branches: [develop]
pull_request:
branches: [master, develop]
branches: [main, develop]
jobs:
test:
runs-on: "ubuntu-latest"
strategy:
fail-fast: false
matrix:
runs-on:
- "ubuntu-latest"
- "windows-latest"
- "macos-latest"
runs-on: "${{ matrix.runs-on }}"
steps:
- uses: "actions/checkout@v4.1.1"
- uses: "actions/checkout@v4.2.2"
- name: "Setup Node.js"
uses: "actions/setup-node@v4.0.2"
uses: "actions/setup-node@v4.1.0"
with:
node-version: "lts/*"
cache: "npm"
@ -22,4 +29,4 @@ jobs:
run: "npm clean-install"
- name: "Test"
run: "npm run test"
run: "node --run test"

4
.gitignore vendored
View File

@ -20,10 +20,6 @@ npm-debug.log*
# IDE - VSCode
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
# misc
.DS_Store

View File

@ -1,3 +0,0 @@
#!/usr/bin/env sh
npm run lint:commit -- --edit

View File

@ -1,5 +0,0 @@
#!/usr/bin/env sh
npm run lint:staged
npm run lint:javascript
npm run test

View File

@ -1,7 +0,0 @@
{
"**/*": ["editorconfig-checker", "prettier --write --ignore-unknown"],
"**/*.md": ["markdownlint-cli2 --fix --no-globs"],
"**/*.{js,jsx,ts,tsx}": [
"eslint --fix --max-warnings 0 --report-unused-disable-directives"
]
}

View File

@ -1,11 +0,0 @@
{
"config": {
"extends": "markdownlint/style/prettier",
"default": true,
"relative-links": true,
"no-inline-html": false,
},
"globs": ["**/*.md"],
"ignores": ["**/node_modules", "**/test/fixtures/**"],
"customRules": ["./src/index.js"],
}

17
.markdownlint-cli2.mjs Normal file
View File

@ -0,0 +1,17 @@
import relativeLinksRule from "./src/index.js"
const config = {
config: {
extends: "markdownlint/style/prettier",
default: true,
"relative-links": {
root_path: ".",
},
"no-inline-html": false,
},
globs: ["**/*.md"],
ignores: ["**/node_modules", "**/test/fixtures/**"],
customRules: [relativeLinksRule],
}
export default config

4
.npmrc
View File

@ -1,2 +1,2 @@
save-exact=true
provenance=true
save-exact = true
provenance = true

View File

@ -1,18 +1,8 @@
{
"branches": ["master"],
"branches": ["main", { "name": "beta", "prerelease": true }],
"plugins": [
[
"@semantic-release/commit-analyzer",
{
"preset": "conventionalcommits"
}
],
[
"@semantic-release/release-notes-generator",
{
"preset": "conventionalcommits"
}
],
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/npm",
"@semantic-release/github"
]

View File

@ -1,8 +0,0 @@
{
"recommendations": [
"editorconfig.editorconfig",
"esbenp.prettier-vscode",
"dbaeumer.vscode-eslint",
"davidanson.vscode-markdownlint"
]
}

View File

@ -1,8 +0,0 @@
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"prettier.configPath": ".prettierrc.json",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll": "explicit"
}
}

View File

@ -4,7 +4,7 @@ Thanks a lot for your interest in contributing to **markdownlint-rule-relative-l
## Code of Conduct
**markdownlint-rule-relative-links** adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](./CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
**markdownlint-rule-relative-links** adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
## Open Development

View File

@ -51,12 +51,13 @@ awesome.md:3 relative-links Relative links should be valid ["./invalid.txt" shou
- Support images (e.g: `![Image](./image.png)`).
- Support links fragments similar to the [built-in `markdownlint` rule - MD051](https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md) (e.g: `[Link](./awesome.md#heading)`).
- Ignore external links and absolute paths as it only checks relative links (e.g: `https://example.com/` or `/absolute/path.png`).
- If necessary, absolute paths can be validated too, with [`root_path` configuration option](#absolute-paths).
### Limitations
- Only images and links defined using markdown syntax are validated, html syntax is ignored (e.g: `<a href="./link.txt" />` or `<img src="./image.png" />`).
Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
### Related links
@ -66,7 +67,7 @@ Contributions are welcome to improve the rule, and to alleviate these limitation
## Prerequisites
[Node.js](https://nodejs.org/) >= 16.0.0
[Node.js](https://nodejs.org/) >= 22.0.0
## Installation
@ -80,18 +81,22 @@ There are various ways [markdownlint](https://github.com/DavidAnson/markdownlint
We recommend configuring [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) over [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) for compatibility with the [vscode-markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension.
`.markdownlint-cli2.jsonc`
`.markdownlint-cli2.mjs`
```json
{
"config": {
"default": true,
"relative-links": true
```js
import relativeLinksRule from "markdownlint-rule-relative-links"
const config = {
config: {
default: true,
"relative-links": true,
},
"globs": ["**/*.md"],
"ignores": ["**/node_modules"],
"customRules": ["markdownlint-rule-relative-links"]
globs: ["**/*.md"],
ignores: ["**/node_modules"],
customRules: [relativeLinksRule],
}
export default config
```
`package.json`
@ -104,18 +109,37 @@ We recommend configuring [markdownlint-cli2](https://github.com/DavidAnson/markd
}
```
### Absolute paths
GitHub (and, likely, other similar platforms) resolves absolute paths in Markdown links relative to the repository root.
To validate such links, add `root_path` option to the configuration:
```js
config: {
default: true,
"relative-links": {
root_path: ".",
},
},
```
After this change, all absolute paths will be converted to relative paths, and will be resolved relative to the specified directory.
For example, if you run markdownlint from a subdirectory (if `package.json` is located in a subdirectory), you should set `root_path` to `".."`.
## Usage
```sh
npm run lint:markdown
node --run lint:markdown
```
## 💡 Contributing
Anyone can help to improve the project, submit a Feature Request, a bug report or even correct a simple spelling mistake.
The steps to contribute can be found in the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
The steps to contribute can be found in the [CONTRIBUTING.md](/CONTRIBUTING.md) file.
## 📄 License
[MIT](./LICENSE)
[MIT](/LICENSE)

13
eslint.config.js Normal file
View File

@ -0,0 +1,13 @@
import typescriptESLint from "typescript-eslint"
import configConventions from "eslint-config-conventions"
export default typescriptESLint.config(...configConventions, {
files: ["**/*.ts", "**/*.tsx"],
languageOptions: {
parser: typescriptESLint.parser,
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname,
},
},
})

8576
package-lock.json generated

File diff suppressed because it is too large Load Diff

View File

@ -18,6 +18,8 @@
"markdownlint-rule"
],
"main": "src/index.js",
"types": "src/index.d.ts",
"type": "module",
"files": [
"src"
],
@ -26,46 +28,35 @@
"provenance": true
},
"engines": {
"node": ">=16.0.0",
"npm": ">=9.0.0"
"node": ">=22.0.0"
},
"scripts": {
"lint:commit": "commitlint",
"lint:editorconfig": "editorconfig-checker",
"lint:markdown": "markdownlint-cli2",
"lint:eslint": "eslint . --max-warnings 0 --report-unused-disable-directives --ignore-path .gitignore",
"lint:prettier": "prettier . --check --ignore-path .gitignore",
"lint:javascript": "tsc --project jsconfig.json --noEmit",
"lint:staged": "lint-staged",
"lint:eslint": "eslint . --max-warnings 0",
"lint:prettier": "prettier . --check",
"lint:typescript": "tsc --noEmit",
"test": "node --test",
"release": "semantic-release",
"postinstall": "husky",
"prepublishOnly": "pinst --disable",
"postpublish": "pinst --enable"
"release": "semantic-release"
},
"dependencies": {
"markdown-it": "14.1.0"
},
"devDependencies": {
"@commitlint/cli": "19.2.2",
"@commitlint/config-conventional": "19.2.2",
"@types/markdown-it": "14.1.1",
"@types/node": "20.12.12",
"editorconfig-checker": "5.1.5",
"eslint": "8.57.0",
"eslint-config-conventions": "14.2.0",
"eslint-config-prettier": "9.1.0",
"eslint-plugin-import": "2.29.1",
"eslint-plugin-prettier": "5.1.3",
"eslint-plugin-promise": "6.2.0",
"eslint-plugin-unicorn": "53.0.0",
"husky": "9.0.11",
"lint-staged": "15.2.5",
"markdownlint": "0.34.0",
"markdownlint-cli2": "0.13.0",
"pinst": "3.0.0",
"prettier": "3.2.5",
"semantic-release": "23.1.1",
"typescript": "5.4.5"
"@types/markdown-it": "14.1.2",
"@types/node": "22.15.17",
"editorconfig-checker": "6.0.1",
"eslint": "9.26.0",
"eslint-config-conventions": "19.2.0",
"eslint-plugin-promise": "7.2.1",
"eslint-plugin-unicorn": "59.0.1",
"eslint-plugin-import-x": "4.11.1",
"globals": "16.1.0",
"markdownlint": "0.38.0",
"markdownlint-cli2": "0.18.0",
"prettier": "3.5.3",
"semantic-release": "24.2.3",
"typescript-eslint": "8.32.0",
"typescript": "5.8.3"
}
}

8
src/index.d.ts vendored Normal file
View File

@ -0,0 +1,8 @@
import type MarkdownIt from "markdown-it"
import type { Rule } from "markdownlint"
declare const relativeLinksRule: Rule
export default relativeLinksRule
declare const markdownIt: MarkdownIt
export { markdownIt }

View File

@ -1,10 +1,8 @@
"use strict"
import { pathToFileURL } from "node:url"
import fs from "node:fs"
const { pathToFileURL } = require("node:url")
const fs = require("node:fs")
const { filterTokens } = require("./markdownlint-rule-helpers/helpers.js")
const {
import { filterTokens } from "./markdownlint-rule-helpers/helpers.js"
import {
convertHeadingToHTMLFragment,
getMarkdownHeadings,
getMarkdownIdOrAnchorNameFragments,
@ -12,14 +10,16 @@ const {
getNumberOfLines,
getLineNumberStringFromFragment,
lineFragmentRe,
} = require("./utils.js")
} from "./utils.js"
export { markdownIt } from "./utils.js"
/** @typedef {import('markdownlint').Rule} MarkdownLintRule */
/**
* @type {MarkdownLintRule}
*/
const customRule = {
const relativeLinksRule = {
names: ["relative-links"],
description: "Relative links should be valid",
tags: ["links"],
@ -51,17 +51,25 @@ const customRule = {
}
}
if (hrefSrc == null) {
if (hrefSrc == null || hrefSrc.startsWith("#")) {
continue
}
const url = new URL(hrefSrc, pathToFileURL(params.name))
const isRelative =
url.protocol === "file:" &&
!hrefSrc.startsWith("/") &&
!hrefSrc.startsWith("#")
let url
if (!isRelative) {
if (hrefSrc.startsWith("/")) {
const rootPath = params.config["root_path"]
if (!rootPath) {
continue
}
url = new URL(`.${hrefSrc}`, pathToFileURL(`${rootPath}/`))
} else {
url = new URL(hrefSrc, pathToFileURL(params.name))
}
if (url.protocol !== "file:") {
continue
}
@ -172,4 +180,4 @@ const customRule = {
},
}
module.exports = customRule
export default relativeLinksRule

View File

@ -14,7 +14,7 @@
* @param {(token: MarkdownItToken) => void} handler Callback function.
* @returns {void}
*/
const filterTokens = (params, type, handler) => {
export const filterTokens = (params, type, handler) => {
for (const token of params.parsers.markdownit.tokens) {
if (token.type === type) {
handler(token)
@ -28,11 +28,6 @@ const filterTokens = (params, type, handler) => {
* @param {string} name HTML attribute name.
* @returns {RegExp} Regular Expression for matching.
*/
const getHtmlAttributeRe = (name) => {
export const getHtmlAttributeRe = (name) => {
return new RegExp(`\\s${name}\\s*=\\s*['"]?([^'"\\s>]*)`, "iu")
}
module.exports = {
filterTokens,
getHtmlAttributeRe,
}

View File

@ -1,10 +1,10 @@
const MarkdownIt = require("markdown-it")
import MarkdownIt from "markdown-it"
const { getHtmlAttributeRe } = require("./markdownlint-rule-helpers/helpers.js")
import { getHtmlAttributeRe } from "./markdownlint-rule-helpers/helpers.js"
const markdownIt = new MarkdownIt({ html: true })
export const markdownIt = new MarkdownIt({ html: true })
const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
export const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
/**
* Converts a Markdown heading into an HTML fragment according to the rules
@ -14,7 +14,7 @@ const lineFragmentRe = /^#(?:L\d+(?:C\d+)?-L\d+(?:C\d+)?|L\d+)$/
* @param {string} inlineText Inline token for heading.
* @returns {string} Fragment string for heading.
*/
const convertHeadingToHTMLFragment = (inlineText) => {
export const convertHeadingToHTMLFragment = (inlineText) => {
return (
"#" +
encodeURIComponent(
@ -40,7 +40,7 @@ const ignoredTokens = new Set(["heading_open", "heading_close"])
* @param {string} content
* @returns {string[]}
*/
const getMarkdownHeadings = (content) => {
export const getMarkdownHeadings = (content) => {
const tokens = markdownIt.parse(content, {})
/** @type {string[]} */
@ -88,7 +88,7 @@ const idHTMLAttributeRegex = getHtmlAttributeRe("id")
* @param {string} content
* @returns {string[]}
*/
const getMarkdownIdOrAnchorNameFragments = (content) => {
export const getMarkdownIdOrAnchorNameFragments = (content) => {
const tokens = markdownIt.parse(content, {})
/** @type {string[]} */
@ -128,7 +128,7 @@ const getMarkdownIdOrAnchorNameFragments = (content) => {
* @example isValidIntegerString("1abc") // false
* @example isValidIntegerString("1.0") // false
*/
const isValidIntegerString = (value) => {
export const isValidIntegerString = (value) => {
const regex = /^\d+$/
return regex.test(value)
}
@ -138,7 +138,7 @@ const isValidIntegerString = (value) => {
* @param {string} content
* @returns {number}
*/
const getNumberOfLines = (content) => {
export const getNumberOfLines = (content) => {
return content.split("\n").length
}
@ -148,16 +148,6 @@ const getNumberOfLines = (content) => {
* @returns {string}
* @example getLineNumberStringFromFragment("#L50") // 50
*/
const getLineNumberStringFromFragment = (fragment) => {
export const getLineNumberStringFromFragment = (fragment) => {
return fragment.slice(2)
}
module.exports = {
lineFragmentRe,
convertHeadingToHTMLFragment,
getMarkdownHeadings,
getMarkdownIdOrAnchorNameFragments,
isValidIntegerString,
getNumberOfLines,
getLineNumberStringFromFragment,
}

View File

@ -0,0 +1,3 @@
# Valid
![Absolute Path](/test/fixtures/image.png)

View File

@ -1,23 +1,31 @@
const { test } = require("node:test")
const assert = require("node:assert/strict")
import { test } from "node:test"
import assert from "node:assert/strict"
const { markdownlint } = require("markdownlint").promises
import * as markdownlint from "markdownlint/promise"
const relativeLinksRule = require("../src/index.js")
import relativeLinksRule, { markdownIt } from "../src/index.js"
const defaultConfig = {
"relative-links": true,
}
/**
*
* @param {string} fixtureFile
* @param {Object} config
* @returns
*/
const validateMarkdownLint = async (fixtureFile) => {
const lintResults = await markdownlint({
const validateMarkdownLint = async (fixtureFile, config = defaultConfig) => {
const lintResults = await markdownlint.lint({
files: [fixtureFile],
config: {
default: false,
"relative-links": true,
...config,
},
customRules: [relativeLinksRule],
markdownItFactory: () => {
return markdownIt
},
})
return lintResults[fixtureFile]
}
@ -143,11 +151,27 @@ test("ensure the rule validates correctly", async (t) => {
fixturePath: "test/fixtures/invalid/non-existing-image.md",
errors: ['"./image.png" should exist in the file system'],
},
{
name: "should be invalid with incorrect absolute paths",
fixturePath: "test/fixtures/config-dependent/absolute-paths.md",
errors: ['"/test/fixtures/image.png" should exist in the file system'],
config: {
"relative-links": {
root_path: "test",
},
},
},
]
for (const { name, fixturePath, errors } of testCases) {
for (const {
name,
fixturePath,
errors,
config = defaultConfig,
} of testCases) {
await t.test(name, async () => {
const lintResults = (await validateMarkdownLint(fixturePath)) ?? []
const lintResults =
(await validateMarkdownLint(fixturePath, config)) ?? []
const errorsDetails = lintResults.map((result) => {
assert.deepEqual(result.ruleNames, relativeLinksRule.names)
assert.deepEqual(
@ -216,7 +240,7 @@ test("ensure the rule validates correctly", async (t) => {
fixturePath: "test/fixtures/valid/existing-image.md",
},
{
name: "should ignore absolute paths",
name: "should ignore absolute paths if root_path is not set",
fixturePath: "test/fixtures/valid/ignore-absolute-paths.md",
},
{
@ -228,11 +252,21 @@ test("ensure the rule validates correctly", async (t) => {
fixturePath:
"test/fixtures/valid/ignore-fragment-checking-in-own-file.md",
},
{
name: "should be valid with correct absolute paths if root_path is set",
fixturePath: "test/fixtures/config-dependent/absolute-paths.md",
config: {
"relative-links": {
root_path: ".",
},
},
},
]
for (const { name, fixturePath } of testCases) {
for (const { name, fixturePath, config = defaultConfig } of testCases) {
await t.test(name, async () => {
const lintResults = (await validateMarkdownLint(fixturePath)) ?? []
const lintResults =
(await validateMarkdownLint(fixturePath, config)) ?? []
const errorsDetails = lintResults.map((result) => {
return result.errorDetail
})

View File

@ -1,14 +1,14 @@
const { test } = require("node:test")
const assert = require("node:assert/strict")
import { test } from "node:test"
import assert from "node:assert/strict"
const {
import {
convertHeadingToHTMLFragment,
getMarkdownHeadings,
getMarkdownIdOrAnchorNameFragments,
isValidIntegerString,
getNumberOfLines,
getLineNumberStringFromFragment,
} = require("../src/utils.js")
} from "../src/utils.js"
test("utils", async (t) => {
await t.test("convertHeadingToHTMLFragment", async () => {

View File

@ -2,8 +2,8 @@
"compilerOptions": {
"lib": ["ESNext"],
"target": "ESNext",
"module": "CommonJS",
"moduleResolution": "Node",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"checkJs": true,
"allowJs": true,
"noEmit": true,