8000 Use ESM in guides, recipes · rlew631/unifiedjs.github.io@4a010be · GitHub
[go: up one dir, main page]
Skip to content

Commit 4a010be

Browse files
wooormwooorm
committed
Use ESM in guides, recipes
1 parent 6449feb commit 4a010be

File tree

9 files changed

+490
-425
lines changed

9 files changed

+490
-425
lines changed

‎doc/learn/create-a-plugin.md

Lines changed: 127 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -65,25 +65,59 @@ In the next step we’ll write the code to use our plugin.
6565

6666
### Setting up
6767

68+
Let’s set up a project.
69+
Create a folder, `example`, enter it, and initialize a new project:
70+
71+
```sh
72+
mkdir example
73+
cd example
74+
npm init -y
75+
```
76+
77+
Then make sure the project is a module, so that `import` and `export` work,
78+
by changing `package.json`:
79+
80+
```diff
81+
--- a/package.json
82+
+++ b/package.json
83+
@@ -2,6 +2,7 @@
84+
"name": "example",
85+
"version": "1.0.0",
86+
"description": "",
87+
+ "type": "module",
88+
"main": "index.js",
89+
"scripts": {
90+
"test": "echo \"Error: no test specified\" && exit 1"
91+
```
92+
93+
Make sure `example.md` exists with:
94+
95+
```markdown
96+
One sentence. Two sentences.
97+
98+
One sentence. Two sentences.
99+
```
100+
68101
Now, let’s create an `example.js` file that will process our text file and
69102
report any found problems.
70103

71104
```javascript
72-
var fs = require('fs')
73-
var retext = require('retext')
74-
var report = require('vfile-reporter')
75-
var spacing = require('.')
105+
import fs from 'fs'
106+
import {retext} from 'retext'
107+
import {reporter} from 'vfile-reporter'
108+
import retextSentenceSpacing from './index.js'
76109

77-
var doc = fs.readFileSync('example.md')
110+
const buffer = fs.readFileSync('example.md')
78111

79112
retext()
80-
.use(spacing)
81-
.process(doc, function(err, file) {
82-
console.error(report(err || file))
113+
.use(retextSentenceSpacing)
114+
.process(buffer)
115+
.then((file) => {
116+
console.error(reporter(file))
83117
})
84118
```
85119

86-
> Don’t forget to `npm install` dependencies!
120+
> Don’t forget to `npm install` dependencies (`retext`, `vfile-reporter`)!
87121
88122
If you read the guide on [using unified][use], you’ll see some familiar
89123
statements.
@@ -104,17 +138,13 @@ We’ll do that in the next section.
104138

105139
### Plugin
106140

107-
As we read in Plugin Basics, we’ll need an attacher, and for our case also a
141+
As we read in Plugin Basics, we’ll need a plugin, and for our case also a
108142
transformer.
109143
Let’s create them in our plugin file `index.js`:
110144

111145
```javascript
112-
module.exports = attacher
113-
114-
function attacher() {
115-
return transformer
116-
117-
function transformer(tree, file) {
146+
export default function retextSentenceSpacing() {
147+
return (tree, file) => {
118148
}
119149
}
120150
```
@@ -125,21 +155,18 @@ We can use a utility to help us to recursively walk our tree, namely
125155
Let’s add that.
126156

127157
```diff
128-
+var visit = require('unist-util-visit')
129-
+
130-
module.exports = attacher
131-
132-
function attacher() {
133-
return transformer
134-
135-
function transformer(tree, file) {
136-
+ visit(tree, 'ParagraphNode', visitor)
158+
--- a/index.js
159+
+++ b/index.js
160+
@@ -1,4 +1,9 @@
161+
+import {visit} from 'unist-util-visit'
137162
+
138-
+ function visitor(node) {
163+
export default function retextSentenceSpacing() {
164+
return (tree, file) => {
165+
+ visit(tree, 'ParagraphNode', (node) => {
139166
+ console.log(node)
140-
+ }
141-
}
142-
}
167+
+ })
168+
}
169+
}
143170
```
144171

145172
> Don’t forget to `npm install` the utility!
@@ -148,17 +175,34 @@ If we now run our example with Node.js, as follows, we’ll see that visitor is
148175
invoked with both paragraphs in our example:
149176

150177
```sh
151-
$ node example.js
152-
{ type: 'ParagraphNode',
153-
children:
154-
[ { type: 'SentenceNode', children: [Object] },
155-
{ type: 'WhiteSpaceNode', value: ' ' },
156-
{ type: 'SentenceNode', children: [Object] } ] }
157-
{ type: 'ParagraphNode',
158-
children:
159-
[ { type: 'SentenceNode', children: [Object] },
160-
{ type: 'WhiteSpaceNode', value: ' ' },
161-
{ type: 'SentenceNode', children: [Object] } ] }
178+
node example.js
179+
```
180+
181+
```txt
182+
{
183+
type: 'ParagraphNode',
184+
children: [
185+
{ type: 'SentenceNode', children: [Array], position: [Object] },
186+
{ type: 'WhiteSpaceNode', value: ' ', position: [Position] },
187+
{ type: 'SentenceNode', children: [Array], position: [Object] }
188+
],
189+
position: {
190+
start: { line: 1, column: 1, offset: 0 },
191+
end: { line: 1, column: 29, offset: 28 }
192+
}
193+
}
194+
{
195+
type: 'ParagraphNode',
196+
children: [
197+
{ type: 'SentenceNode', children: [Array], position: [Object] },
198+
{ type: 'WhiteSpaceNode', value: ' ', position: [Position] },
199+
{ type: 'SentenceNode', children: [Array], position: [Object] }
200+
],
201+
position: {
202+
start: { line: 3, column: 1, offset: 30 },
203+
end: { line: 3, column: 30, offset: 59 }
204+
}
205+
}
162206
no issues found
163207
```
164208

@@ -173,22 +217,19 @@ Only checking white-space between sentences.
173217
We use a small utility for checking node types: [`unist-util-is`][is].
174218

175219
```diff
176-
var visit = require('unist-util-visit')
177-
+var is = require('unist-util-is')
178-
179-
module.exports = attacher
180-
181-
function attacher() {
182-
return transformer
183-
184-
function transformer(tree, file) {
185-
visit(tree, 'ParagraphNode', visitor)
186-
187-
function visitor(node) {
220+
--- a/index.js
221+
+++ b/index.js
222+
@@ -1,9 +1,20 @@
223+
import {visit} from 'unist-util-visit'
224+
+import {is} from 'unist-util-is'
225+
226+
export default function retextSentenceSpacing() {
227+
return (tree, file) => {
228+
visit(tree, 'ParagraphNode', (node) => {
188229
- console.log(node)
189-
+ var children = node.children
230+
+ const children = node.children
190231
+
191-
+ children.forEach(function(child, index) {
232+
+ children.forEach((child, index) => {
192233
+ if (
193234
+ is(children[index - 1], 'SentenceNode') &&
194235
+ is(child, 'WhiteSpaceNode') &&
@@ -197,9 +238,9 @@ function attacher() {
197238
+ console.log(child)
198239
+ }
199240
+ })
200-
}
201-
}
202-
}
241+
})
242+
}
243+
}
203244
```
204245

205246
> Don’t forget to `npm install` the utility!
@@ -208,9 +249,26 @@ If we now run our example with Node, as follows, we’ll see that only white-spa
208249
between sentences is logged.
209250

210251
```sh
211-
$ node example.js
212-
{ type: 'WhiteSpaceNode', value: ' ' }
213-
{ type: 'WhiteSpaceNode', value: ' ' }
252+
node example.js
253+
```
254+
255+
```txt
256+
{
257+
type: 'WhiteSpaceNode',
258+
value: ' ',
259+
position: Position {
260+
start: { line: 1, column: 14, offset: 13 },
261+
end: { line: 1, column: 15, offset: 14 }
262+
}
263+
}
264+
{
265+
type: 'WhiteSpaceNode',
266+
value: ' ',
267+
position: Position {
268+
start: { line: 3, column: 14, offset: 43 },
269+
end: { line: 3, column: 16, offset: 45 }
270+
}
271+
}
214272
no issues found
215273
```
216274

@@ -219,38 +277,22 @@ characters than needed.
219277
We can use [`file.message()`][message] to associate a message with the file.
220278

221279
```diff
222-
var visit = require('unist-util-visit')
223-
var is = require('unist-util-is')
224-
225-
module.exports = attacher
226-
227-
function attacher() {
228-
return transformer
229-
230-
function transformer(tree, file) {
231-
visit(tree, 'ParagraphNode', visitor)
232-
233-
function visitor(node) {
234-
var children = node.children
235-
236-
children.forEach(function(child, index) {
237-
if (
238-
is(children[index - 1], 'SentenceNode') &&
239-
is(child, 'WhiteSpaceNode') &&
240-
is(children[index + 1], 'SentenceNode')
241-
) {
280+
--- a/index.js
281+
+++ b/index.js
282+
@@ -12,7 +12,12 @@ export default function retextSentenceSpacing() {
283+
is(child, 'WhiteSpaceNode') &&
284+
is(children[index + 1], 'SentenceNode')
285+
) {
242286
- console.log(child)
243287
+ if (child.value.length !== 1) {
244288
+ file.message(
245289
+ 'Expected 1 space between sentences, not ' + child.value.length,
246290
+ child
247291
+ )
248292
+ }
249-
}
250-
})
251-
}
252-
}
253-
}
293+
}
294+
})
295+
})
254296
```
255297

256298
If we now run our example one final time, we’ll see a message for our problem!

0 commit comments

Comments
 (0)
0