https://github.com/vweevers/section-remark
Specialized Remark that only transforms (or adds) one Markdown section.
https://github.com/vweevers/section-remark
markdown remark unified
Last synced: about 1 month ago
JSON representation
Specialized Remark that only transforms (or adds) one Markdown section.
- Host: GitHub
- URL: https://github.com/vweevers/section-remark
- Owner: vweevers
- License: mit
- Created: 2018-05-05T21:19:22.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-12-11T17:48:11.000Z (over 5 years ago)
- Last Synced: 2026-03-14T18:00:17.885Z (3 months ago)
- Topics: markdown, remark, unified
- Language: JavaScript
- Homepage:
- Size: 3.91 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# section-remark
> Specialized Remark that only transforms (or adds) one Markdown section.
[](https://www.npmjs.org/package/section-remark)
[](https://www.npmjs.org/package/section-remark)
[](http://travis-ci.org/vweevers/section-remark)
[](https://david-dm.org/vweevers/section-remark)
[](https://standardjs.com)
## Background
Remark works on an *abstract* syntax tree, which means some information is lost. Not semantics, but formatting, style, whitespace, i.e. your personal preferences. What's more, converting the AST back to markdown will *add* formatting and possibly result in unwanted diff noise.
Meant for sections of generated markdown, `section-remark` runs on a subset of the tree (a range of nodes starting with a certain header), stringifies it and concatenates the result with the rest of your markdown. Other sections are left alone.
Returns a `unified` processor, so like the regular `remark`, you can use [any plugin](https://github.com/remarkjs/remark/blob/master/doc/plugins.md).
## Usage
As an example, let's generate a Contributors section:
```js
const remark = require('section-remark')
const contributors = require('remark-contributors')
const report = require('vfile-reporter')
const vfile = require('to-vfile')
remark('Contributors')
.use(contributors)
.process(vfile.readSync('README.md'), function (err, file) {
console.error(report(err || file))
vfile.writeSync(file)
})
```
This does nothing if the contributors section doesn't already exist. To either replace it or add it to the end of the document, do:
```js
remark('Contributors', { add: true })
```
To replace it or add it after another section:
```js
remark('Contributors', { after: 'API' })
```
We can use any `test` supported by [`mdast-util-heading-range`](https://github.com/syntax-tree/mdast-util-heading-range). If we want to generate an API section and insert it after a usage or example section:
```js
remark('API', { after: /^(usage|example)$/i })
```
Same goes for the first argument. If we want to replace or add a TOC:
```js
remark(/^(table of )?contents$/i, { add: true })
```
This will throw an error though if the TOC doesn't exist, because `section-remark` can't convert the regular expression to a title. We should define the `text` option, so that a "Contents" header will be renamed to "Table of Contents". And let's insert the TOC before another section.
```js
remark(/^(table of )?contents$/i, {
text: 'Table of Contents',
before: /^usage|example$/i
})
```
Lastly, if you use `before` or `after` and the section does not already exist, its header will inherit the depth of its `before` or `after` sibling.
## API
### `sectionRemark(test[, options])`
Returns a `unified` processor that transforms a section starting with a header which matches `test` (see [`mdast-util-heading-range`](https://github.com/syntax-tree/mdast-util-heading-range)). Options:
- `add`: add to end of document, if not found
- `before`: insert before section, if not found
- `after`: insert after section, if not found
- `text`: text content of header, defaults to `test` if a string
- `depth`: header depth, starting at 1, defaults to sibling depth or 2.
## Install
With [npm](https://npmjs.org) do:
```
npm install section-remark
```
## License
[MIT](http://opensource.org/licenses/MIT) © Vincent Weevers