Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mild-blue/htmldiff.js
https://github.com/mild-blue/htmldiff.js
Last synced: 12 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/mild-blue/htmldiff.js
- Owner: mild-blue
- License: mit
- Created: 2024-05-07T08:46:24.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-05-09T09:55:12.000Z (8 months ago)
- Last Synced: 2024-12-21T19:07:58.933Z (15 days ago)
- Language: JavaScript
- Size: 425 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# htmldiff.js
Diff and markup HTML with `` and `` tags.
## Origin
Quote from the original source of this fork:
*`htmldiff.js` is a JavaScript port of [https://github.com/myobie/htmldiff](https://github.com/myobie/htmldiff) by
[Keanu Lee](http://keanulee.com) at [Inkling](https://www.inkling.com/).*
**htmldiff.js** is based on [this fork](https://github.com/inkling/htmldiff.js) and adds a few things:
- Diffing of video, math, widget, iframe, img and svg tags.
- Ability to set atomic tags via the API.
- A command line interface.
- TypeScript support.
- Better documentation.
See also *Credits* below.
## Description
htmldiff takes two HTML snippets or files and marks the differences between them with
`` and `` tags. The diffing understands HTML so it doesn't do a pure text diff,
instead it will insert the appropriate tags for changed/added/deleted text nodes, single
tags or tag hierarchies.
The module can be used as module in Node.js, with RequireJS, or even just as a script tag.
## API
The module exports a single default function:
JavaScript:
````javascript
diff(before, after, className, dataPrefix, atomicTags);
````
TypeScript:
````javascript
function diff(before: string, after: string, className?: string | null, dataPrefix?: string | null, atomicTags?: string | null): string;
````
### Parameters
- `before` (string) is the original HTML text.
- `after` (string) is the HTML text after the changes have been applied.
The return value is a string with the diff result, marked by `` and `del` tags. The
function has three optional parameters. If an empty string or `null` is used for any
of these three parameters it will be ignored:
- `className` (string) className will be added as a class attribute on every inserted
`` and `` tag.
- `dataPrefix` (string) The data prefix to use for data attributes. The so called *operation
index data attribute* will be named `data-${dataPrefix-}operation-index`. If not used,
the default attribute name `data-operation-index` will be added on every inserted
`` and `` tag. The value of this attribute is an auto incremented counter.
- `atomicTags` (string) Comma separated list of tag names. The list has to be in the form
`tag1,tag2,...` e. g. `head,script,style`. An atomic tag is one whose child nodes should
not be compared - the entire tag should be treated as one token. This is useful for tags
where it does not make sense to insert `` and `` tags. If not used, the default
list will be used:
`iframe,object,math,svg,script,video,head,style,a,img`.
### Example
JavaScript:
```javascript
diff = require('node-htmldiff');
console.log(diff('
This is some text
', 'That is some more text
', 'myClass'));
```
TypeScript:
```javascript
import diff = require("node-htmldiff");
console.log(diff("
This is some text
", "That is some more text
", "myClass"));
```
Please note that `diff` is only an arbitrary name; since the module exports only one default
function you can use whatever name you like, e. g., `diffHTML`.
Result:
```html
ThisThat is some more text.
```
## Command line interface
```bash
htmldiff beforeFile afterFile diffedFile [-c className] [-p dataPrefix] [-t atomicTags]
```
Parameters:
- `beforeFile` An HTML input file in its original form.
- `afterFile` An HTML input file, based on `beforeFile` but with changes.
- `diffedFile` Name of the diffed HTML output file. All differences between
`beforeFile` and `afterFile` will be surrounded with `` and ``
tags. If diffedFile is `-` (minus) the result will be written with
`console.log()` to stdout.
Options:
`-c className`, `-p dataPrefix` and `-t atomicTags` are all optional. For a
description please see API documentation above.
## Development
After cloning the repository run `npm i` or `npm install` to install the necessary
dependencies. A run of `npm run make` creates the JavaScript output file.
`npm run lint` checks the TypeScript sources with TSLint. `npm test` runs all the
tests from the `test` directory. `npm run testsample` diffs the HTML sample files
from the directory `sample` and logs the result to the console.
The command line interface of htmldiff is developed in TypeScript so you have to run
`npm run make` once to create the JavaScript output file.
## Credits
This module wouldn't have been possible without code from the following projects/persons:
- Original project: [The Network Inc.](http://www.tninetwork.com), [Github](https://github.com/tnwinc/htmldiff.js)
- Massive improvements of the original code: [Inkling](https://www.inkling.com), [Github](https://github.com/inkling/htmldiff.js)
- Support of more tags: Ian White, [Github](https://github.com/ian97531)
## License
MIT © [idesis GmbH](https://www.idesis.de), Max-Keith-Straße 66 (E 11), D-45136 Essen
See the `LICENSE` file for details.