Skip to content

Commit 7252bb7

Browse files
wooormwooorm
committed
Update readme.md 
1 parent 78a0c9c commit 7252bb7

File tree

1 file changed

+58
-91
lines changed

1 file changed

+58
-91
lines changed

‎readme.md‎

Lines changed: 58 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,20 @@
1-
# mdast-zone [![Build Status][travis-badge]][travis] [![Coverage Status][coverage-badge]][coverage]
1+
# mdast-zone [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status] [![Chat][chat-badge]][chat]
22

3-
[**mdast**][mdast] utility to treat HTML comments as ranges or markers.
3+
<!--lint disable list-item-spacing heading-increment no-duplicate-headings-->
4+
5+
[**MDAST**][mdast] utility to treat HTML comments as ranges or markers.
46
Useful as a base for remark plugins.
57

68
## Installation
79

8-
[npm][npm-install]:
10+
[npm][]:
911

1012
```bash
1113
npm install mdast-zone
1214
```
1315

14-
**mdast-zone** is also available for [duo][], and as an AMD, CommonJS,
15-
and globals module, [uncompressed and compressed][releases].
16-
17-
## Table of Contents
18-
19-
* [Usage](#usage)
20-
21-
* [API](#api)
22-
23-
* [zone(options)](#zoneoptions)
24-
25-
* [Marker](#marker)
26-
* [function onparse(marker)](#function-onparsemarker)
27-
* [function onstringify(marker)](#function-onstringifymarker)
28-
* [function onrun(start, nodes, end, scope)](#function-onrunstart-nodes-end-scope)
29-
30-
* [License](#license)
16+
**mdast-zone** is also available as an AMD, CommonJS, and
17+
globals module, [uncompressed and compressed][releases].
3118

3219
## Usage
3320

@@ -101,114 +88,94 @@ The first is exposed by this plugin in the form of an HTML comment which
10188
sort-of looks like a self-closing, custom tag. The second by placing starting
10289
and ending tags, as siblings, in a parent.
10390

104-
**Parameters**:
105-
106-
* `options` (`Object`):
107-
108-
* `name` (`string`) — Type to look for;
109-
110-
* `onparse` ([`Function`](#function-onparsemarker), optional)
111-
— Callback invoked when a marker is found during parsing;
91+
###### `options`
11292

113-
* `onstringify` ([`Function`](#function-onstringifymarker), optional)
114-
— Callback invoked when a marker is found during stringification;
93+
* `name` (`string`) — Type to look for;
94+
* `onparse` ([`Function`][onparse], optional)
95+
— Callback invoked when a marker is found during parsing;
96+
* `onstringify` ([`Function`][onstringify], optional)
97+
— Callback invoked when a marker is found during stringification;
98+
* `onrun` ([Function][onrun], optional)
99+
— Callback invoked when a range is found during transformation.
115100

116-
* `onrun` ([Function](#function-onrunstart-nodes-end-scope), optional)
117-
— Callback invoked when a range is found during transformation.
101+
###### Returns
118102

119-
**Returns**: `Function` — Should be passed to [`remark.use()`](https://github.com/wooorm/remark#remarkuseplugin-options).
120-
121-
#### `Marker`
122-
123-
**Example**
124-
125-
```markdown
126-
<!--foo bar="baz" qux-->
127-
```
128-
129-
Yields:
130-
131-
```json
132-
{
133-
"type": "marker",
134-
"attributes": "bar=\"baz\" qux",
135-
"parameters": {
136-
"bar": "baz",
137-
"qux": true
138-
},
139-
"node": {
140-
"type": "html",
141-
"value": "<!--foo bar=\"baz\" qux-->"
142-
}
143-
}
144-
```
145-
146-
**Fields**
147-
148-
* `type` (`string`) — Either `"marker"`, `"start"`, or `"end"`;
149-
* `attributes` (`string`) — Raw, unparsed value;
150-
* `parameters` (`Object.<string, *>`) — Parsed attributes;
151-
* `node` ([`Node`][mdast-node]) — Original HTML node.
103+
`Function`, which should be passed to [`remark.use()`][use].
152104

153105
#### `function onparse(marker)`
154106

155107
#### `function onstringify(marker)`
156108

157-
**Parameters**
158-
159-
* `marker` ([`Marker`](#marker)) — Marker.
160-
161109
When passing `name: "foo"` and `onparse: console.log.bind(console)` to
162-
`zone()`, comments in the form of `<!--foo bar="baz" qux-->` are detected and
163-
`onparse` is invoked:
110+
`zone()`, comments in the form of `<!--foo bar="baz" qux-->` are detected
111+
and `onparse` is invoked during the parsing phase.
164112

165113
An `onstringify` method could (instead, or both) be passed to `zone()`,
166-
which would be invoked with the same `marker` but during the stringification
167-
phase.
114+
which would be invoked with the same `marker` but during the
115+
stringification phase.
168116

169-
#### function onrun(start, nodes, end, scope)
117+
###### Parameters
170118

171-
**Parameters**
119+
* `marker` ([`Marker`][marker]).
172120

173-
* `start` ([`Marker`](#marker)) — Start of range;
121+
#### `function onrun(start, nodes, end, scope)`
174122

175-
* `nodes` (`Array.<Node>`) — Nodes between `start` and `end`;
123+
Invoked during the transformation phase with markers which determine
124+
a range: two markers, the first `start` and the last `end`, and the
125+
content inside.
176126

177-
* `end` ([`Marker`](#marker)) — End of range.
127+
###### Parameters
178128

129+
* `start` ([`Marker`][marker]) — Start of range;
130+
* `nodes` (`Array.<Node>`) — Nodes between `start` and `end`;
131+
* `end` ([`Marker`][marker]) — End of range.
179132
* `scope` (`Object`):
180133

181-
* `parent` ([`Node`][mdast-node]) — Parent of the range;
134+
* `parent` ([`Node`][node]) — Parent of the range;
182135
* `start` (`number`) — Index of `start` in `parent`;
183136
* `end` (`number`) — Index of `end` in `parent`.
184137

185-
**Returns**: `Array.<Node>?` — Zero or more nodes to replace the range
186-
(including `start` and `end`s HTML comments) with.
138+
###### Returns
139+
140+
`Array.<Node>?` — Zero or more nodes to replace the range (including
141+
`start` and `end`s markers) with.
187142

188143
## License
189144

190-
[MIT][license] © [Titus Wormer][home]
145+
[MIT][license] © [Titus Wormer][author]
191146

192147
<!-- Definitions -->
193148

194-
[travis-badge]: https://img.shields.io/travis/wooorm/mdast-zone.svg
149+
[build-badge]: https://img.shields.io/travis/wooorm/mdast-zone.svg
195150

196-
[travis]: https://travis-ci.org/wooorm/mdast-zone
151+
[build-status]: https://travis-ci.org/wooorm/mdast-zone
197152

198153
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/mdast-zone.svg
199154

200-
[coverage]: https://codecov.io/github/wooorm/mdast-zone
155+
[coverage-status]: https://codecov.io/github/wooorm/mdast-zone
156+
157+
[chat-badge]: https://img.shields.io/gitter/room/wooorm/remark.svg
158+
159+
[chat]: https://gitter.im/wooorm/remark
160+
161+
[releases]: https://github.com/wooorm/mdast-zone/releases
162+
163+
[license]: LICENSE
164+
165+
[author]: http://wooorm.com
166+
167+
[npm]: https://docs.npmjs.com/cli/install
201168

202169
[mdast]: https://github.com/wooorm/mdast
203170

204-
[mdast-node]: https://github.com/wooorm/mdast#node
171+
[node]: https://github.com/wooorm/mdast#node
205172

206-
[npm-install]: https://docs.npmjs.com/cli/install
173+
[onparse]: #function-onparsemarker
207174

208-
[duo]: http://duojs.org/#getting-started
175+
[onstringify]: #function-onstringifymarker
209176

210-
[releases]: https://github.com/wooorm/mdast-zone/releases
177+
[onrun]: #function-onrunstart-nodes-end-scope
211178

212-
[license]: LICENSE
179+
[use]: https://github.com/wooorm/unified#processoruseplugin-options
213180

214-
[home]: http://wooorm.com
181+
[marker]: https://github.com/wooorm/mdast-comment-marker#marker

0 commit comments

Comments
 (0)