Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/remarkjs/remark/llms.txt

Use this file to discover all available pages before exploring further.

remark-cli automatically searches for configuration files as it processes each markdown file, walking up the file system from the file’s directory until it either finds a config file or reaches the filesystem root. This means you can scope configuration to a sub-tree of your project without any extra flags — just drop a .remarkrc.json (or any supported format) into the relevant directory.

​
Configuration file formats

Eight file names are recognised, checked in the order listed below. The first match wins, so a .remarkrc in the same directory always takes precedence over a package.json further up the tree.
PriorityFileFormat
1.remarkrcJSON
2.remarkrc.cjsCommonJS
3.remarkrc.jsonJSON
4.remarkrc.jsCJS or ESM (follows "type" in package.json)
5.remarkrc.mjsESM
6.remarkrc.yamlYAML
7.remarkrc.ymlYAML
8package.json (remarkConfig field)JSON
JSON config files (package.json, .remarkrc, .remarkrc.json) do not support comments. If you want to annotate your configuration with explanations, use .remarkrc.js or .remarkrc.yml instead.

​
Config in package.json

Adding a remarkConfig field to your existing package.json is the quickest way to get started — no extra file needed. 
{
  "remarkConfig": {
    "settings": {
      "bullet": "*"
    },
    "plugins": [
      "remark-preset-lint-consistent",
      "remark-preset-lint-recommended",
      ["remark-toc", {"heading": "contents"}]
    ]
  }
}

​
Config in .remarkrc.js (ESM)

A JavaScript config file unlocks the full expressiveness of ESM imports, dynamic values, and inline comments. When your package.json sets "type": "module", .remarkrc.js is treated as ESM. 
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'

const remarkConfig = {
  plugins: [
    remarkPresetLintConsistent, // Check that markdown is consistent.
    remarkPresetLintRecommended, // Few recommended rules.
    // Generate a table of contents in `## Contents`
    [remarkToc, { heading: 'contents' }]
  ],
  settings: {
    bullet: '*' // Use `*` for list item bullets (default)
  }
}

export default remarkConfig

​
Config in .remarkrc.yml

YAML is a compact, human-readable format that also supports comments. It is a good middle ground between the terseness of JSON and the flexibility of JavaScript. 
plugins:
  # Check that markdown is consistent.
  - remark-preset-lint-consistent
  # Few recommended rules.
  - remark-preset-lint-recommended
  # Generate a table of contents in `## Contents`
  - - remark-toc
    - heading: contents
settings:
  bullet: "*"

​
How config resolution works

When remark-cli is about to process a file it climbs the directory tree looking for the nearest config file. Consider this project layout: 
folder/
├─ subfolder/
│  ├─ .remarkrc.json
│  └─ file.md
├─ .remarkrc.js
├─ package.json
└─ readme.md
  • folder/subfolder/file.md is processed using folder/subfolder/.remarkrc.json — the closest match.
  • folder/readme.md is processed using folder/.remarkrc.js — the closest match at the folder/ level.
The folder/package.json is not used for either file because .remarkrc.js appears earlier in the precedence order and sits at the same level.

​
Ignoring files with .remarkignore

Place a .remarkignore file anywhere in your project to tell remark-cli which files to skip. Each line is a glob pattern, interpreted the same way as .gitignore entries. 
# Ignore generated docs
docs/generated/**

# Ignore changelogs
CHANGELOG.md
**/CHANGELOG.md
remark-cli discovers .remarkignore files by walking upwards from each processed file, so scoped ignore rules work the same way as scoped config files. You can also point to a custom ignore file with the --ignore-path flag.

​
The settings field

The settings key in any config file is passed directly to remark-stringify and controls how the markdown serialiser formats output. Common options include:
OptionTypeDescription
bullet"*" | "+" | "-"Character used for unordered list items
emphasis"*" | "_"Character used for emphasis (italic)
strong"*" | "_"Character used for strong (bold)
fence"`" | "~"Character used for fenced code blocks
setextbooleanUse setext-style headings (=== / ---)
Refer to the remark-stringify API reference for the full list of serialiser options.

​
Setting up a format script

1

Install the CLI and your plugins

npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc
2

Add a remarkConfig to package.json

{
  "remarkConfig": {
    "settings": {
      "bullet": "*"
    },
    "plugins": [
      "remark-preset-lint-consistent",
      "remark-preset-lint-recommended",
      ["remark-toc", {"heading": "contents"}]
    ]
  }
}
3

Add a format script to package.json

{
  "scripts": {
    "format": "remark . --output"
  }
}
4

Run the script

npm run format
This rewrites every markdown file in the project in place, applying your configured plugins and serialiser settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us