markdownlint 0.37.3 → 0.38.0

package/doc/md041.md

@@ -6,44 +6,59 @@ Aliases: `first-line-h1`, `first-line-heading`
 
 Parameters:
 
+- `allow_preamble`: Allow content before first heading (`boolean`, default
+  `false`)
 - `front_matter_title`: RegExp for matching title in front matter (`string`,
   default `^\s*title\s*[:=]`)
 - `level`: Heading level (`integer`, default `1`)
 
 This rule is intended to ensure documents have a title and is triggered when
-the first line in the file isn't a top-level (h1) heading:
+the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
 
 ```markdown
-This is a file without a heading
+This is a document without a heading
 ```
 
-To fix this, add a top-level heading to the beginning of the file:
+To fix this, add a top-level heading to the beginning of the document:
 
 ```markdown
-# File with heading
+# Document Heading
 
-This is a file with a top-level heading
+This is a document with a top-level heading
 ```
 
 Because it is common for projects on GitHub to use an image for the heading of
-`README.md` and that is not well-supported by Markdown, HTML headings are also
-permitted by this rule. For example:
+`README.md` and that pattern is not well-supported by Markdown, HTML headings
+are also permitted by this rule. For example:
 
 ```markdown
 <h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
 
-This is a file with a top-level HTML heading
+This is a document with a top-level HTML heading
 ```
 
-Note: The `level` parameter can be used to change the top-level (ex: to h2) in
-cases where an h1 is added externally.
+In some cases, a document's title heading may be preceded by text like a table
+of contents. This is not ideal for accessibility, but can be allowed by setting
+the `allow_preamble` parameter to `true`.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
-contains a `title` property (commonly used with blog posts), this rule will not
-report a violation. To use a different property name in the front matter,
-specify the text of a regular expression via the `front_matter_title` parameter.
-To disable the use of front matter by this rule, specify `""` for
-`front_matter_title`.
+```markdown
+This is a document with preamble text
+
+# Document Heading
+```
+
+If [YAML][YAML] front matter is present and contains a `title` property
+(commonly used with blog posts), this rule will not report a violation. To use a
+different property name in the front matter, specify the text of a [regular
+expression][RegExp] via the `front_matter_title` parameter. To disable the use
+of front matter by this rule, specify `""` for `front_matter_title`.
+
+The `level` parameter can be used to change the top-level heading (ex: to `h2`)
+in cases where an `h1` is added externally.
 
 Rationale: The top-level heading often acts as the title of a document. More
 information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
+
+[HTML]: https://en.wikipedia.org/wiki/HTML
+[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
+[YAML]: https://en.wikipedia.org/wiki/YAML

package/doc/md043.md

@@ -16,7 +16,7 @@ structure for a set of files.
 To require exactly the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail
 ```
@@ -25,7 +25,7 @@ Set the `headings` parameter to:
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "### Detail"
 ]
@@ -34,7 +34,7 @@ Set the `headings` parameter to:
 To allow optional headings as with the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail (optional)
 ## Foot
@@ -47,7 +47,7 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "*",
     "## Foot",
@@ -55,6 +55,24 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 ]
 ```
 
+To allow a single required heading to vary as with a project name:
+
+```markdown
+# Project Name
+## Description
+## Examples
+```
+
+Use the special value `"?"` meaning "exactly one unspecified heading":
+
+```json
+[
+    "?",
+    "## Description",
+    "## Examples"
+]
+```
+
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).
 

package/doc/md045.md

@@ -4,7 +4,7 @@ Tags: `accessibility`, `images`
 
 Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -29,12 +29,20 @@ Or with HTML as:
 <img src="image.jpg" alt="Alternate text" />
 ```
 
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 content of an image for people who may not be able to see it.
 
+[aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
 [wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

package/doc/md051.md

@@ -7,6 +7,8 @@ Aliases: `link-fragments`
 Parameters:
 
 - `ignore_case`: Ignore case of fragments (`boolean`, default `false`)
+- `ignored_pattern`: Pattern for ignoring additional fragments (`string`,
+  default ``)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -64,6 +66,13 @@ attribute can be used to define a fragment:
 An `a` tag can be useful in scenarios where a heading is not appropriate or for
 control over the text of the fragment identifier.
 
+[HTML links to `#top` scroll to the top of a document][html-top-fragment]. This
+rule allows that syntax (using lower-case for consistency):
+
+```markdown
+[Link](#top)
+```
+
 This rule also recognizes the custom fragment syntax used by GitHub to highlight
 [specific content in a document][github-linking-to-content].
 
@@ -79,6 +88,12 @@ And this link to content starting within line 19 running into line 21:
 [Link](#L19C5-L21C11)
 ```
 
+Some Markdown generators dynamically create and insert headings when building
+documents, for example by combining a fixed prefix like `figure-` and an
+incrementing numeric counter. To ignore such generated fragments, set the
+`ignored_pattern` [regular expression][RegEx] parameter to a pattern that
+matches (e.g., `^figure-`).
+
 Rationale: [GitHub section links][github-section-links] are created
 automatically for every heading when Markdown content is displayed on GitHub.
 This makes it easy to link directly to different sections within a document.
@@ -93,3 +108,5 @@ append an incrementing integer as needed for uniqueness.
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
 [github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
 [github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown
+[html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
+[RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions

package/doc/md052.md

@@ -6,6 +6,7 @@ Aliases: `reference-links-images`
 
 Parameters:
 
+- `ignored_labels`: Ignored link labels (`string[]`, default `["x"]`)
 - `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
 
 Links and images in Markdown can provide the link destination or image source
@@ -38,3 +39,14 @@ so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
 the `include_shortcut` parameter to `true`. Note that doing so produces warnings
 for *all* text in the document that *could* be a shortcut. If bracketed text is
 intentional, brackets can be escaped with the `\` character: `\[example\]`.
+
+If there are link labels that are deliberately unreferenced, they can be ignored
+by setting the `ignored_labels` parameter to the list of strings to ignore. The
+default value of this parameter ignores the checkbox syntax used by
+[GitHub Flavored Markdown task list items][gfm-tasklist]:
+
+```markdown
+- [x] Checked task list item
+```
+
+[gfm-tasklist]: https://github.github.com/gfm/#task-list-items-extension-

package/doc/md053.md

@@ -29,9 +29,9 @@ reference has the corresponding label. The "full", "collapsed", and "shortcut"
 formats are all supported.
 
 If there are reference definitions that are deliberately unreferenced, they can
-be ignored by setting the `ignored_definitions` parameter. The default value of
-this parameter ignores the following convention for adding non-HTML comments to
-Markdown:
+be ignored by setting the `ignored_definitions` parameter to the list of strings
+to ignore. The default value of this parameter ignores the following convention
+for adding non-HTML comments to Markdown:
 
 ```markdown
 [//]: # (This behaves like a comment)

package/doc/md059.md

@@ -0,0 +1,30 @@
+# `MD059` - Link text should be descriptive
+
+Tags: `accessibility`, `links`
+
+Aliases: `descriptive-link-text`
+
+Parameters:
+
+- `prohibited_texts`: Prohibited link texts (`string[]`, default `["click
+  here","here","link","more"]`)
+
+This rule is triggered when a link has generic text like `[click here](...)` or
+`[link](...)`.
+
+Link text should be descriptive and communicate the purpose of the link (e.g.,
+`[Download the budget document](...)` or `[CommonMark Specification](...)`).
+This is especially important for screen readers which sometimes present links
+without context.
+
+By default, this rule prohibits a small number of common English words/phrases.
+To customize that list of words/phrases, set the `prohibited_texts` parameter to
+an `Array` of `string`s.
+
+Note: For languages other than English, use the `prohibited_texts` parameter to
+customize the list for that language. It is *not* a goal for this rule to have
+translations for every language.
+
+Note: This rule checks Markdown links; HTML links are ignored.
+
+More information: <https://webaim.org/techniques/hypertext/>

package/helpers/README.md

@@ -22,8 +22,8 @@ be useful to custom rule authors and may avoid duplicating code.
 *None* - The entire body of code is tested to 100% coverage by the core
 `markdownlint` project, so there are no additional tests here.
 
-[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/Rules.md

package/helpers/helpers.cjs

@@ -9,11 +9,8 @@ const { newLineRe, nextLinesRe } = require("./shared.cjs");
 module.exports.newLineRe = newLineRe;
 module.exports.nextLinesRe = nextLinesRe;
 
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").RuleOnError} RuleOnError */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").RuleOnErrorFixInfo} RuleOnErrorFixInfo */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} MicromarkToken */
 // eslint-disable-next-line jsdoc/valid-types
 /** @typedef {import("micromark-extension-gfm-footnote", { with: { "resolution-mode": "import" } })} */
@@ -313,7 +310,7 @@ module.exports.addErrorDetailIf = addErrorDetailIf;
  */
 function addErrorContext(
   onError, lineNumber, context, start, end, range, fixInfo) {
-  context = ellipsify(context, start, end);
+  context = ellipsify(context.replace(newLineRe, "\n"), start, end);
   addError(onError, lineNumber, undefined, context, range, fixInfo);
 }
 module.exports.addErrorContext = addErrorContext;
@@ -378,6 +375,7 @@ module.exports.frontMatterHasTitle =
  */
 function getReferenceLinkImageData(tokens) {
   const normalizeReference = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
+  const getText = (t) => t?.children.filter((c) => c.type !== "blockQuotePrefix").map((c) => c.text).join("");
   const references = new Map();
   const shortcuts = new Map();
   const addReferenceToDictionary = (token, label, isShortcut) => {
@@ -449,7 +447,7 @@ function getReferenceLinkImageData(tokens) {
           const isFullOrCollapsed = (token.children.length === 2) && !token.children.some((t) => t.type === "resource");
           const [ labelText ] = micromark.getDescendantsByType(token, [ "label", "labelText" ]);
           const [ referenceString ] = micromark.getDescendantsByType(token, [ "reference", "referenceString" ]);
-          let label = labelText?.text;
+          let label = getText(labelText);
           // Identify if footnote
           if (!isShortcut && !isFullOrCollapsed) {
             const [ footnoteCallMarker, footnoteCallString ] = token.children.filter(
@@ -462,7 +460,7 @@ function getReferenceLinkImageData(tokens) {
           }
           // Track link (handle shortcuts separately due to ambiguity in "text [text] text")
           if (isShortcut || isFullOrCollapsed) {
-            addReferenceToDictionary(token, referenceString?.text || label, isShortcut);
+            addReferenceToDictionary(token, getText(referenceString) || label, isShortcut);
           }
         }
         break;

package/helpers/micromark-helpers.cjs

@@ -6,8 +6,9 @@ const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.cjs");
 
 // eslint-disable-next-line jsdoc/valid-types
 /** @typedef {import("micromark-util-types", { with: { "resolution-mode": "import" } }).TokenType} TokenType */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} Token */
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} */
 
 /**
  * Determines if a Micromark token is within an htmlFlow type.
@@ -215,8 +216,12 @@ function getHeadingStyle(heading) {
  * @returns {string} Heading text.
  */
 function getHeadingText(heading) {
-  const headingTexts = getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ]);
-  return headingTexts[0]?.text.replace(/[\r\n]+/g, " ") || "";
+  const headingText = getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ])
+    .flatMap((descendant) => descendant.children.filter((child) => child.type !== "htmlText"))
+    .map((data) => data.text)
+    .join("")
+    .replace(/[\r\n]+/g, " ");
+  return headingText || "";
 }
 
 /**
@@ -265,6 +270,26 @@ function getParentOfType(token, types) {
   return current;
 }
 
+const docfxTabSyntaxRe = /^#tab\//;
+
+/**
+ * Returns whether the specified Micromark token looks like a Docfx tab.
+ *
+ * @param {Token | null} heading Micromark token.
+ * @returns {boolean} True iff the token looks like a Docfx tab.
+ */
+function isDocfxTab(heading) {
+  // See https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#tabs
+  if (heading?.type === "atxHeading") {
+    const headingTexts = getDescendantsByType(heading, [ "atxHeadingText" ]);
+    if ((headingTexts.length === 1) && (headingTexts[0].children.length === 1) && (headingTexts[0].children[0].type === "link")) {
+      const resourceDestinationStrings = filterByTypes(headingTexts[0].children[0].children, [ "resourceDestinationString" ]);
+      return (resourceDestinationStrings.length === 1) && docfxTabSyntaxRe.test(resourceDestinationStrings[0].text);
+    }
+  }
+  return false;
+}
+
 /**
  * Set containing token types that do not contain content.
  *
@@ -296,6 +321,7 @@ module.exports = {
   getHtmlTagInfo,
   getParentOfType,
   inHtmlFlow,
+  isDocfxTab,
   isHtmlFlowComment,
   nonContentTokens
 };

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.cjs",
   "exports": {

package/lib/cache.mjs

@@ -3,14 +3,19 @@
 import { getReferenceLinkImageData as helpersGetReferenceLinkImageData } from "../helpers/helpers.cjs";
 import { filterByTypes } from "../helpers/micromark-helpers.cjs";
 
+/** @typedef {import("markdownlint").RuleParams} RuleParams */
+/** @typedef {import("markdownlint").MicromarkToken} MicromarkToken */
+/** @typedef {import("markdownlint").MicromarkTokenType} MicromarkTokenType */
+
 /** @type {Map<string, object>} */
 const map = new Map();
+/** @type {RuleParams | undefined} */
 let params = undefined;
 
 /**
  * Initializes (resets) the cache.
  *
- * @param {import("markdownlint").RuleParams} [p] Rule parameters object.
+ * @param {RuleParams} [p] Rule parameters object.
  * @returns {void}
  */
 export function initialize(p) {
@@ -18,6 +23,15 @@ export function initialize(p) {
   params = p;
 }
 
+/**
+ * Gets the cached Micromark token array (for testing).
+ *
+ * @returns {MicromarkToken[]} Micromark tokens.
+ */
+export function micromarkTokens() {
+  return params?.parsers.micromark.tokens || [];
+}
+
 /**
  * Gets a cached object value - computes it and caches it.
  *
@@ -37,15 +51,15 @@ function getCached(name, getValue) {
 /**
  * Filters a list of Micromark tokens by type and caches the result.
  *
- * @param {import("markdownlint").MicromarkTokenType[]} types Types to allow.
+ * @param {MicromarkTokenType[]} types Types to allow.
  * @param {boolean} [htmlFlow] Whether to include htmlFlow content.
- * @returns {import("markdownlint").MicromarkToken[]} Filtered tokens.
+ * @returns {MicromarkToken[]} Filtered tokens.
  */
 export function filterByTypesCached(types, htmlFlow) {
   return getCached(
     // eslint-disable-next-line prefer-rest-params
     JSON.stringify(arguments),
-    () => filterByTypes(params.parsers.micromark.tokens, types, htmlFlow)
+    () => filterByTypes(micromarkTokens(), types, htmlFlow)
   );
 }
 
@@ -57,6 +71,6 @@ export function filterByTypesCached(types, htmlFlow) {
 export function getReferenceLinkImageData() {
   return getCached(
     getReferenceLinkImageData.name,
-    () => helpersGetReferenceLinkImageData(params.parsers.micromark.tokens)
+    () => helpersGetReferenceLinkImageData(micromarkTokens())
   );
 }