uetchy/mdmod

✂️🧬 Powerful & extensible Markdown fragment editor

mdmod

Powerful & extensible Markdown fragment editor.

Features

• Programmatically update portion of Markdown document (Table of Contents, package index for Monorepo, version number in the installation guide, etc)
• Plugins to extend its usage

Install

npm i -g mdmod

Use case - update version string in the installation guide

Suppose we are about to update the README.md for the latest version v6.0.0.

Define a block starting with <!-- START mdmod --> and with a trailing <!-- END mdmod -->, and then pass the option as an object, where match is /v\d\.\d\.\d/g and replace is version.

<!-- START mdmod {match: /v\d\.\d\.\d/g, replace: version} -->

```
curl https://path/to/releases/v0.4.0.tar.gz
tar -zxvf v0.4.0.tar.gz
```

<!-- END mdmod -->

Run mdmod with a variable version set v6.0.0:

mdmod README.md --define.version v6.0.0

This will replace all the string matched /v\d\.\d\.\d/ with the content of version defined in the CLI argument:

<!-- START mdmod {match: /v\d\.\d\.\d/g, replace: version} -->

```
curl https://path/to/releases/v6.0.0.tar.gz
tar -zxvf v6.0.0.tar.gz
```

<!-- END mdmod -->

Configuration

MdmodOption

{
  replace: (() => string) | string,
  match?: RegExp,
  use?: string | [string, string]
}

• replace: function or variable or string literal to replace with
• match (optional): regular expression to match text. Without match, mdmod will replace whole text.
• use (optional): specify plugin to use. If use property is given, other options will be ignored. If relative path is given (e.g. use: "./scripts/contributors.js"), use the specified script as a plugin. You can pass args to a plugin like this: use: ["somePlugin", {foo: "bar"}]

See CONTRIBUTING.md for more information on how to write a plugin.

Start of block

<!-- START mdmod MdmodOption -->
<!-- START mdmod [MdmodOption, MdmodOption, ...] -->

End of block

<!-- END mdmod -->

Environment variable

Instead of using --define.<key>=<value>, you can also define a variable with exporting environment variable MDMOD_<key>. <key> will be lowercased and added to the VM's constant dictionary.

Official Plugins

Table of Contents (mdmod-plugin-toc)

Generate a table of contents.

npm i -g mdmod-plugin-toc
mdmod README.md

<!-- START mdmod {use: 'toc'} -->
<!-- END mdmod -->

would produce:

- [mdmod](#mdmod)
  - [Features](#features)
  - [Install](#install)
  - [Example Usage](#example-usage)
  - [Configuration](#configuration)
    - [MdmodOption](#mdmodoption)
    - [Start of block](#start-of-block)
    - [End of block](#end-of-block)
    - [Environment variable](#environment-variable)
  - [Official Plugins](#official-plugins)
    - [Table of Contents (`mdmod-plugin-toc`)](#table-of-contents-mdmod-plugin-toc)
    - [Table of Packages (`mdmod-plugin-top`)](#table-of-packages-mdmod-plugin-top)
  - [Usage Tips](#usage-tips)
    - [Sync version text in README.md with the latest `git tag`](#sync-version-text-in-readmemd-with-the-latest-git-tag)
    - [Automated workflow with `husky` and `lint-staged`](#automated-workflow-with-husky-and-lint-staged)

Table of Packages (mdmod-plugin-top)

Generate a list of monorepo packages (/packages/*).

npm i -g mdmod-plugin-top
mdmod README.md

<!-- START mdmod {use: 'top'} -->
<!-- END mdmod -->

would produce:

### [pkg1](packages/pkg1)

testPackage

[![](https://img.shields.io/npm/v/pkg1.svg)](https://npmjs.com/package/pkg1)
[![npm: total downloads](https://flat.badgen.net/npm/dt/pkg1)](https://npmjs.com/package/pkg1)
![npm: license](https://flat.badgen.net/npm/license/pkg1)

```bash
npm install --save pkg1
# or
yarn add pkg1
```

GitHub Sponsors (mdmod-plugin-github-sponsors)

npm i -g mdmod-plugin-github-sponsors
mdmod README.md --define.owner uetchy

# Sponsors

<!-- START mdmod {use: 'github-sponsors'} -->
<!-- END mdmod -->

would produce:

# Sponsors

<!-- START mdmod {use: 'github-sponsors'} -->

[<img src="https://avatars.githubusercontent.com/u/6936373?u=4edd14e6636c45d10ac6a3eecb4b3ffa6cc2bf5c&v=4" width="35" />](https://github.com/Naturalclar) [<img src="https://avatars.githubusercontent.com/u/79023920?v=4" width="35" />](https://github.com/Lierin8oracle)

<!-- END mdmod -->

Usage Tips

Sync version text in README.md with the latest git tag

npx mdmod README.md --define.version $(git describe --tags --match 'v*' --abbrev=0)

README.md:

# Download

<!-- START mdmod {match: /v\d\.\d\.\d/g, replace: version} -->

```bash
curl -LO https://github.com/uetchy/mdmod/archive/v0.4.0.zip
unzip v0.4.0.zip
```

<!-- END mdmod -->

Automated workflow with husky and lint-staged

{
  "husky": {
    "pre-commit": "lint-staged"
  },
  "lint-staged": {
    "*.md": ["mdmod"]
  }
}

Showcase

List of awesome projects that use mdmod.

• Tencent/cloudbase-framework

Contributing

See CONTRIBUTING.md for more information.