@envsa/remark-config/readme.md

Markdown and MDX linting for @envsa/shared-config.

<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->

<!-- title -->

# @envsa/remark-config

<!-- /title -->

<!-- badges -->

[![NPM Package @envsa/remark-config](https://img.shields.io/npm/v/@envsa/remark-config.svg)](https://npmjs.com/package/@envsa/remark-config)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- /badges -->

<!-- description -->

**Markdown and MDX linting for @envsa/shared-config.**

<!-- /description -->

## Overview

It's a shared [Remark](https://github.com/remarkjs/remark/blob/main/packages/remark-cli/readme.md#example-config-files-json-yaml-js) config for linting Markdown and MDX files, plus a command-line tool `envsa-remark` to streamline project initialization. Note that linting and fixing is provided separately through [@envsa/eslint-config](https://github.com/envsa/shared-config/tree/main/packages/eslint-config).

<!-- recommendation -->

> [!IMPORTANT]
>
> **You can use this package on its own, but it's recommended to use [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/shared-config) instead for a single-dependency and single-package approach to linting and fixing your project.**
>
> This package is included as a dependency in [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/shared-config), which also automatically invokes the command line functionality in this package via its `envsa` command

<!-- /recommendation -->

## Setup

To use just this Remark config in isolation:

1. Install the `.npmrc` in your project root. This is required for correct PNPM behavior:

   ```sh
   pnpm dlx @envsa/repo-config init
   ```

2. Add the package:

   ```sh
   pnpm add -D @envsa/remark-config
   ```

3. Add the starter `.remarkrc.js` and files to your project root, and add any customizations you'd like:

   ```sh
   pnpm exec envsa-remark init
   ```

## Usage

The Remark binary should be picked up automatically by VS Code plugins.

You can call it directly, but it's recommended to use the `envsa` script bundled with the [@envsa/shared-config](https://github.com/envsa/shared-config) instead to invoke the Remark lint rules through ESLint. The [`eslint-mdx`](https://github.com/mdx-js/eslint-mdx) plugin is used to bridge these rules into ESLint and the VS Code ESLint plugin.

If you really want to call it directly, you can integrate a command to the underlying `remark` CLI tool with your `package.json` scripts as you see fit, for example:

```json
{
  "scripts": {
    "lint": "pnpm remark . --quiet --frail"
  }
}
```

### CLI

<!-- cli-help -->

#### Command: `envsa-remark`

Envsa's Remark and Remark Lint shared configuration tools. (Actual linting and fixing is managed through @envsa/eslint-config.)

This section lists top-level commands for `envsa-remark`.

Usage:

```txt
envsa-remark <command>
```

| Command        | Description                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `init`         | Initialize by copying starter config files to your project root or to your package.json file.                 |
| `print-config` | Print the effective Remark configuration. Package-scoped. Searches up to the root of a monorepo if necessary. |

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

_See the sections below for more information on each subcommand._

#### Subcommand: `envsa-remark init`

Initialize by copying starter config files to your project root or to your package.json file.

Usage:

```txt
envsa-remark init
```

| Option              | Description         | Type                 | Default  |
| ------------------- | ------------------- | -------------------- | -------- |
| `--location`        | TK                  | `"file"` `"package"` | `"file"` |
| `--help`<br>`-h`    | Show help           | `boolean`            |          |
| `--version`<br>`-v` | Show version number | `boolean`            |          |

#### Subcommand: `envsa-remark print-config`

Print the effective Remark configuration. Package-scoped. Searches up to the root of a monorepo if necessary.

Usage:

```txt
envsa-remark print-config
```

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

<!-- /cli-help -->

## Configuration

### Avoiding errors in non-git projects

The [remark-validate-links](https://github.com/remarkjs/remark-validate-links) looks for a git remote to validate relative link paths.

If your project is not a git repository, you will receive warning from remark via eslint:

```txt
Command failed: git remote -v
fatal: not a git repository (or any of the parent directories): .git
eslint(undefined-undefined)
```

To fix this, pass the `repository: false` option in your `.remarkrc.js` file:

```js
// .remarkrc.js
import sharedConfig, { overrideRules } from '@envsa/remark-config';

const localConfig = {
  ...sharedConfig,
  plugins: overrideRules(sharedConfig.plugins, [['remarkValidateLinks', { repository: false }]]),
};

export default localConfig;
```

## Credits

[Eric Mika](https://github.com/kitschpatrol) is the author of the original [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) project on which this is based.

<!-- license -->

## License

[MIT](license.txt) © Liam Rella

<!-- /license -->