Skip to content

Commit 98c9b8a

Browse files
eGavreGavr
committed
Merge pull request #125 from bem/update-docs
Update docs
2 parents afd1db5 + 3578cf9 commit 98c9b8a

3 files changed

Lines changed: 124 additions & 68 deletions

File tree

‎README.md‎

Lines changed: 62 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,36 @@
22

33
Compares two HTML.
44

5+
<!-- TOC -->
6+
* [The comparison algorithm](#the-comparison-algorithm)
7+
* [Install](#install)
8+
* [API](#api)
9+
* [HtmlDiffer](#htmldiffer)
10+
* [Options](#options)
11+
* [ignoreAttributes: [Array]](#ignoreattributes-array)
12+
* [compareAttributesAsJSON: [Array]](#compareattributesasjson-array)
13+
* [ignoreWhitespaces: Boolean](#ignorewhitespaces-boolean)
14+
* [ignoreComments: Boolean](#ignorecomments-boolean)
15+
* [ignoreEndTags: Boolean](#ignoreendtags-boolean)
16+
* [ignoreDuplicateAttributes: Boolean](#ignoreduplicateattributes-boolean)
17+
* [Presets](#presets)
18+
* [Usage](#usage)
19+
* [Methods](#methods)
20+
* [htmlDiffer.diffHtml](#htmldifferdiffhtml)
21+
* [htmlDiffer.isEqual](#htmldifferisequal)
22+
* [Logger](#logger)
23+
* [Methods](#methods-1)
24+
* [logger.getDiffText](#loggergetdifftext)
25+
* [logger.logDiffText](#loggerlogdifftext)
26+
* [Example](#example)
27+
* [Usage as a program](#usage-as-a-program)
28+
* [Example](#example-1)
29+
* [Configuration file](#configuration-file)
30+
* [Masks](#masks)
31+
* [Syntax](#syntax)
32+
33+
<!-- TOC END -->
34+
535
## The comparison algorithm
636

737
**html-differ** compares HTML using the following criteria:
@@ -54,12 +84,12 @@ For example, the following two code samples will be considered to be equivalent:
5484
```
5585

5686
**CAUTION!**<br>
57-
**html-differ** does not check the validity of HTML, but compares them using the above shown criteria and specified options (see the list of possible options in the [API](https://github.com/bem/html-differ#api)).
87+
**html-differ** does not check the validity of HTML, but compares them using the above shown criteria and specified options (see the list of possible [options](https://github.com/bem/html-differ/tree/master#options)).
5888

5989
## Install
6090

6191
```bash
62-
$ npm install html-differ -g
92+
$ npm install html-differ
6393
```
6494

6595
## API
@@ -71,9 +101,11 @@ var HtmlDiffer = require('html-differ').HtmlDiffer,
71101
htmlDiffer = new HtmlDiffer(options);
72102
```
73103

74-
where `options` is an object:
104+
where `options` is an object.
105+
106+
####Options####
75107

76-
* **ignoreAttributes: [ Array ]**
108+
#####ignoreAttributes: [Array]#####
77109

78110
Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`).
79111

@@ -90,7 +122,7 @@ The following two code samples will be considered to be equivalent:
90122
<input id="sfsdfksdf">
91123
```
92124

93-
* **compareAttributesAsJSON: [ Array ]**
125+
#####compareAttributesAsJSON: [Array]#####
94126

95127
Sets what kind of respective attributes' content will be compared as JSON objects, but not as strings (default: `[]`).<br>
96128
In cases when the value of the attribute is an invalid JSON or can not be wrapped into a function, it will be compared as `undefined`.
@@ -118,7 +150,7 @@ The following two code samples will be considered to be equivalent:
118150
The first element of the array could be written in a short form as string:<br>
119151
`['data', { name: 'onclick', isFunction: true }]`.
120152

121-
* **ignoreWhitespaces: Boolean**
153+
#####ignoreWhitespaces: Boolean#####
122154

123155
Makes **html-differ** ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`).
124156

@@ -150,7 +182,7 @@ The following two code samples will be considered to be equivalent:
150182

151183
```
152184

153-
* **ignoreComments: Boolean**
185+
#####ignoreComments: Boolean#####
154186

155187
Makes **html-differ** ignore HTML comments during the comparison (default: `true`).
156188

@@ -199,7 +231,7 @@ Text
199231
</html>
200232
```
201233

202-
* **ignoreEndTags: Boolean**
234+
#####ignoreEndTags: Boolean#####
203235

204236
Makes **html-differ** ignore end tags during the comparison (default: `false`).
205237

@@ -214,7 +246,7 @@ The following two code samples will be considered to be equivalent:
214246
<span>Text</spane>
215247
```
216248

217-
* **ignoreDuplicateAttributes: Boolean**
249+
#####ignoreDuplicateAttributes: Boolean#####
218250

219251
Makes **html-differ** ignore tags' duplicate attributes during the comparison.<br>
220252
From the list of the same tag's attributes, the attribute which goes the first will be taken for comparison, others will be ignored (default: `false`).
@@ -230,40 +262,35 @@ For example, the following two code samples will be considered to be equivalent:
230262
<span id="blah">Text</span>
231263
```
232264

233-
**BEM preset**
265+
####Presets####
266+
267+
* [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - sets predefined options for [BEM](http://bem.info/).
268+
234269

235-
You can set predefined options for [BEM](http://bem.info/) using the _preset_:
270+
#####Usage#####
271+
272+
Passing of a preset via the constructor:
236273

237274
```js
238275
var HtmlDiffer = require('html-differ').HtmlDiffer,
239276
htmlDiffer = new HtmlDiffer('bem');
240277
```
241278

242-
The options will be predefined:
279+
Redefinition of a preset via the constructor:
243280

244281
```js
245-
{
246-
ignoreAttributes: ['id', 'for', 'aria-labelledby', 'aria-describedby'],
247-
compareAttributesAsJSON: [
248-
'data-bem',
249-
{ name: 'onclick', isFunction: true },
250-
{ name: 'ondblclick', isFunction: true }
251-
],
252-
ignoreWhitespaces: true,
253-
ignoreComments: true,
254-
ignoreEndTags: false,
255-
ignoreDuplicateAttributes: false
256-
}
282+
var HtmlDiffer = require('html-differ').HtmlDiffer,
283+
htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });
257284
```
258285

259286
####Methods####
260287

261-
**htmlDiffer.diffHtml**<br>
288+
#####htmlDiffer.diffHtml#####
262289
**@param** *{String}* - the 1-st HTML code<br>
263290
**@param** *{String}* - the 2-nd HTML code<br>
264291
**@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between HTML
265292

266-
**htmlDiffer.isEqual**<br>
293+
#####htmlDiffer.isEqual#####
267294
**@param** *{String}* - the 1-st HTML code<br>
268295
**@param** *{String}* - the 2-nd HTML code<br>
269296
**@returns** *{Boolean}*
@@ -277,16 +304,16 @@ var logger = require('html-differ/lib/logger');
277304

278305
####Methods####
279306

280-
**logger.getDiffText**<br>
281-
**@param** *{Array of objects}* - the result of the work of the method **htmlDiffer.diffHtml**<br>
307+
#####logger.getDiffText#####
308+
**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
282309
**@param** *{Object}* - options:<br>
283310

284311
* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).
285312

286313
**@returns** *{String}*
287314

288-
**logger.logDiffText**<br>
289-
**@param** *{Array of objects}* - the result of the work of the method **htmlDiffer.diffHtml**<br>
315+
#####logger.logDiffText#####
316+
**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)<br>
290317
**@param** *{Object}* - options:<br>
291318

292319
* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).
@@ -336,8 +363,9 @@ Usage:
336363
Options:
337364
-h, --help : Help
338365
-v, --version : Shows the version number
339-
--config=CONFIG : Path to configuration JSON file
340-
--bem : Uses predefined options for BEM
366+
--config=CONFIG : Path to a configuration JSON file
367+
--bem : Uses predefined options for BEM (deprecated)
368+
-p PRESET, --preset=PRESET : Name of a preset
341369
--chars-around-diff=CHARSAROUNDDIFF : The number of characters around the diff (default: 40)
342370

343371
Arguments:
@@ -352,12 +380,12 @@ $ html-differ path/to/html1 path/to/html2
352380

353381
$ html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/to/html2
354382

355-
$ html-differ --bem path/to/html1 path/to/html2
383+
$ html-differ --preset=bem path/to/html1 path/to/html2
356384
```
357385

358386
###Configuration file##
359387

360-
Study the following `config.json` file:
388+
Study the following file `config.json`:
361389

362390
```js
363391
{

0 commit comments

Comments
 (0)