1 # stringify-entities [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status]
3 Encode HTML character references and character entities.
6 * [x] Just the encoding part
7 * [x] Reliable: ``'`'`` characters are escaped to ensure no scripts
8 run in IE6-8. Additionally, only named entities recognised by HTML4
9 are encoded, meaning the infamous `'` (which people think is a
10 [virus][]) won’t show up
14 By default, all dangerous, non-ASCII, or non-printable ASCII characters
15 are encoded. A [subset][] of characters can be given to encode just
16 those characters. Alternatively, pass [`escapeOnly`][escapeonly] to
17 escape just the dangerous characters (`"`, `'`, `<`, `>`, `&`, `` ` ``).
18 By default, numeric entities are used. Pass [`useNamedReferences`][named]
19 to use named entities when possible, or [`useShortestReferences`][short]
20 to use them if that results in less bytes.
27 npm install stringify-entities
33 var stringify = require('stringify-entities')
35 stringify('alpha © bravo ≠ charlie 𝌆 delta')
36 // => 'alpha © bravo ≠ charlie 𝌆 delta'
38 stringify('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
39 // => 'alpha © bravo ≠ charlie 𝌆 delta'
44 ### `stringifyEntities(value[, options])`
46 Encode special characters in `value`.
50 ###### `options.escapeOnly`
52 Whether to only escape possibly dangerous characters (`boolean`,
53 default: `false`). Those characters are `"`, `'`, `<`, `>` `&`, and
56 ###### `options.subset`
58 Whether to only escape the given subset of characters (`Array.<string>`).
60 ###### `options.useNamedReferences`
62 Whether to use named entities where possible (`boolean?`, default:
65 ###### `options.useShortestReferences`
67 Whether to use named entities, where possible, if that results in less
68 bytes (`boolean?`, default: `false`). **Note**: `useNamedReferences`
69 can be omitted when using `useShortestReferences`.
71 ###### `options.omitOptionalSemicolons`
73 Whether to omit semi-colons when possible (`boolean?`, default: `false`).
74 **Note**: This creates parse errors: don’t use this except when building
77 Omitting semi-colons is possible for [certain][dangerous] [legacy][]
78 named references, and numeric entities, in some cases.
80 ###### `options.attribute`
82 Only needed when operating dangerously with `omitOptionalSemicolons: true`.
83 Create entities which don’t fail in attributes (`boolean?`, default:
88 * [`parse-entities`](https://github.com/wooorm/parse-entities)
89 — Parse HTML character references
90 * [`character-entities`](https://github.com/wooorm/character-entities)
91 — Info on character entities
92 * [`character-entities-html4`](https://github.com/wooorm/character-entities-html4)
93 — Info on HTML4 character entities
94 * [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
95 — Info on legacy character entities
96 * [`character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
97 — Info on invalid numeric character references
101 [MIT][license] © [Titus Wormer][author]
105 [build-badge]: https://img.shields.io/travis/wooorm/stringify-entities.svg
107 [build-status]: https://travis-ci.org/wooorm/stringify-entities
109 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/stringify-entities.svg
111 [coverage-status]: https://codecov.io/github/wooorm/stringify-entities
115 [author]: http://wooorm.com
117 [npm]: https://docs.npmjs.com/cli/install
119 [virus]: http://www.telegraph.co.uk/technology/advice/10516839/Why-do-some-apostrophes-get-replaced-with-andapos.html
121 [dangerous]: dangerous.json
123 [legacy]: https://github.com/wooorm/character-entities-legacy
125 [subset]: #optionssubset
127 [escapeonly]: #optionsescapeonly
129 [named]: #optionsusenamedreferences
131 [short]: #optionsuseshortestreferences