Nearly Pure Mustard

    remark-cli

    11.0.0 • Public • Published

    remark-cli

    Build Coverage Downloads Sponsors Backers Chat

    Command line interface to inspect and change markdown files with remark.

    Contents

    What is this?

    This package is a command line interface (CLI) that you can use in your terminal or in npm scripts and the like to inspect and change markdown files. This CLI is built around remark, which is a very popular ecosystem of plugins that work with markdown as structured data, specifically ASTs (abstract syntax trees). You can choose from the 150+ plugins that already exist or make your own.

    See the monorepo readme for info on what the remark ecosystem is.

    When should I use this?

    You can use this package when you want to work with the markdown files in your project from the command line. remark-cli has many options and you can combine it with many plugins, so it should be possible to do what you want. If not, you can always use remark itself manually in a script.

    Install

    This package is ESM only. In Node.js (version 14.14+, or 16.0+), install with npm:

    npm install remark-cli

    Use

    Add a table of contents with remark-toc to readme.md:

    remark readme.md --use remark-toc --output

    Lint all markdown files in the current directory according to the markdown style guide with remark-preset-lint-markdown-style-guide.

    remark . --use remark-preset-lint-markdown-style-guide

    CLI

    The interface of remark-cli is explained as follows on its help page (remark --help):

    Usage: remark [options] [path | glob ...]
    
      CLI to process markdown with remark
    
    Options:
    
      -h  --help                              output usage information
      -v  --version                           output version number
      -o  --output [path]                     specify output location
      -r  --rc-path <path>                    specify configuration file
      -i  --ignore-path <path>                specify ignore file
      -s  --setting <settings>                specify settings
      -e  --ext <extensions>                  specify extensions
      -u  --use <plugins>                     use plugins
      -w  --watch                             watch for changes and reprocess
      -q  --quiet                             output only warnings and errors
      -S  --silent                            output only errors
      -f  --frail                             exit with 1 on warnings
      -t  --tree                              specify input and output as syntax tree
          --report <reporter>                 specify reporter
          --file-path <path>                  specify path to process as
          --ignore-path-resolve-from dir|cwd  resolve patterns in `ignore-path` from its directory or cwd
          --ignore-pattern <globs>            specify ignore patterns
          --silently-ignore                   do not fail when given ignored files
          --tree-in                           specify input as syntax tree
          --tree-out                          output syntax tree
          --inspect                           output formatted syntax tree
          --[no-]stdout                       specify writing to stdout (on by default)
          --[no-]color                        specify color in report (on by default)
          --[no-]config                       search for configuration files (on by default)
          --[no-]ignore                       search for ignore files (on by default)
    
    Examples:
    
      # Process `input.md`
      $ remark input.md -o output.md
    
      # Pipe
      $ remark < input.md > output.md
    
      # Rewrite all applicable files
      $ remark . -o
    

    More information on all these options is available at unified-args, which does the work. remark-cli is unified-args preconfigured to:

    Examples

    Example: checking and formatting markdown on the CLI

    This example checks and formats markdown with remark-cli. It assumes you’re in a Node.js package.

    First, install the CLI and plugins:

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

    Now, add an npm script in your package.json:

      /* … */
      "scripts": {
        /* … */
        "format": "remark . --output",
        /* … */
      },
      /* … */

    💡 Tip: add ESLint and such in the format script too.

    Observe that the above change adds a format script, which can be run with npm run format. It runs remark on all markdown files (.) and rewrites them (--output). Run ./node_modules/.bin/remark --help for more info on the CLI.

    Then, add a remarkConfig to your package.json to configure remark:

      /* … */
      "remarkConfig": {
        "settings": {
          "bullet": "*", // Use `*` for list item bullets (default)
          // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
        },
        "plugins": [
          "remark-preset-lint-consistent", // Check that markdown is consistent.
          "remark-preset-lint-recommended", // Few recommended rules.
          [
            // Generate a table of contents in `## Contents`
            "remark-toc",
            {
              "heading": "contents"
            }
          ]
        ]
      },
      /* … */

    👉 Note: you must remove the comments in the above examples when copy/pasting them, as comments are not supported in package.json files.

    Finally, you can run the npm script to check and format markdown files in your project:

    npm run format

    Example: config files (JSON, YAML, JS)

    In the previous example, we saw that remark-cli was configured from within a package.json file. That’s a good place when the configuration is relatively short, when you have a package.json, and when you don’t need comments (which are not allowed in JSON).

    You can also define configuration in separate files in different languages. With the package.json config as inspiration, here’s a JavaScript version that can be placed in .remarkrc.js:

    import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
    import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
    import remarkToc from 'remark-toc'
    
    const remarkConfig = {
      settings: {
        bullet: '*', // Use `*` for list item bullets (default)
        // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
      },
      plugins: [
        remarkPresetLintConsistent, // Check that markdown is consistent.
        remarkPresetLintRecommended, // Few recommended rules.
        // Generate a table of contents in `## Contents`
        [remarkToc, {heading: 'contents'}]
      ]
    }
    
    export default remarkConfig

    This is the same configuration in YAML, which can be placed in .remarkrc.yml:

    settings:
      bullet: "*"
    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

    When remark-cli is about to process a markdown file it’ll search the file system upwards for configuration files starting at the folder where that file exists. Take the following file structure as an illustration:

    folder/
    ├─ subfolder/
    │  ├─ .remarkrc.json
    │  └─ file.md
    ├─ .remarkrc.js
    ├─ package.json
    └─ readme.md
    

    When folder/subfolder/file.md is processed, the closest config file is folder/subfolder/.remarkrc.json. For folder/readme.md, it’s folder/.remarkrc.js.

    The order of precedence is as follows. Earlier wins (so in the above file structure folder/.remarkrc.js wins over folder/package.json):

    1. .remarkrc (JSON)
    2. .remarkrc.json (JSON)
    3. .remarkrc.cjs (CJS)
    4. .remarkrc.mjs (ESM)
    5. .remarkrc.js (CJS or ESM, depending on type: 'module' in package.json)
    6. .remarkrc.yaml (YAML)
    7. .remarkrc.yml (YAML)
    8. package.json with remarkConfig field

    Compatibility

    Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

    Security

    As markdown can be turned into HTML and improper use of HTML can open you up to cross-site scripting (XSS) attacks, use of remark can be unsafe. When going to HTML, you will likely combine remark with rehype, in which case you should use rehype-sanitize.

    Use of remark plugins could also open you up to other attacks. Carefully assess each plugin and the risks involved in using them.

    For info on how to submit a report, see our security policy.

    Contribute

    See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help. Join us in Discussions to chat with the community and contributors.

    This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

    Sponsor

    Support this effort and give back by sponsoring on OpenCollective!

    Vercel

    Motif

    HashiCorp

    GitBook

    Gatsby

    Netlify

    Coinbase

    ThemeIsle

    Expo

    Boost Note

    Holloway


    You?

    License

    MIT © Titus Wormer

    Install

    npm i remark-cli

    DownloadsWeekly Downloads

    106,452

    Version

    11.0.0

    License

    MIT

    Unpacked Size

    18.3 kB

    Total Files

    4

    Last publish

    Collaborators

    • johno
    • wooorm