Skip to content
This repository was archived by the owner on Jul 15, 2019. It is now read-only.

Commit 4f3f134

Browse files
author
adon
committed
update README on tag balancing
1 parent 45dd4c0 commit 4f3f134

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

README.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,36 @@ var input = '...';
3232
var result = purifier.purify(input);
3333
```
3434

35+
## Advanced Usage
36+
37+
The following outlines the configuration that is secure by default. You should perform due dilligence to confirm your use cases are safe before disabling or altering the configurations.
38+
39+
```js
40+
// The default configuration
41+
new Purifier({
42+
whitelistTags: ['a', '...'],
43+
whitelistAttributes: ['href', '...'],
44+
enableCanonicalization: true,
45+
tagBalance: {
46+
enabled: true,
47+
stackSize: 100
48+
}
49+
});
50+
```
51+
52+
<!--
53+
#### whitelistTags
54+
55+
#### whitelistAttributes
56+
57+
#### enableCanonicalization
58+
-->
59+
60+
#### tagBalance
61+
The untrusted data must be self-contained. Therefore, it cannot close any tags prior to its inclusion, nor leave any of its own tags unclosed. An efficient and simple tag balancing algorithm is applied by default to enforce this goal only, and may not produce perfectly balanced output. You can implement your own tag balancing before invoking purify. But the default one should be still enabled, unless you're sure your algorithm can meet the self-contained requirement.
62+
63+
The ``stackSize`` is a limit on the maximum number of unclosed tags (or the max levels of nested tags). When an untrusted data attempts to open tags that are so nested to exceed the allowed limit, the algorithm will cease further processing the data but simply close all of those tags.
64+
3565
## Development
3666

3767
### How to build

0 commit comments

Comments
 (0)