### Configure markdownlint with Required Headings
Source: https://github.com/davidanson/markdownlint/blob/main/test/required-headings-question-missing.md
This configuration sets up markdownlint to enforce specific headings within a project's markdown files. It ensures that the document starts with '# Project Name', followed by an unspecified heading, and then '## Examples'. This helps maintain a consistent document structure.
```markdown
{MD043:+1}
```
--------------------------------
### Markdownlint File Configuration Example
Source: https://github.com/davidanson/markdownlint/blob/main/test/headings_with_spaces_at_the_beginning.md
Shows how to configure markdownlint for a specific file by disabling certain rules. This example disables the 'heading-style' and 'first-line-heading' rules.
```json
{
"heading-style": false,
"first-line-heading": false
}
```
--------------------------------
### YAML Configuration Block
Source: https://github.com/davidanson/markdownlint/blob/main/test/spaces_inside_emphasis_markers.md
An example of an autogenerated YAML configuration block used within Markdown documentation.
```yaml
# YAML...
```
--------------------------------
### Fenced Code Block Language Examples
Source: https://github.com/davidanson/markdownlint/blob/main/test/md040-language_only.md
Examples showing how markdownlint interprets fenced code blocks with varying language declarations, including whitespace and extra metadata. These examples illustrate how the parser handles different formatting styles for language tags.
```html
``` html
markdownlint
```
```
```css
```css
body {} {MD009:11}
```
```
```html
```html version=5
MarkdownLint {MD040:17}
```
```
```css
```css
a {}
```
```
--------------------------------
### Configure markdownlint rules and severity
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
Examples of how to enable, disable, and set severity levels for rules, tags, or the default configuration within the options.config object.
```javascript
{
"rule_tag_or_default": false
}
{
"rule_tag_or_default": true
}
{
"rule_tag_or_default": "warning"
}
{
"rule": {
"severity": "error",
"rule_parameter": "value"
}
}
```
--------------------------------
### Markdownlint Configuration Example
Source: https://github.com/davidanson/markdownlint/blob/main/test/code-block-with-language-allowed.md
An example of a markdownlint configuration comment. This shows how to configure rules like 'no-hard-tabs' and 'code-block-style' directly within the markdown file.
```markdown
```
--------------------------------
### Define complex markdownlint configuration
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
An example of a comprehensive configuration object utilizing default settings, specific rule overrides, and tag-based rule disabling.
```json
{
"default": true,
"MD003": { "style": "atx_closed" },
"MD007": { "indent": 4 },
"no-hard-tabs": false,
"whitespace": false
}
```
--------------------------------
### Valid ordered list examples by style
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md029.md
Demonstrates valid list formatting for different style configurations including 'one', 'ordered', and 'zero'. These examples show how the rule expects numerical sequences to be defined.
```markdown
1. Do this.
1. Do that.
1. Done.
```
```markdown
1. Do this.
2. Do that.
3. Done.
```
```markdown
0. Do this.
0. Do that.
0. Done.
```
--------------------------------
### Text Content Example
Source: https://github.com/davidanson/markdownlint/blob/main/test/code-block-with-language-allowed.md
A simple text block example. This snippet is used to demonstrate how markdownlint handles plain text content within markdown.
```text
hello
world
}
```
--------------------------------
### MD003 Heading Style Examples
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md003.md
Examples demonstrating inconsistent heading styles that trigger MD003, the corrected consistent ATX style, and the allowed hybrid Setext/ATX configuration.
```markdown
# ATX style H1
## Closed ATX style H2 ##
Setext style H1
===============
```
```markdown
# ATX style H1
## ATX style H2
```
```markdown
Setext style H1
===============
Setext style H2
---------------
### ATX style H3
```
```markdown
A line of text followed by a horizontal rule becomes a heading
---
```
--------------------------------
### Markdown Trailing Space Examples
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md009.md
Examples demonstrating the use of trailing spaces for line breaks and indentation within list items as governed by MD009.
```markdown
Text text text
text
```
```markdown
- list item text
list item text
```
--------------------------------
### Hard Tab Usage Example
Source: https://github.com/davidanson/markdownlint/blob/main/test/code-block-with-language-allowed.md
Demonstrates the use of hard tabs within code blocks, which markdownlint's MD010 rule typically flags. This example shows a line with a hard tab.
```text
Line with hard tab. {MD010}
```
--------------------------------
### Markdown heading styles
Source: https://github.com/davidanson/markdownlint/blob/main/test/incorrect_heading_setext.md
Examples of different heading styles supported by markdownlint, including ATX-style and Setext-style headers. These styles are subject to the MD003 rule.
```markdown
# Heading 1 {MD003} #
## Heading 2 {MD003}
Heading 3
---------
```
--------------------------------
### Sample markdown with MD055 table pipe styles
Source: https://github.com/davidanson/markdownlint/blob/main/test/snapshots/markdownlint-test-scenarios.mjs.md
A markdown example demonstrating various table pipe configurations including trailing, both, none, and leading styles. These examples are used to test the MD055 rule enforcement.
```markdown
# Table Pipe Style Implicit Trailing
## Style: trailing
Table | Heading |
----- | ------- |
Cell | Cell |
## Style: both {MD055:+2} {MD055:+3} {MD055:+4}
| Table | Heading |
| ----- | ------- |
| Cell | Cell |
## Style: none {MD055:+2} {MD055:+3} {MD055:+4}
Table | Heading
----- | -------
Cell | Cell
## Style: leading {MD055:+2} {MD055:+3} {MD055:+4}
| Table | Heading
| ----- | -------
| Cell | Cell
```
--------------------------------
### MD042 Rule Violation and Fix Examples
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md042.md
Examples demonstrating Markdown link syntax that triggers the MD042 rule versus valid link syntax. This rule flags empty link destinations and empty fragment identifiers.
```markdown
[an empty link]()
```
```markdown
[a valid link](https://example.com/)
```
```markdown
[an empty fragment](#)
```
```markdown
[a valid fragment](#fragment)
```
--------------------------------
### Markdown Fenced Code Block Example (With Language)
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md040.md
This example shows a correctly formatted fenced code block in Markdown with a language specifier ('bash'). Adding the language improves rendering and syntax highlighting, satisfying the MD040 rule.
```markdown
```bash
#!/bin/bash
echo Hello world
```
```
--------------------------------
### Markdown: Consistent Heading Styles Example
Source: https://github.com/davidanson/markdownlint/blob/main/doc-build/md003.md
Shows a corrected markdown document using only ATX heading styles for consistency.
```markdown
# ATX style H1
## ATX style H2
```
--------------------------------
### MD049 Emphasis Style Examples
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md049.md
Demonstrates inconsistent emphasis usage that triggers the rule and the corrected consistent version.
```markdown
*Text*
_Text_
```
```markdown
*Text*
*Text*
```
--------------------------------
### Load and extend markdownlint configurations
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
Demonstrates how to load external style files using require in JavaScript or the extends keyword in JSON configuration files.
```javascript
const options = {
"files": [ "..." ],
"config": require("style/relaxed.json")
};
```
```json
{
"extends": "markdownlint/style/relaxed"
}
```
--------------------------------
### Markdown Example: Style Guide Variations for List Marker Spacing
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md030.md
Illustrates how different document style guides may dictate varying numbers of spaces after list markers, especially when list items contain multiple paragraphs.
```markdown
* Foo
* Bar
* Baz
* Foo
Second paragraph
* Bar
```
```markdown
1. Foo
Second paragraph
1. Bar
```
--------------------------------
### Reading Configuration with Promises
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
Presents the promise-based API for reading markdownlint configuration files. This approach allows for cleaner asynchronous handling using `async/await` or `.then()` chains. It accepts the file path, optional parsers, and a file system implementation, returning a Promise that resolves with the configuration object.
```javascript
/**
* Read specified configuration file.
*
* @param {string} file Configuration file name.
* @param {ConfigurationParser[]} [parsers] Parsing function(s).
* @param {Object} [fs] File system implementation.
* @returns {Promise} Configuration object.
*/
function readConfig(file, parsers, fs) { ... }
```
--------------------------------
### Define Shell Commands in Markdown
Source: https://github.com/davidanson/markdownlint/blob/main/test/snapshots/markdownlint-test-scenarios.mjs.md
Examples of shell command formatting within Markdown files, often used for installation instructions or CLI demonstrations.
```sh
npm install --save multimatch
```
```sh
ls example
```
--------------------------------
### Reading Configuration Asynchronously
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
Demonstrates the asynchronous API for reading markdownlint configuration files. It includes parameters for the file path, optional parsers, a file system implementation, and a callback function for handling the result or errors.
```javascript
/**
* Read specified configuration file.
*
* @param {string} file Configuration file name.
* @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).
* @param {Object} [fs] File system implementation.
* @param {ReadConfigCallback} [callback] Callback (err, result) function.
* @returns {void}
*/
function readConfig(file, parsers, fs, callback) { ... }
```
--------------------------------
### Markdown Example: Document with a top-level heading
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md041.md
Demonstrates a corrected Markdown document that adheres to the MD041 rule by starting with a top-level heading.
```markdown
# Document Heading
This is a document with a top-level heading
```
--------------------------------
### MD023 Heading Indentation Examples
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md023.md
Demonstrates the violation of MD023 where a heading is indented, and the correct format where the heading starts at the beginning of the line. It also shows that block quotes are an exception to this rule.
```markdown
Some text
# Indented heading
```
```markdown
Some text
# Heading
```
```markdown
> # Heading in Block Quote
```
--------------------------------
### Shell Command Code Blocks
Source: https://github.com/davidanson/markdownlint/blob/main/test/code_block_dollar_fence.md
Examples of shell commands formatted as code blocks for package installation and file listing. These blocks include the MD014 rule identifier for linting compliance.
```sh
$ npm install --save multimatch {MD014}
```
```sh
$ ls example {MD014}
```
--------------------------------
### Markdown Example: Correct Heading Spacing (MD022)
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md022.md
Shows the corrected version of markdown where headings are properly surrounded by blank lines, adhering to the MD022 rule. This serves as a visual guide for implementing the rule's requirements.
```markdown
# Heading 1
Some text
Some more text
## Heading 2
```
--------------------------------
### Applying and Extending Style Presets
Source: https://context7.com/davidanson/markdownlint/llms.txt
Explains how to utilize built-in style presets like 'relaxed' and 'all' to manage rule sets. It also demonstrates how to extend these presets with custom rule overrides.
```javascript
import { lint } from "markdownlint/sync";
import relaxedStyle from "markdownlint/style/relaxed";
import allStyle from "markdownlint/style/all";
const relaxedResults = lint({
"strings": { "content": "# Title\n\nSome very long line that would normally trigger MD013 but relaxed style has it disabled for convenience in many projects.\n" },
"config": relaxedStyle
});
console.log("Relaxed violations:", relaxedResults.content.length);
const strictResults = lint({
"strings": { "content": "# Title\n\nSome very long line that would normally trigger MD013 but relaxed style has it disabled for convenience in many projects.\n" },
"config": allStyle
});
console.log("Strict violations:", strictResults.content.length);
const customConfig = {
...relaxedStyle,
"MD041": true,
"MD013": { "line_length": 120 }
};
const customResults = lint({
"strings": { "content": "No heading first line\n" },
"config": customConfig
});
console.log("Custom violations:", customResults.content.length);
```
--------------------------------
### Configure markdownlint for Front Matter Title
Source: https://github.com/davidanson/markdownlint/blob/main/test/front-matter-alt-title-toml.md
This snippet shows how to configure markdownlint to use a specific front matter field for the first line heading. It targets the 'front_matter_title' rule and specifies a regular expression to match the 'alternate' field. This is useful for static site generators or documentation setups that use custom front matter.
```markdown
```
--------------------------------
### Reading Configuration Synchronously
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
Illustrates the synchronous API for reading markdownlint configuration files. This function takes the file path, optional parsers, and a file system implementation, returning the configuration object directly.
```javascript
/**
* Read specified configuration file.
*
* @param {string} file Configuration file name.
* @param {ConfigurationParser[]} [parsers] Parsing function(s).
* @param {Object} [fs] File system implementation.
* @returns {Configuration} Configuration object.
*/
function readConfig(file, parsers, fs) { ... }
```
--------------------------------
### Markdown Reference Link and Image Syntax
Source: https://github.com/davidanson/markdownlint/blob/main/doc-build/md052.md
Examples of full, collapsed, and shortcut reference syntax for links and images, along with their corresponding label definitions.
```markdown
Full: [text][label]
Collapsed: [label][]
Shortcut: [label]
Full: ![text][image]
Collapsed: ![image][]
Shortcut: ![image]
[label]: https://example.com/label
[image]: https://example.com/image
```
--------------------------------
### Demonstrate JavaScript indentation and rule violations
Source: https://github.com/davidanson/markdownlint/blob/main/test/code-block-with-tabs.md
A collection of JavaScript code snippets demonstrating various indentation styles and markdownlint rule triggers. These examples highlight how specific formatting patterns relate to MD010 and MD046 rules.
```javascript
if (true) {
console.log("true");
if (false) {
console.log("false");
}
}
```
```javascript
if (true) {
console.log("true"); // {MD010}
if (false) { // {MD010}
console.log("false"); // {MD010}
} // {MD010}
}
```
```javascript
if (true) { // {MD046}
console.log("true");
if (false) {
console.log("false");
}
}
```
```javascript
if (true) { // {MD010}
console.log("true"); // {MD010}
if (false) { // {MD010}
console.log("false"); // {MD010}
} // {MD010}
} // {MD010}
```
--------------------------------
### MD005 Violation Example
Source: https://github.com/davidanson/markdownlint/blob/main/doc/md005.md
An example of a Markdown list where the final item is misaligned, triggering the MD005 rule.
```markdown
* Item 1
* Nested Item 1
* Nested Item 2
* A misaligned item
```
--------------------------------
### Configuration Options API
Source: https://github.com/davidanson/markdownlint/blob/main/README.md
A collection of configuration parameters used to initialize and control the markdownlint engine.
```APIDOC
## Configuration Options
### Description
These options are used to configure the behavior of the markdownlint library during the linting process.
### Parameters
- **options.configParsers** (Array) - Optional - Functions to parse markdownlint-configure-file blocks.
- **options.customRules** (Array