Markuplint

https://markuplint.dev
Admin
Markuplint is an HTML linter that enforces conformance to standards like HTML and WAI-ARIA while...
Tokens:37,807
Snippets:533
Trust Score:7.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Initialize Markuplint in Your Project

Source: https://markuplint.dev/docs/guides

Set up Markuplint within your project by running the initialization command. This command interactively guides you through the setup process and installs necessary modules.

```bash
npx markuplint --init  
```

--------------------------------

### Create Markuplint Rule CLI

Source: https://markuplint.dev/docs/guides/custom-rule

Use the Markuplint CLI to initiate the creation of a new custom rule. This command guides you through the setup process.

```bash
npx @markuplint/create-rule  
```

--------------------------------

### Configuring Plugins with Settings

Source: https://markuplint.dev/docs/configuration/properties

Provides examples of how to load plugins, including specifying custom settings for them.

```json
{
  "plugins": [
    "third-party-plugin",
    "@third-party/markuplint-plugin",
    {
      "name": "third-party-plugin2",
      "settings": {
        "foo": "bar"
      }
    },
    "./path/to/local-plugin.js",
    {
      "name": "./path/to/local-plugin.js2",
      "settings": {
        "foo": "bar"
      }
    }
  ]
}
```

--------------------------------

### Install Pug Parser with Bun

Source: https://markuplint.dev/docs/guides/besides-html

Install the Pug parser plugin using Bun. This is necessary for linting Pug syntax.

```bash
bun add --dev @markuplint/pug-parser
```

--------------------------------

### Markuplint Configuration for Architected CSS

Source: https://markuplint.dev/docs/configuration/usecases/architected-css

Provides a markuplint configuration example using the `class-naming` rule with `regexSelector` to enforce architected CSS conventions. This setup defines rules for block and element naming, including nesting constraints.

```json
{
  "rules": {
    "class-naming": "/^[A-Z][a-z0-9]+$/"
  },
  "childNodeRules": [
    {
      "regexSelector": {
        "attrName": "class",
        "attrValue":
          // Capture a block name
          "/^(?<BlockName>[A-Z][a-z0-9]+)(?:__[a-z][a-z0-9-]+)?$/"
      },
      "rules": {
        "class-naming": {
          "value": [
            // Expand a block name by Mustache format
            "/^{{BlockName}}__[a-z][a-z0-9-]+$/",
            "/^([A-Z][a-z0-9]+)$/"
          ]
        }
      }
    }
  ]
}
```

--------------------------------

### Install Pug Parser with pnpm

Source: https://markuplint.dev/docs/guides/besides-html

Install the Pug parser plugin using pnpm. This is necessary for linting Pug syntax.

```bash
pnpm add -D @markuplint/pug-parser
```

--------------------------------

### Markuplint Configuration Example for SVG Images

Source: https://markuplint.dev/docs/rules/wai-aria

An example configuration for markuplint that adjusts the wai-aria rule for SVG images, specifically addressing Safari/VoiceOver behavior with implicit roles.

```json
{
  "rules": {
    "wai-aria": true
  },
  "nodeRules": [
    {
      "selector": "img[src$=.svg]",
      "rules": {
        // Allows the implicit role:
        "wai-aria": {
          "options": {
            "disallowSetImplicitRole": false
          }
        },
        // Change to require to specify role attributes:
        "required-attr": "role",
        // Allow only img value for the role attribute:
        "invalid-attr": {
          "options": {
            "allowAttrs": [
              {
                "name": "role",
                "value": {
                  "enum": ["img"]
                }
              }
            ]
          }
        }
      }
    }
  ]
}
```

--------------------------------

### Install Pug Parser with npm

Source: https://markuplint.dev/docs/guides/besides-html

Install the Pug parser plugin using npm. This is necessary for linting Pug syntax.

```bash
npm install -D @markuplint/pug-parser
```

--------------------------------

### Install Pug Parser with Yarn

Source: https://markuplint.dev/docs/guides/besides-html

Install the Pug parser plugin using Yarn. This is necessary for linting Pug syntax.

```bash
yarn add --dev @markuplint/pug-parser
```

--------------------------------

### Install Vue Parser and Spec Plugin with Bun

Source: https://markuplint.dev/docs/guides/besides-html

Install the Vue parser and its corresponding spec plugin using Bun. This is required for linting Vue.js syntax with specific Vue rules.

```bash
bun add --dev @markuplint/vue-parser @markuplint/vue-spec
```

--------------------------------

### JSON Configuration

Source: https://markuplint.dev/docs/configuration

Example of a Markuplint configuration file in JSON format. Use this to specify rules and options.

```json
{
  "extends": ["markuplint:recommended"]
}
```

--------------------------------

### Example of File Overrides

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates how to use the `overrides` property to apply specific configurations to files matching a glob pattern.

```json
{
  "rules": {
    "any-rule": true
  },
  "overrides": {
    "./path/to/**/*": {
      "rules": {
        "any-rule": false
      }
    }
  }
}
```

--------------------------------

### JavaScript Configuration

Source: https://markuplint.dev/docs/configuration

Example of a Markuplint configuration file in JavaScript format. Use this for more complex configurations or dynamic settings.

```javascript
module.exports = {
  extends: ['markuplint:recommended'],
};
```

--------------------------------

### Correct Class Name Example

Source: https://markuplint.dev/docs/rules/class-naming

Demonstrates a class name that conforms to the configured naming convention.

```html
<!-- "class-naming": "/[a-z]+(?:__[a-z]+(?:--[a-z]+))?/") -->  

<div class="block"></div>  

```

--------------------------------

### Install Vue Parser and Spec Plugin with npm

Source: https://markuplint.dev/docs/guides/besides-html

Install the Vue parser and its corresponding spec plugin using npm. This is required for linting Vue.js syntax with specific Vue rules.

```bash
npm install -D @markuplint/vue-parser @markuplint/vue-spec
```

--------------------------------

### Install JSX Parser and Spec Plugin with Bun

Source: https://markuplint.dev/docs/guides/besides-html

Install the JSX parser and its corresponding spec plugin using Bun. This is required for linting JSX syntax with specific React rules.

```bash
bun add --dev @markuplint/jsx-parser @markuplint/react-spec
```

--------------------------------

### Correct Heading Levels

Source: https://markuplint.dev/docs/rules/heading-levels

This example shows correct usage with sequential heading levels, adhering to the rule.

```html
<h1>Heading 1</h1>  

<h2>Heading 2</h2>  

<h3>Heading 3</h3>  
```

--------------------------------

### YAML Configuration

Source: https://markuplint.dev/docs/configuration

Example of a Markuplint configuration file in YAML format. This is an alternative to JSON for specifying rules and options.

```yaml
extends:
  - markuplint:recommended
```

--------------------------------

### Configuration example: Multiple required attributes

Source: https://markuplint.dev/docs/rules/required-attr

This JSON configuration specifies that both 'alt' and 'src' attributes are required.

```json
{
  "rules": {
    "required-attr": ["alt", "src"]
  }
}

```

--------------------------------

### Correct Usage of Element

Source: https://markuplint.dev/docs/rules/deprecated-element

This example demonstrates the correct usage of an element, avoiding deprecated tags.

```html
<span class="red">lorem</span>
```

--------------------------------

### Configuration Example for BEM-like CSS Structure

Source: https://markuplint.dev/docs/rules/class-naming

Illustrates how to configure the class-naming rule for BEM-like structures using regex selectors and captured groups.

```json
{
  "rules": {
    "class-naming": "/.+/"
  },
  "childNodeRules": [
    {
      "regexSelector": {
        "attrName": "class",
        "attrValue": "/^(?<BlockName>[A-Z][a-z0-9]+)(?:__[a-z][a-z0-9-]+)?$/"
      },
      "rules": {
        "class-naming": {
          "value": [
            "/^ {{BlockName}}__[a-z][a-z0-9-]+$/",
            "/^([A-Z][a-z0-9]+)$/"
          ]
        }
      }
    }
  ]
}

```

--------------------------------

### Install Vue Parser and Spec Plugin with Yarn

Source: https://markuplint.dev/docs/guides/besides-html

Install the Vue parser and its corresponding spec plugin using Yarn. This is required for linting Vue.js syntax with specific Vue rules.

```bash
yarn add --dev @markuplint/vue-parser @markuplint/vue-spec
```

--------------------------------

### Install Vue Parser and Spec Plugin with pnpm

Source: https://markuplint.dev/docs/guides/besides-html

Install the Vue parser and its corresponding spec plugin using pnpm. This is required for linting Vue.js syntax with specific Vue rules.

```bash
pnpm add -D @markuplint/vue-parser @markuplint/vue-spec
```

--------------------------------

### Run Markuplint Instantly

Source: https://markuplint.dev/docs/guides

Execute Markuplint directly on a target HTML file without project setup. It applies recommended presets if no configuration file is found.

```bash
npx markuplint target.html  
```

--------------------------------

### Example: Defining a list of tokens

Source: https://markuplint.dev/docs/api/types

This configuration shows how to define a list of tokens for an attribute, specifying options like separator, emptiness, order, uniqueness, and case sensitivity.

```json
{
  "type": {
    "token": "URL",
    "separator": "space",
    "allowEmpty": true,
    "ordered": true,
    "unique": true,
    "caseInsensitive": true
  }
}
```

--------------------------------

### Correct Palpable Content Examples

Source: https://markuplint.dev/docs/rules/no-empty-palpable-content

These examples demonstrate correct usage where elements with palpable content are not empty. This includes a div with text content and a div containing an image.

```html
<div>text contet</div>
```

```html
<div><img src="path/to" alt="image content" /></div>
```

--------------------------------

### Available Code Example with Interpolation

Source: https://markuplint.dev/docs/guides/besides-html

Demonstrates valid usage of interpolation within attribute values in markuplint-supported syntaxes.

```html
<div attr="{{ value }}"></div>
```

```html
<div attr='{{ value }}'></div>
```

```html
<div attr="{{ value }}-{{ value2 }}-{{ value3 }}"></div>
```

--------------------------------

### Install JSX Parser and Spec Plugin with npm

Source: https://markuplint.dev/docs/guides/besides-html

Install the JSX parser and its corresponding spec plugin using npm. This is required for linting JSX syntax with specific React rules.

```bash
npm install -D @markuplint/jsx-parser @markuplint/react-spec
```

--------------------------------

### Install JSX Parser and Spec Plugin with pnpm

Source: https://markuplint.dev/docs/guides/besides-html

Install the JSX parser and its corresponding spec plugin using pnpm. This is required for linting JSX syntax with specific React rules.

```bash
pnpm add -D @markuplint/jsx-parser @markuplint/react-spec
```

--------------------------------

### Correct HTML Structure

Source: https://markuplint.dev/docs/rules/no-orphaned-end-tag

This example demonstrates the correct usage of `<p>` and `<br>` tags, avoiding orphaned end tags.

```html
<div>  
  <p>paragraph<br />with break</p>  
</div>  
```

--------------------------------

### Install JSX Parser and Spec Plugin with Yarn

Source: https://markuplint.dev/docs/guides/besides-html

Install the JSX parser and its corresponding spec plugin using Yarn. This is required for linting JSX syntax with specific React rules.

```bash
yarn add --dev @markuplint/jsx-parser @markuplint/react-spec
```

--------------------------------

### Example HTML Structure for Image Naming

Source: https://markuplint.dev/docs/configuration/usecases/consistent-image-file-naming

Demonstrates the correct and incorrect usage of source and img elements based on file naming conventions for different resolutions.

```html
<picture>
  <!-- ✅ Correct -->
  <source srcset="logo@3x.png 3x" />
  <source srcset="logo@2x.png 2x" />
  
  <!-- ❌ Incorrect: Invalid format -->
  <source srcset="logo-3x.png 3x" />
  
  <!-- ❌ Incorrect: Different name -->
  <source srcset="symbol@2x.png 2x" />
  
  <!-- It is the basis -->
  <img src="logo.png" alt="logo" />
</picture>
```

--------------------------------

### TypeScript Configuration

Source: https://markuplint.dev/docs/configuration

Example of a Markuplint configuration file in TypeScript format. This allows for type-safe configuration and is useful in TypeScript projects.

```typescript
import type { Config } from '@markuplint/ml-config';

const config: Config = {
  extends: ['markuplint:recommended'],
};

export default config;
```

--------------------------------

### Incorrect Class Name Example

Source: https://markuplint.dev/docs/rules/class-naming

Demonstrates a class name that violates the configured naming convention.

```html
<!-- "class-naming": "/[a-z]+(?:__[a-z]+(?:--[a-z]+))?/") -->  

<div class="Block"></div>  

```

--------------------------------

### Correct Attribute Usage

Source: https://markuplint.dev/docs/rules/invalid-attr

Examples of HTML with valid attributes that conform to specifications.

```html
<div>
  <button tabindex="0">The Button</button>
  <a href="/" referrerpolicy="no-referrer">The Anchor</a>
</div>
```

--------------------------------

### Incorrect Table: Missing Column

Source: https://markuplint.dev/docs/rules/table-row-column-alignment

This example demonstrates a table where a row is missing columns compared to the header row.

```html
<table>
  <tr>
    <th></th>
    <th colspan="3"></th>
    <th></th>
  </tr>
  <tr class="missing">
    <td></td>
  </tr>
</table>
```

--------------------------------

### JSON Output with CLI

Source: https://markuplint.dev/docs/guides/faq

To get Markuplint's output in JSON format, use the `--format JSON` option with the CLI command.

```bash
markuplint "**/*.html" --format JSON
```

--------------------------------

### Configure Vue Parser and Spec in markuplint

Source: https://markuplint.dev/docs/guides/besides-html

Configuration example for markuplint to use the Vue parser and Vue spec plugin. This enables linting for .vue files.

```json
{
  "parser": {
    "\.vue$": "@markuplint/vue-parser"
  },
  "specs": {
    "\.vue$": "@markuplint/vue-spec"
  }
}
```

--------------------------------

### Configuration example: Attribute with value constraint

Source: https://markuplint.dev/docs/rules/required-attr

This configuration requires the 'src' attribute and enforces a specific pattern for its value using a regular expression.

```json
{
  "rules": {
    "required-attr": [
      "alt",
      {
        "name": "src",
        "value": "/^\/|^https:\/\//i"
      }
    ]
  }
}

```

--------------------------------

### Loading Plugin Configurations

Source: https://markuplint.dev/docs/configuration/properties

Illustrates how to load configurations from plugins using the 'plugin:' prefix, specifying the plugin name and config name.

```json
{
  "extends": ["plugin:third-party-plugin-name/config-name"],
  "plugins": ["third-party-plugin"]
}
```

--------------------------------

### Example Usage with Inherited Attributes

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates how a component configured with `inheritAttrs: true` will render with attributes like `aria-live`. This is useful for accessibility and dynamic styling.

```jsx
<div>
  {/* Evaluate as rendered div element has aria-live="polite"  */}
  <MyComponent aria-live="polite">Lorem Ipsam</MyComponent>
</div>;
```

--------------------------------

### Internationalized Message Example - Japanese

Source: https://markuplint.dev/docs/guides/custom-rule

Example of an internationalized message output in Japanese.

```text
「title」要素がありません  
```

--------------------------------

### Basic Markuplint API Usage

Source: https://markuplint.dev/docs/api

Demonstrates the fundamental steps to initialize the MLEngine, process an HTML file, configure it with a config file, and execute the linting process. It also shows how to listen for log events.

```javascript
import { MLEngine } from 'markuplint';  

const file = await MLEngine.toMLFile('./path/to/page.html');  

const engine = new MLEngine(file, {  
  configFile: './path/to/.markuplintrc',  
});  

engine.on('log', (id, message) => {  
  console.log(id, message);  
});  

const result = await engine.exec();  

console.log(result.violations);  
```

--------------------------------

### Example Usage with Element Attributes

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates rendering a component that is configured to act as an img element with specific attributes. This is useful for ensuring correct rendering and attribute propagation.

```jsx
<div>
  {/* Evaluate as rendered img element has the src attribute and alt="Lorem ipsam"  */}
  <MyComponent />
</div>;
```

--------------------------------

### Correct HTML: With H1

Source: https://markuplint.dev/docs/rules/required-h1

This example shows a valid HTML structure that includes an h1 element, satisfying the required-h1 rule.

```html
<html>
  <head>
    <title>page</title>
  </head>
  <body>
    <main>
      <h1>heading</h1>
      <p>text</p>
    </main>
  </body>
</html>
```

--------------------------------

### Basic Usage

Source: https://markuplint.dev/docs/api

Demonstrates the fundamental steps to initialize and use the MLEngine for linting HTML files. This includes creating an MLFile, configuring the engine, listening for logs, and executing the linting process.

```APIDOC
## Basic Usage

### Description
Initializes and uses the MLEngine for linting HTML files. This involves creating an MLFile, configuring the engine, listening for logs, and executing the linting process.

### Method
```javascript
import { MLEngine } from 'markuplint';

const file = await MLEngine.toMLFile('./path/to/page.html');

const engine = new MLEngine(file, {
  configFile: './path/to/.markuplintrc',
});

engine.on('log', (id, message) => {
  console.log(id, message);
});

const result = await engine.exec();

console.log(result.violations);
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- `violations` (Array) - A list of linting violations found in the file.

#### Response Example
```json
{
  "violations": [
    {
      "ruleId": "some-rule",
      "severity": "error",
      "message": "Violation message",
      "line": 10,
      "col": 5,
      "endLine": 10,
      "endCol": 15,
      "ruleOptions": {}
    }
  ]
}
```
```

--------------------------------

### Internationalized Message Example - English

Source: https://markuplint.dev/docs/guides/custom-rule

Example of an internationalized message output in English.

```text
Missing the "title" element  
```

--------------------------------

### Configuration example: Single required attribute

Source: https://markuplint.dev/docs/rules/required-attr

This JSON configuration sets the `required-attr` rule to enforce the presence of the 'alt' attribute.

```json
{
  "rules": {
    "required-attr": "alt"
  }
}

```

--------------------------------

### Example: invalid-attr rule options

Source: https://markuplint.dev/docs/api/types

This JSON object demonstrates how to configure the 'invalid-attr' rule with allowed attributes and their types.

```json
{
  "invalid-attr": {
    "options": {
      "allowAttrs": [
        {
          "name": "any-attr-name",
          "value": {
            "type": "Boolean"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Using with CommonJS

Source: https://markuplint.dev/docs/api

Provides instructions and an example for using Markuplint within a CommonJS environment by leveraging the `@markuplint/esm-adapter` package. This is particularly useful for Node.js platforms and older Node.js versions.

```APIDOC
## Using with CommonJS

### Description
Enables the use of Markuplint's API from a CommonJS ecosystem using the `@markuplint/esm-adapter`. This adapter is primarily intended for environments like VS Code extensions that do not support ESM natively and operates on the Node.js platform.

### Method
```javascript
const { MLEngine } = require('@markuplint/esm-adapter');

const result = await MLEngine.fromCode(htmlCode);

console.log(result);
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `htmlCode` (string) - The HTML code to be linted.

### Request Example
```json
{
  "htmlCode": "<html><body><h1>Hello</h1></body></html>"
}
```

### Response
#### Success Response (200)
- The structure of the response depends on the `MLEngine.fromCode` implementation, typically containing linting results.

#### Response Example
```json
{
  "violations": [],
  "sourceCode": "<html><body><h1>Hello</h1></body></html>"
}
```

### Notes
- `@markuplint/esm-adapter` is supported only on Node.js versions below 22.
- The implemented APIs are limited and it internally uses Worker threads, making it suitable only for the Node.js platform.
```

--------------------------------

### Extending Configuration with Local Files and Packages

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates how to extend the current configuration by specifying paths to other config files or npm packages.

```json
{
  "extends": [
    "../../.markuplintrc",
    "third-party-config"
  ]
}
```

--------------------------------

### Correct HTML with DOCTYPE

Source: https://markuplint.dev/docs/rules/doctype

This example demonstrates a correctly formed HTML document that includes the `<!doctype html>` declaration, satisfying the `doctype` rule.

```html
<!doctype html>
<html>

  <head>

    <title>Any Page</title>

  </head>

  <body>

    <h1>Any Page</h1>

    <p>Anonymous</p>

  </body>

</html>

```

--------------------------------

### Configure JSX Parser and Spec in markuplint

Source: https://markuplint.dev/docs/guides/besides-html

Configuration example for markuplint to use the JSX parser and React spec plugin. This enables linting for .jsx files.

```json
{
  "parser": {
    "\.jsx$": "@markuplint/jsx-parser"
  },
  "specs": {
    "\.jsx$": "@markuplint/react-spec"
  }
}
```

--------------------------------

### Configuration example: Per-element attribute requirement

Source: https://markuplint.dev/docs/rules/required-attr

This configuration demonstrates how to set the `required-attr` rule to enforce the 'alt' attribute specifically for `<img>` elements using `nodeRules`.

```json
{
  "rules": {
    "required-attr": true
  },
  "nodeRules": [
    {
      "selector": "img",
      "rules": {
        "required-attr": "alt"
      }
    }
  ]
}

```

--------------------------------

### Correct Use of <br> Tags

Source: https://markuplint.dev/docs/rules/no-consecutive-br

This example demonstrates the correct way to handle line breaks, avoiding consecutive <br> tags by using separate paragraphs.

```html
<p>A...</p>  

<p>B...</p>  

```

--------------------------------

### Correct Code: Dynamic ID using a function

Source: https://markuplint.dev/docs/rules/no-hard-code-id

This example demonstrates the correct way to use dynamic IDs by generating them with a function.

```javascript
const id = uid();

<div id={id}></div>;
```

--------------------------------

### Format and Lint Code

Source: https://markuplint.dev/community/contributing

Run this command to format and lint your code according to project standards. Ensure your code adheres to the established style guide before committing.

```bash
yarn lint
```

--------------------------------

### Correct Usage: Allowed Element

Source: https://markuplint.dev/docs/rules/disallowed-element

This example demonstrates the correct usage where the disallowed `hgroup` element is absent, and a standard `h1` is used instead.

```html
<!-- "disallowed-element": ["hgroup"] -->  

<div>  

  <h1>Heading</h1>  

</div>  
```

--------------------------------

### Correct Code: Unique Attributes

Source: https://markuplint.dev/docs/rules/attr-duplication

This example demonstrates correct usage where all attributes are unique, even if they share a similar name prefix.

```html
<div data-attr="value" data-Attr2="db"></div>
```

--------------------------------

### Correct Code: Dynamic ID via Props

Source: https://markuplint.dev/docs/rules/no-hard-code-id

This example shows how to use dynamic IDs by passing them as props to a component.

```javascript
const Component = ({ id }) => <div id={id}></div>;
```

--------------------------------

### Configuration Example: Required Element Rule

Source: https://markuplint.dev/docs/rules/required-element

This JSON configuration demonstrates how to specify the `required-element` rule in the `rules` section of the markuplint configuration to search for elements within the entire document.

```json
{
  "rules": {
    "required-element": ["meta[charset=\"UTF-8\"]"]
  }
}
```

--------------------------------

### Configuration Example: Disallowing hgroup Globally

Source: https://markuplint.dev/docs/rules/disallowed-element

Shows how to configure the `disallowed-element` rule globally within the `rules` object to disallow the `hgroup` element across the entire document.

```json
{
  "rules": {
    "disallowed-element": ["hgroup"]
  }
}
```

--------------------------------

### Correct HTML structure for required-element rule

Source: https://markuplint.dev/docs/rules/required-element

This example demonstrates an HTML structure that satisfies the `required-element` rule by including the specified meta tag.

```html
<!-- "required-element": ["meta[charset=\"UTF-8\"]"] -->  

<head>  

  <meta charset="UTF-8" />  

  <title>Page title</title>  

</head>  
```

--------------------------------

### Unavailable Code Example without Quotations

Source: https://markuplint.dev/docs/guides/besides-html

Illustrates invalid usage where interpolation is not enclosed in quotations, which markuplint may flag as an error.

```html
<div attr={{ value }}></div>
```

--------------------------------

### Execute Linting Script with Bun

Source: https://markuplint.dev/docs/guides

Run the configured Markuplint linting script using Bun.

```bash
bun run lint:html  
```

--------------------------------

### Incorrect Empty Palpable Content Examples

Source: https://markuplint.dev/docs/rules/no-empty-palpable-content

These examples show elements with palpable content that are incorrectly empty, including empty divs, divs with only whitespace, and divs with only whitespace and newlines.

```html
<div></div>
```

```html
<div> </div>
```

```html
<div>  

</div>
```

--------------------------------

### Create MLFile Instance

Source: https://markuplint.dev/docs/api/classes

Use the static toMLFile method to create an MLFile instance for the MLEngine constructor. Specify the path to your HTML file.

```javascript
const file = await MLEngine.toMLFile('./path/to/page.html');
```

--------------------------------

### Correct Usage of `<dl>` with Unique `<dt>`

Source: https://markuplint.dev/docs/rules/no-duplicate-dt

This example demonstrates the correct usage of a `<dl>` where each `<dt>` has a unique name, adhering to the rule.

```html
<dl>
  <dt>Name 1</dt>
  <dd>Content 1</dd>
  <dt>Name 2</dt>
  <dd>Content 2</dd>
  <div>
    <dt>Name 3</dt>
    <dd>Content 3</dd>
  </div>
</dl>
```

--------------------------------

### Configuration Example: Disallowing small within Headings

Source: https://markuplint.dev/docs/rules/disallowed-element

Demonstrates configuring the `disallowed-element` rule using `nodeRules` to disallow the `small` element specifically within `h1` to `h6` elements.

```json
{
  "nodeRules": [
    {
      "selector": "h1, h2, h3, h4, h5, h6",
      "rules": {
        "disallowed-element": ["small"]
      }
    }
  ]
}
```

--------------------------------

### Using 'choice' Keyword for Content Alternatives

Source: https://markuplint.dev/docs/rules/permitted-contents

Demonstrates the use of the `choice` keyword to specify that a container can accept one of several alternative content structures.

```json
{
  "rules": {
    "permitted-contents": [
      {
        "tag": "x-container",
        "contents": [
          {
            "choice": [{ "oneOrMore": "x-item" }, { "oneOrMore": "y-item" }]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Example of Custom Authored Element Detection

Source: https://markuplint.dev/docs/configuration/properties

Illustrates how custom authored element names are detected by Markuplint, preventing them from being treated as native HTML elements.

```html
<template>
  <custom><!-- It detects as a native HTML element if not specified. --></custom>
  <mine><!-- It detects as a native HTML element if not specified. --></mine>
</template>
```

--------------------------------

### React Component with List Rendering and Key Prop

Source: https://markuplint.dev/docs/guides/besides-html

Example of a React component rendering a list, utilizing the 'key' prop for efficient updates. This demonstrates a common pattern where spec plugins are necessary.

```jsx
const Component = ({ list }) => {
  return (
    <ul>
      {list.map(item => (
        <li key={item.key}>{item.text}</li>
      ))}
    </ul>
  );
};

```

--------------------------------

### Setting Permitted Contents for Custom Elements

Source: https://markuplint.dev/docs/rules/permitted-contents

Example configuration for the `permitted-contents` rule, specifying allowed content structures for custom elements `x-container` and `x-item`.

```json
{
  "rules": {
    "permitted-contents": [
      {
        "tag": "x-container",
        "contents": []
      },
      {
        "tag": "x-item",
        "contents": []
      }
    ]
  }
}
```

--------------------------------

### Correct time element usage

Source: https://markuplint.dev/docs/rules/require-datetime

These examples demonstrate valid `<time>` element usage, either by providing machine-readable content directly or by including the `datetime` attribute with a parsable value.

```html
<time>2023-01-05</time>
```

```html
<time datetime="2023-01-05">1/5/2023</time>
```

```html
<time datetime="2023-01-05">Today</time>
```

```html
<time datetime="2023-01-05">令和5年1月5日</time>
```

--------------------------------

### Correct: Using addEventListener for event handling

Source: https://markuplint.dev/docs/rules/no-use-event-handler-attr

This example demonstrates the correct way to handle events using 'addEventListener' in JavaScript, separating event logic from HTML.

```html
<div id="foo">Click</div>

<script>
  document.getElementById('foo').addEventListener('click', () => doSomething());
</script>
```

--------------------------------

### Execute Linting Script with npm

Source: https://markuplint.dev/docs/guides

Run the configured Markuplint linting script using npm.

```bash
npm run lint:html  
```

--------------------------------

### Configuration Example: Required Element Rule with NodeRules

Source: https://markuplint.dev/docs/rules/required-element

This JSON configuration shows how to use `nodeRules` to apply the `required-element` rule to child elements of a specific selector, in this case, the `head` element.

```json
{
  "nodeRules": [
    {
      "selector": "head",
      "rules": {
        "required-element": ["meta[charset=\"UTF-8\"]"]
      }
    }
  ]
}
```

--------------------------------

### Basic CLI Usage

Source: https://markuplint.dev/docs/guides/cli

Demonstrates how to run Markuplint on target HTML files, including multiple files and glob patterns. The CLI returns an exit code of 0 on success and 1 if problems are found.

```bash
$ markuplint target.html

```

```bash
$ markuplint target.html target2.html

```

```bash
$ markuplint "**/*.html"

```

--------------------------------

### MLEngine Constructor

Source: https://markuplint.dev/docs/api/classes

Initializes a new MLEngine instance. It requires an MLFile object and accepts an optional options object to configure linting behavior.

```APIDOC
## MLEngine Constructor

### Description
Initializes a new MLEngine instance with a specified file and optional configuration.

### Parameters
#### `file`
- **MLFile** - Required - An instance of MLFile representing the file to be processed. Use `MLEngine.toMLFile` to create this instance.

#### `options`
- **Object** - Optional - Configuration options for the engine.
  - **configFile** (string) - Optional - The file path of the configuration.
  - **config** (Object) - Optional - The configuration object.
  - **defaultConfig** (Object) - Optional - Fallback configuration.
  - **noSearchConfig** (boolean) - Optional - Disables automatic configuration file search.
  - **locale** (string) - Optional - The locale for messages.
  - **fix** (boolean) - Optional - If true, returns the fixed code.
  - **ignoreExt** (boolean) - Optional - Ignores file extension checks.
  - **rules** (Object[]) - Optional - Additional custom rules.
  - **importPresetRules** (boolean) - Optional - Disables importing preset rules.
  - **debug** (boolean) - Optional - Enables debug logging.
  - **watch** (boolean) - Optional - Enables watch mode for file changes.

### Request Example
```javascript
const file = await MLEngine.toMLFile('./path/to/page.html');
const engine = new MLEngine(file, { configFile: './.markuplintrc' });
```
```

--------------------------------

### Specifying Parsers for File Types

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates how to map file extensions to specific parser packages or local parser files.

```json
{
  "parser": {
    "\.pug$": "@markuplint/pug-parser",
    "\.[jt]sx?$": "@markuplint/jsx-parser",
    "\.vue$": "@markuplint/vue-parser",
    "\.svelte$": "@markuplint/svelte-parser",
    "\.ext$": "./path/to/custom-parser/any-lang.js"
  }
}
```

--------------------------------

### Incorrect Attribute Usage

Source: https://markuplint.dev/docs/rules/invalid-attr

Examples of HTML with attributes that are either non-existent or have invalid type values.

```html
<div unexist-attr>
  <button tabindex="non-integer">The Button</button>
  <a href="/" referrerpolicy="invalid-value">The Anchor</a>
</div>
```

--------------------------------

### Correct Label-Control Association

Source: https://markuplint.dev/docs/rules/label-has-control

These examples demonstrate valid ways to associate label elements with controls using the 'for' attribute or by nesting the control within the label.

```html
<label for="bar">foo</label><input type="text" id="bar" />  

<label>foo<input type="text" /></label>  

<h1><span>New</span> Release Note</h1>  
```

--------------------------------

### Example: Specifying a custom type identifier

Source: https://markuplint.dev/docs/api/types

When using custom type identifiers like '<'color-profile'>', they must be specified as a string including the angle brackets and single quotes.

```json
{
  "type": "<'color-profile'>"
}
```

--------------------------------

### Using :has() with Subsequent-sibling Combinator

Source: https://markuplint.dev/docs/guides/selectors

This example demonstrates how to use the :has() pseudo-class in conjunction with a subsequent-sibling combinator to select elements. It targets 'img' elements that are preceded by a '<picture>' element and have a sibling following them.

```json
{
  "nodeRules": [
    {
      "selector": "picture img:has(~)",
      "rules": {
        "required-attr": true
      }
    }
  ]
}
```

--------------------------------

### Correct: Adjacent Invoker Commands API trigger and target

Source: https://markuplint.dev/docs/rules/neighbor-popovers

This example demonstrates a correct usage of the Invoker Commands API, where the trigger button is immediately followed by its target div.

```html
<button command="toggle-popover" commandfor="foo">Trigger</button>
<div id="foo" popover>Popover</div>

```

--------------------------------

### Deprecated 'attrs' Option: Disallow Attribute

Source: https://markuplint.dev/docs/rules/invalid-attr

Example of using the deprecated 'attrs' option to disallow an attribute.

```json
{
  "invalid-attr": {
    "options": {
      "attrs": {
        "x-attr": {
          "disallowed": true
        }
      }
    }
  }
}
```

--------------------------------

### Deprecated 'attrs' Option: Type Validation

Source: https://markuplint.dev/docs/rules/invalid-attr

Example of using the deprecated 'attrs' option for type validation.

```json
{
  "invalid-attr": {
    "options": {
      "attrs": {
        "x-attr": {
          "type": "Boolean"
        }
      }
    }
  }
}
```

--------------------------------

### Deprecated 'attrs' Option: Enum Validation

Source: https://markuplint.dev/docs/rules/invalid-attr

Example of using the deprecated 'attrs' option for enum validation.

```json
{
  "invalid-attr": {
    "options": {
      "attrs": {
        "x-attr": {
          "enum": ["value1", "value2", "value3"]
        }
      }
    }
  }
}
```

--------------------------------

### Example Usage with ARIA Name from Attribute

Source: https://markuplint.dev/docs/configuration/properties

Demonstrates rendering a component configured as an SVG with its accessible name derived from a component's prop. This ensures proper screen reader support.

```jsx
<div>
  {/* Evaluate as the accessible name is "my icon name" */} 
  <MyIcon label="my icon name" /> 
</div>;
```

--------------------------------

### Incorrect Code: Hard-coded ID

Source: https://markuplint.dev/docs/rules/no-hard-code-id

This example shows an element with a hard-coded id attribute, which violates the rule.

```html
<div id="foo"></div>
```

--------------------------------

### Execute Linting Script with Yarn

Source: https://markuplint.dev/docs/guides

Run the configured Markuplint linting script using Yarn.

```bash
yarn lint:html  
```

--------------------------------

### Incorrect Heading Levels

Source: https://markuplint.dev/docs/rules/heading-levels

This example demonstrates incorrect usage where heading levels are skipped, violating the rule.

```html
<h1>Heading 1</h1>  

<h3>Heading 3<!-- SKIPPED --></h3>  

<h4>Heading 3</h4>  
```

--------------------------------

### Incorrect Usage of Deprecated Element

Source: https://markuplint.dev/docs/rules/deprecated-element

This example shows the incorrect usage of a deprecated HTML element (`<font>`).

```html
<font color="red">lorem</font>
```

--------------------------------

### Incorrect: Unquoted Attribute Value

Source: https://markuplint.dev/docs/rules/attr-value-quotes

This example shows an attribute value that is not enclosed in any quotes, which violates the rule.

```html
<div data-attr=value></div>
```

--------------------------------

### Execute Linting Script with pnpm

Source: https://markuplint.dev/docs/guides

Run the configured Markuplint linting script using pnpm.

```bash
pnpm run lint:html  
```

--------------------------------

### Configuration for Local Project Integration

Source: https://markuplint.dev/docs/guides/custom-rule

Configure your Markuplint settings to include a custom rule from a local project directory. Ensure the plugin path is correctly set.

```json
{
  "plugins": ["./[dir-name]/index.js"], 
  "rules": {
    "[dir-name]/[rule-name]": true 
  }
}
```

--------------------------------

### Incorrect Table: Extra Column

Source: https://markuplint.dev/docs/rules/table-row-column-alignment

This example shows a table with an extra column in one of the rows, violating the rule.

```html
<table>
  <tr>
    <th></th>
  </tr>
  <tr>
    <td></td>
    <td class="extra"></td>
  </tr>
</table>
```

--------------------------------

### Incorrect boolean attribute usage

Source: https://markuplint.dev/docs/rules/no-boolean-attr-value

Boolean attributes should not have explicit values assigned. This example shows incorrect usage.

```html
<input type="text" required="required" />
```

--------------------------------

### Test Your Code

Source: https://markuplint.dev/community/contributing

Run this command to execute all tests and ensure your contributions meet the required quality standards. This helps maintain code integrity and prevent regressions.

```bash
yarn test
```

--------------------------------

### Character Reference Rule Configuration

Source: https://markuplint.dev/docs/rules/character-reference

An example of the JSON configuration interface for the character-reference rule, specifying its severity level.

```json
{
  "character-reference": true
}
```

--------------------------------

### MLEngine Constructor

Source: https://markuplint.dev/docs/api/classes

Instantiates the MLEngine class. Requires an MLFile object and accepts optional configuration options.

```javascript
new MLEngine(file, options);
```

--------------------------------

### Incorrect Code: Duplicate Attribute

Source: https://markuplint.dev/docs/rules/attr-duplication

This example shows an element with a duplicated attribute (`data-attr` and `data-Attr`), which violates the rule.

```html
<div data-attr="value" data-Attr="db"></div>
```

--------------------------------

### Using the 'as' Attribute for Component Mapping

Source: https://markuplint.dev/docs/guides/besides-html

Demonstrates how the 'as' attribute on custom components directly maps them to specified HTML elements.

```html
<x-ul as="ul"><!-- Evaluate as <ul> -->
  <x-li as="li"></x-li><!-- Evaluate as <li> -->
  <x-li as="li"></x-li><!-- Evaluate as <li> -->
  <x-li as="li"></x-li><!-- Evaluate as <li> -->
</x-ul>
```

--------------------------------

### Basic Rule Verification with Document Traversal

Source: https://markuplint.dev/docs/guides/custom-rule

Implement a custom rule's verification logic using Markuplint's document traversal API. This example checks for the presence of 'div' elements.

```javascript
createRule({
  async verify({ document, report }) {
    await document.walkOn('Element', el => {
      if (el.localName === 'div') {
        report({
          scope: el,
          message: 'The div element is found',
        });
      }
    });
  },
});  
```

--------------------------------

### Deprecated 'attrs' Option: Pattern Validation

Source: https://markuplint.dev/docs/rules/invalid-attr

Example of using the deprecated 'attrs' option for pattern validation with a regular expression.

```json
{
  "invalid-attr": {
    "options": {
      "attrs": {
        "x-attr": {
          "pattern": "/[a-z]+/"
        }
      }
    }
  }
}
```

--------------------------------

### Incorrect Table: Overlapped Cells

Source: https://markuplint.dev/docs/rules/table-row-column-alignment

This example shows a table with cells that overlap due to incorrect rowspan and colspan usage.

```html
<table summary="has overlapped cells">
  <tr>
    <td></td>
    <td></td>
    <td rowspan="5"></td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td colspan="5"></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td></td>
    <td></td>
  </tr>
</table>
```

--------------------------------

### Configure Rules with Plugin Namespaces

Source: https://markuplint.dev/docs/configuration/properties

Enable core rules and rules from plugins. Plugin rules are specified with a namespace followed by a solidus and the rule name.

```json
{
  "plugins": ["third-party-plugin", "./path/to/local-plugin.js"],
  "rules": {
    "core-rule-name": true,
    "third-party-plugin/rule-name": true,
    "named-plugin-imported-form-local/rule-name": true
  }
}
```

--------------------------------

### Incorrect HTML: Missing H1

Source: https://markuplint.dev/docs/rules/required-h1

This example demonstrates an HTML structure that violates the required-h1 rule because it lacks an h1 element.

```html
<html>
  <head>
    <title>page</title>
  </head>
  <body>
    <main>
      <p>text</p>
    </main>
  </body>
</html>
```

--------------------------------

### Configuration Interface

Source: https://markuplint.dev/docs/rules/placeholder-label-option

This JSON object defines the configuration interface for the `placeholder-label-option` rule.

```json
{
  "placeholder-label-option": boolean
}
```

--------------------------------

### Correct boolean attribute usage

Source: https://markuplint.dev/docs/rules/no-boolean-attr-value

Boolean attributes should be present without any assigned value. This example shows the correct usage.

```html
<input type="text" required />
```

--------------------------------

### MLEngine.exec Method

Source: https://markuplint.dev/docs/api/classes

Executes the linting process on the file associated with the MLEngine instance. It returns a promise that resolves with the linting results or null if no violations are found.

```APIDOC
## exec()

### Description
Executes the linting process and returns the results, including violations and potentially fixed code.

### Method
`exec(): Promise<Object|null>`

### Parameters
None

### Return
- **Promise<Object|null>** - A promise that resolves to an object containing linting results or null.
  - **violations** (Object[]) - An array of linting violations.
  - **filePath** (string) - The absolute path of the processed file.
  - **sourceCode** (string) - The original source code of the file.
  - **fixedCode** (string) - The fixed source code if the `fix` option was enabled; otherwise, it's the same as `sourceCode`.

### Request Example
```javascript
const result = await engine.exec();

if (result) {
  const { violations, filePath, sourceCode, fixedCode } = result;
  console.log(violations);
}
```
```

--------------------------------

### Incorrect HTML with Orphaned End Tag

Source: https://markuplint.dev/docs/rules/no-orphaned-end-tag

This example shows an orphaned `</p>` tag and a `</br>` tag, which are invalid in HTML.

```html
<div>  
  paragraph</br>with break</p>  
</div>  
```

--------------------------------

### Incorrect Label-Control Association

Source: https://markuplint.dev/docs/rules/label-has-control

These examples show labels that are not associated with a control element or have controls in incorrect positions, violating the rule.

```html
<label>foo</label><input type="text" />  

<h1><label>New</label> Release Note</h1>  
```

--------------------------------

### Configure Rules with String Value

Source: https://markuplint.dev/docs/configuration/properties

Enable or configure rules by specifying their name and a string value. This is a basic way to set rule configurations.

```json
{
  "rules": {
    "rule-name": "value" // Specify the rule name and value to here
  }
}
```

--------------------------------

### Incorrect Usage: Disallowed Element

Source: https://markuplint.dev/docs/rules/disallowed-element

This example shows an incorrect usage where an `hgroup` element is present, which is disallowed by the rule configuration.

```html
<!-- "disallowed-element": ["hgroup"] -->  

<div>  

  <hgroup><h1>Heading</h1></hgroup>  

</div>  
```

--------------------------------

### Basic Rule Verification with DOM API

Source: https://markuplint.dev/docs/guides/custom-rule

Implement a custom rule's verification logic using standard DOM APIs within Markuplint. This example also checks for 'div' elements.

```javascript
createRule({
  async verify({ document, report }) {
    const el = document.querySelector('div');
    if (el) {
      report({
        scope: el,
        message: 'The div element is found',
      });
    }
  },
});  
```

--------------------------------

### Incorrect HTML without DOCTYPE

Source: https://markuplint.dev/docs/rules/doctype

This example shows an HTML document missing the DOCTYPE declaration, which will be flagged by the `doctype` rule.

```html
<html>

  <head>

    <title>Any Page</title>

  </head>

  <body>

    <h1>Any Page</h1>

    <p>Anonymous</p>

  </body>

</html>

```

--------------------------------

### Incorrect Table: Missing Row Cells with rowspan

Source: https://markuplint.dev/docs/rules/table-row-column-alignment

This example illustrates a table with missing cells in a row, complicated by the use of rowspan.

```html
<table>
  <tr class="missing1">
    <th></th>
    <th rowspan="3"></th>
    <!-- missing -->
  </tr>
  <tr>
    <td></td>
    <!-- rowspan area -->
    <td></td>
  </tr>
  <tr>
    <td></td>
    <!-- rowspan area -->
    <td></td>
  </tr>
  <tr class="missing2">
    <td></td>
    <td></td>
    <!-- missing -->
  </tr>
</table>
```

--------------------------------

### Incorrect time element usage

Source: https://markuplint.dev/docs/rules/require-datetime

These examples show `<time>` elements with content that is not machine-readable and lacks the `datetime` attribute, violating the rule.

```html
<time>1/5/2023</time>
```

```html
<time>Today</time>
```

```html
<time>令和5年1月5日</time>
```

--------------------------------

### Configuration Options for `use-list` Rule

Source: https://markuplint.dev/docs/rules/use-list

Details the available options for the `use-list` rule, including `spaceNeededBullets`, `noPrev`, `prevElement`, `prevComment`, and `prevCodeBlock`, to customize detection behavior.

```json
{  
  "use-list": {  
    "options": {  
      "spaceNeededBullets"?: string[]  
      "noPrev"?: boolean  
      "prevElement"?: boolean  
      "prevComment"?: boolean  
      "prevCodeBlock"?: boolean  
    }  
  }  
}  
```

--------------------------------

### Configure Specs with Regex

Source: https://markuplint.dev/docs/configuration/properties

Specify regex patterns to match target files and map them to spec file paths or package names. This allows for custom parsing of different file types.

```json
{
  "specs": {
    "\.vue$": "@markuplint/vue-spec",
    "\.ext$": "./path/to/custom-specs/any-lang.js"
  }
}
```

--------------------------------

### Incorrect Use of Consecutive <br> Tags

Source: https://markuplint.dev/docs/rules/no-consecutive-br

This example shows the incorrect usage of two <br> tags in a row, which this rule flags.

```html
<p>
  
  A...<br />  
  <br />  
  B...  
</p>  

```

--------------------------------

### Incorrect Tag Name Casing

Source: https://markuplint.dev/docs/rules/case-sensitive-tag-name

These examples demonstrate incorrect usage where tag names are not consistently lowercase or uppercase, violating the rule.

```html
<DIV><p>lorem</p></DIV>
```

```html
<IMG src="path/to">
```
Tokens:
Raw