Skip to content

Commit 9ee63a1

Browse files
mdevilsmdevils
committed
docs: improve README
1 parent 6f91915 commit 9ee63a1

File tree

1 file changed

+86
-93
lines changed

1 file changed

+86
-93
lines changed

‎README.md

Lines changed: 86 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,145 @@
1-
html-entities
2-
=============
1+
# html-entities
32

4-
Fast and lightweight HTML entities library supporting all HTML standards.
3+
[![npm version](https://img.shields.io/npm/v/html-entities.svg)](https://www.npmjs.com/package/html-entities)
4+
[![License](https://img.shields.io/npm/l/html-entities.svg)](https://github.com/mdevils/html-entities/blob/main/LICENSE)
5+
[![Types](https://img.shields.io/npm/types/html-entities.svg)](https://www.npmjs.com/package/html-entities)
6+
[![Bundle size](https://img.shields.io/bundlephobia/minzip/html-entities)](https://bundlephobia.com/package/html-entities)
57

6-
Comes with both TypeScript and Flow types.
8+
Fast and lightweight HTML entities library for all HTML standards (HTML5, HTML4, XML).
79

8-
* [Installation](#installation)
9-
* [Usage](#usage)
10-
* [encode(text, options)](#encodetext-options)
11-
* [decode(text, options)](#decodetext-options)
12-
* [decodeEntity(text, options)](#decodeentitytext-options)
13-
* [Package Size comparison](#package-size-comparison)
14-
* [Performance comparison](#performance-comparison)
10+
## Features
1511

16-
Installation
17-
------------
12+
- 🚀 **Fast performance** - optimized for speed (see [benchmarks](#performance-comparison))
13+
- 📦 **Lightweight** - small package size (132 kB, see [comparison](#package-size-comparison))
14+
- 🔄 **Standards compliant** - supports HTML5, HTML4, and XML entities
15+
- 📄 **Type safe** - includes TypeScript and Flow types
16+
- 🔌 **Dual ESM/CJS support** - works with both module systems
17+
18+
## Installation
1819

1920
```bash
20-
$ npm install html-entities
21+
# NPM
22+
npm install html-entities
23+
24+
# Yarn
25+
yarn add html-entities
26+
27+
# pnpm
28+
pnpm add html-entities
2129
```
2230

23-
Usage
24-
-----
31+
## Usage
2532

2633
### encode(text, options)
2734

28-
Encodes text replacing HTML special characters (`<>&"'`) and/or other character ranges depending on `mode` option value.
35+
Encodes text by replacing HTML special characters (`<>&"'`) and/or other character ranges depending on `mode` option.
2936

3037
```js
31-
import {encode} from 'html-entities';
38+
import { encode } from 'html-entities';
3239

40+
// Basic usage (defaults to HTML5 special chars only)
3341
encode('< > " \' & © ∆');
3442
// -> '&lt; &gt; &quot; &apos; &amp; © ∆'
3543

36-
encode('< ©', {mode: 'nonAsciiPrintable'});
44+
// Encode non-ASCII printable characters
45+
encode('< ©', { mode: 'nonAsciiPrintable' });
3746
// -> '&lt; &copy;'
3847

39-
encode('< ©', {mode: 'nonAsciiPrintable', level: 'xml'});
48+
// Specify encoding level (XML) and mode
49+
encode('< ©', { mode: 'nonAsciiPrintable', level: 'xml' });
4050
// -> '&lt; &#169;'
4151

42-
encode('< > " \' & ©', {mode: 'nonAsciiPrintableOnly', level: 'xml'});
52+
// Encode only non-ASCII characters, leaving special chars intact
53+
encode('< > " \' & ©', { mode: 'nonAsciiPrintableOnly', level: 'xml' });
4354
// -> '< > " \' & &#169;'
4455
```
4556

46-
Options:
47-
48-
#### level
49-
50-
* `all` alias to `html5` (default).
51-
* `html5` uses `HTML5` named references.
52-
* `html4` uses `HTML4` named references.
53-
* `xml` uses `XML` named references.
57+
#### Options
5458

55-
#### mode
59+
##### `level`
60+
- `all` or `html5` (default) - Uses HTML5 named references
61+
- `html4` - Uses HTML4 named references
62+
- `xml` - Uses XML named references
5663

57-
* `specialChars` encodes only HTML special characters (default).
58-
* `nonAscii` encodes HTML special characters and everything outside the [ASCII character range](https://en.wikipedia.org/wiki/ASCII).
59-
* `nonAsciiPrintable` encodes HTML special characters and everything outiside of the [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters).
60-
* `nonAsciiPrintableOnly` everything outiside of the [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters) keeping HTML special characters intact.
61-
* `extensive` encodes all non-printable characters, non-ASCII characters and all characters with named references.
62-
63-
#### numeric
64-
65-
* `decimal` uses decimal numbers when encoding html entities. i.e. `&#169;` (default).
66-
* `hexadecimal` uses hexadecimal numbers when encoding html entities. i.e. `&#xa9;`.
64+
##### `mode`
65+
- `specialChars` (default) - Encodes only HTML special characters
66+
- `nonAscii` - Encodes HTML special characters and everything outside the [ASCII range](https://en.wikipedia.org/wiki/ASCII)
67+
- `nonAsciiPrintable` - Encodes HTML special characters and everything outside [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters)
68+
- `nonAsciiPrintableOnly` - Encodes everything outside ASCII printable range, keeping HTML special characters intact
69+
- `extensive` - Encodes all non-printable characters, non-ASCII characters and all characters with named references
6770

71+
##### `numeric`
72+
- `decimal` (default) - Uses decimal numbers for HTML entities (e.g., `&#169;`)
73+
- `hexadecimal` - Uses hexadecimal numbers for HTML entities (e.g., `&#xa9;`)
6874

6975
### decode(text, options)
7076

71-
Decodes text replacing entities to characters. Unknown entities are left as is.
77+
Decodes text by replacing HTML entities with their corresponding characters. Unknown entities are preserved.
7278

7379
```js
74-
import {decode} from 'html-entities';
80+
import { decode } from 'html-entities';
7581

82+
// Basic usage (defaults to HTML5)
7683
decode('&lt; &gt; &quot; &apos; &amp; &#169; &#8710;');
7784
// -> '< > " \' & © ∆'
7885

79-
decode('&copy;', {level: 'html5'});
86+
// Specify encoding level
87+
decode('&copy;', { level: 'html5' });
8088
// -> '©'
8189

82-
decode('&copy;', {level: 'xml'});
90+
// XML level doesn't recognize &copy;
91+
decode('&copy;', { level: 'xml' });
8392
// -> '&copy;'
8493
```
8594

86-
Options:
87-
88-
#### level
95+
#### Options
8996

90-
* `all` alias to `html5` (default).
91-
* `html5` uses `HTML5` named references.
92-
* `html4` uses `HTML4` named references.
93-
* `xml` uses `XML` named references.
97+
##### `level`
98+
- `all` or `html5` (default) - Uses HTML5 named references
99+
- `html4` - Uses HTML4 named references
100+
- `xml` - Uses XML named references
94101

95-
#### scope
96-
97-
* `body` emulates behavior of browser when parsing tag bodies: entities without semicolon are also replaced (default).
98-
* `attribute` emulates behavior of browser when parsing tag attributes: entities without semicolon are replaced when not followed by equality sign `=`.
99-
* `strict` ignores entities without semicolon.
102+
##### `scope`
103+
- `body` (default) - Emulates browser behavior when parsing tag bodies: entities without semicolon are also replaced
104+
- `attribute` - Emulates browser behavior when parsing tag attributes: entities without semicolon are replaced when not followed by `=`
105+
- `strict` - Ignores entities without semicolon
100106

101107
### decodeEntity(text, options)
102108

103-
Decodes a single HTML entity. Unknown entitiy is left as is.
109+
Decodes a single HTML entity. Unknown entities are preserved.
104110

105111
```js
106-
import {decodeEntity} from 'html-entities';
112+
import { decodeEntity } from 'html-entities';
107113

108114
decodeEntity('&lt;');
109115
// -> '<'
110116

111-
decodeEntity('&copy;', {level: 'html5'});
117+
decodeEntity('&copy;', { level: 'html5' });
112118
// -> '©'
113119

114-
decodeEntity('&copy;', {level: 'xml'});
120+
decodeEntity('&copy;', { level: 'xml' });
115121
// -> '&copy;'
116122
```
117123

118-
Options:
119-
120-
#### level
124+
#### Options
121125

122-
* `all` alias to `html5` (default).
123-
* `html5` uses `HTML5` named references.
124-
* `html4` uses `HTML4` named references.
125-
* `xml` uses `XML` named references.
126+
##### `level`
127+
- `all` or `html5` (default) - Uses HTML5 named references
128+
- `html4` - Uses HTML4 named references
129+
- `xml` - Uses XML named references
126130

127-
Package Size comparison
128-
-----------------------
131+
## Package Size Comparison
129132

130-
* `html-entities` - 132 kB
131-
* `entities` - 540 kB
132-
* `he` - 124 kB
133+
| Library | Size |
134+
|---------|------|
135+
| **html-entities** | 132 kB |
136+
| he | 124 kB |
137+
| entities | 540 kB |
133138

134-
Performance comparison
135-
----------------------
139+
## Performance Comparison
136140

137-
Statistically significant comparison with other libraries using `benchmark.js`.
138-
Results by this library are marked with `*`.
139-
The source code of the benchmark is available at `benchmark/benchmark.ts`.
141+
Results from benchmarks using `benchmark.js`. This library's results are marked with `*`.
142+
See benchmark source code at `benchmark/benchmark.ts`.
140143

141144
```
142145
Common
@@ -210,26 +213,16 @@ Escaping
210213
#4: entities.escape x 673,710 ops/sec ±1.30% (94 runs sampled)
211214
```
212215

213-
License
214-
-------
216+
## License
215217

216218
MIT
217219

218-
Security contact information
219-
----------------------------
220+
## Security Contact Information
220221

221-
To report a security vulnerability, please use the
222-
[Tidelift security contact](https://tidelift.com/security). Tidelift will
223-
coordinate the fix and disclosure.
222+
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
224223

225-
`html-entities` for enterprise
226-
------------------------------
224+
## For Enterprise
227225

228-
Available as part of the Tidelift Subscription
226+
Available as part of the Tidelift Subscription.
229227

230-
The maintainers of `html-entities` and thousands of other packages are working with
231-
Tidelift to deliver commercial support and maintenance for the open source
232-
dependencies you use to build your applications. Save time, reduce risk, and
233-
improve code health, while paying the maintainers of the exact dependencies you
234-
use.
235-
[Learn more.](https://tidelift.com/subscription/pkg/npm-html-entities?utm_source=npm-html-entities&utm_medium=referral&utm_campaign=enterprise)
228+
The maintainers of `html-entities` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-html-entities?utm_source=npm-html-entities&utm_medium=referral&utm_campaign=enterprise)

0 commit comments

Comments
 (0)