remark-config-docs

Remark configuration for documentation sites. Includes:

• remark-lint-link-text
• remark-lint-mapbox/frontmatter
• remark-lint-mapbox/link-checker
• remark-lint-mapbox/constantly
• remark-lint-mapbox/mdx
• remark-lint-heading-increment

Install

npm install --save-dev @mapbox/remark-config-docs

Create .remarkrc.js with the following contents (update the config with values that are meaningful to the site):

const rc = require("@mapbox/remark-config-docs");
const config = {
  siteBasePath: "docs-starter-kit",
  constants: "src/constants.json",
  ignoreLinks: "conf/ignore-links.json",
};

exports.plugins = [...rc.plugins(config)];

Configuration

The plugin function take an configuration object:

{
  "siteBasePath": "docs-starter-kit", // required, this is the site's base path
  "siteOrigin": "https://docs.mapbox.com", // default is "https://docs.mapbox.com"
  "pages": "src/pages/", // default is "src/pages/"
  "constants": "src/constants.json", // optional, but encouraged. This value is the relative path to the site's constants file. Used by constantly to assert constant values.
  "ignoreLinks": "conf/ignore-links.json", // optional. Used by link-checker to ignore specific links.
  "disable": ["remark-lint-heading-increment"] // optional. Array of plugin names to be disabled for this site.
}

Add a remark-lint plugin to your local configuration

If you have a specific linter to add to a single repository, you can add it to exports.plugins array. For example, you want to add the remark-lint-roller plugin, your .remarkrc.js could look like:

const rc = require("@mapbox/remark-config-docs");
const config = {
  siteBasePath: "docs-starter-kit",
  constants: "src/constants.json",
  ignoreLinks: "conf/ignore-links.json",
};

exports.plugins = [...rc.plugins(config), ["remark-lint-roller", [2]]];

📚 See unified-engine/configure.md for more options to extend your remark configuration file.

Add a new plugin to remark-config-docs

1. Add the plugin to peerDependencies in package.json.
2. Update README.md to list the plugin and document any configuration changes or additions.
3. Add the plugin in index.js.
4. Add a test in text/index.test.js to make sure the new plugin outputs in the configuration as you expect.

How to release

From the main branch:

1. If you haven't already, update CHANGELOG.md to describe the changes, commit, and push.
2. Run npm version {major|minor|patch}. Example (and usually): npm version minor.
3. Push changes.
4. Run mbx npm publish to publish the package to npm.

Dependabot will automatically update @mapbox/remark-config-docs (within 1 day) to all site repositories. If you need it sooner, you can install this package in the repository by following the install steps.

This package uses npm 7, which means it will automatically install the peerDependnecies found in package.json. If your site requires a different version of a peer dependency, you can install the dependency in your repository using the --force flag. Example: npm i @mapbox/[email protected] --force.