@ -12,9 +12,9 @@ To test local changes to Readability.js, you can use the [automated tests](#test
Please make sure to run [eslint](http://eslint.org/) against any proposed changes when creating a pull request.
## Usage
## Usage on the web.
To parse a document, you must create a new `Readability` object from a document object, and then call `parse()`. Here's an example:
To parse a document, you must create a new `Readability` object from a DOM document object, and then call `parse()`. Here's an example:
```javascript
var article = new Readability(document).parse();
@ -29,22 +29,41 @@ This `article` object will contain the following properties:
* `byline`: author metadata
* `dir`: content direction
If you're using Readability on the web, you will likely be able to use a `document` reference from elsewhere (e.g. fetched via XMLHttpRequest, in a same-origin `<iframe>` you have access to, etc.).
Otherwise, you would need to construct such an object using a DOM parser such as [jsdom](https://github.com/tmpvar/jsdom). While this repository contains a parser of its own (`JSDOMParser`), that is restricted to reading XML-compatible markup and therefore we do not recommend it for general use.
If you're using `jsdom` to create a DOM object, you should ensure that the page doesn't run (page) scripts (avoid fetching remote resources etc.) as well as passing it the page's URI as the `url` property of the `options` object you pass the `JSDOM` constructor.
If you're using Readability on the web, you will likely be able to use a `document` reference
from elsewhere (e.g. fetched via XMLHttpRequest, in a same-origin `<iframe>` you have access to, etc.).
### Optional
Readability's `parse()` works by modifying the DOM. This removes some elements in the web page. You could avoid this by passing the clone of the `document` object while creating a `Readability` object.
Readability's `parse()` works by modifying the DOM. This removes some elements in the web page.
You could avoid this by passing the clone of the `document` object while creating a `Readability` object.
```
var documentClone = document.cloneNode(true);
var article = new Readability(documentClone).parse();
```
## Usage from node.js
In node.js, you won't generally have a DOM document object. To obtain one, you can use external
libraries like [jsdom](https://github.com/tmpvar/jsdom). While this repository contains a parser of
its own (`JSDOMParser`), that is restricted to reading XML-compatible markup and therefore we do
not recommend it for general use.
If you're using `jsdom` to create a DOM object, you should ensure that the page doesn't run (page)
scripts (avoid fetching remote resources etc.) as well as passing it the page's URI as the `url`
property of the `options` object you pass the `JSDOM` constructor.
### Example:
```
var JSDOM = require('jsdom').JSDOM;
var doc = new JSDOM("<body>Here's a bunch of text</body>", {