https://github.com/uetchy/mdmod
✂️🧬 Powerful & extensible Markdown fragment editor
https://github.com/uetchy/mdmod
cli markdown mdmod readme
Last synced: about 1 month ago
JSON representation
✂️🧬 Powerful & extensible Markdown fragment editor
- Host: GitHub
- URL: https://github.com/uetchy/mdmod
- Owner: uetchy
- License: apache-2.0
- Created: 2020-07-27T08:04:52.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-11-09T06:57:19.000Z (over 4 years ago)
- Last Synced: 2025-10-02T07:57:51.545Z (9 months ago)
- Topics: cli, markdown, mdmod, readme
- Language: TypeScript
- Homepage:
- Size: 310 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# mdmod
[![npm-version]][npm-url]
[![npm-downloads]][npm-url]
[](https://github.com/uetchy/mdmod/actions?query=test)
[npm-version]: https://badgen.net/npm/v/mdmod
[npm-downloads]: https://badgen.net/npm/dt/mdmod
[npm-url]: https://npmjs.org/package/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](#official-plugins) to extend its usage
## Install
```bash
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 `` and with a trailing ``, and then pass the option as an object, where `match` is `/v\d\.\d\.\d/g` and `replace` is `version`.
````md
```
curl https://path/to/releases/v0.4.0.tar.gz
tar -zxvf v0.4.0.tar.gz
```
````
Run `mdmod` with a variable `version` set `v6.0.0`:
```bash
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:
````md
```
curl https://path/to/releases/v6.0.0.tar.gz
tar -zxvf v6.0.0.tar.gz
```
````
## Configuration
### MdmodOption
```ts
{
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](CONTRIBUTING.md) for more information on how to write a plugin.
### Start of block
```
```
### End of block
```
```
### Environment variable
Instead of using `--define.=`, you can also define a variable with exporting environment variable `MDMOD_`. `` will be lowercased and added to the VM's constant dictionary.
## Official Plugins
### Table of Contents ([`mdmod-plugin-toc`](https://github.com/uetchy/mdmod-plugin-toc))
Generate a table of contents.
```bash
npm i -g mdmod-plugin-toc
mdmod README.md
```
```
```
would produce:
```md
- [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`](https://github.com/uetchy/mdmod-plugin-top))
Generate a list of monorepo packages (`/packages/*`).
```bash
npm i -g mdmod-plugin-top
mdmod README.md
```
```
```
would produce:
````md
### [pkg1](packages/pkg1)
testPackage
[](https://npmjs.com/package/pkg1)
[](https://npmjs.com/package/pkg1)
```bash
npm install --save pkg1
# or
yarn add pkg1
```
````
### GitHub Sponsors ([`mdmod-plugin-github-sponsors`](https://github.com/uetchy/mdmod-plugin-github-sponsors))
```bash
npm i -g mdmod-plugin-github-sponsors
mdmod README.md --define.owner uetchy
```
```
# Sponsors
```
would produce:
```md
# Sponsors
[
](https://github.com/Naturalclar) [
](https://github.com/Lierin8oracle)
```
## Usage Tips
### Sync version text in README.md with the latest `git tag`
```bash
npx mdmod README.md --define.version $(git describe --tags --match 'v*' --abbrev=0)
```
`README.md`:
````md
# Download
```bash
curl -LO https://github.com/uetchy/mdmod/archive/v0.4.0.zip
unzip v0.4.0.zip
```
````
### Automated workflow with `husky` and `lint-staged`
```json
{
"husky": {
"pre-commit": "lint-staged"
},
"lint-staged": {
"*.md": ["mdmod"]
}
}
```
## Showcase
List of awesome projects that use mdmod.
- [Tencent/cloudbase-framework](https://github.com/Tencent/cloudbase-framework)
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.