Skip to content

Commit 5b04870

Browse files
wooormwooorm
committed
Add improved docs
1 parent d6a45ed commit 5b04870

File tree

3 files changed

+256
-212
lines changed

3 files changed

+256
-212
lines changed

‎lib/index.js‎

Lines changed: 29 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,27 @@
33
* @typedef {import('./types.js').Parent} Parent
44
* @typedef {import('./types.js').Content} Content
55
* @typedef {import('./types.js').Options} Options
6-
* @typedef {import('./types.js').Settings} Settings
76
* @typedef {import('./types.js').State} State
8-
* @typedef {import('./types.js').Quote} Quote
97
*/
108

119
import {html, svg} from 'property-information'
1210
import {htmlVoidElements} from 'html-void-elements'
1311
import {handle} from './handle/index.js'
1412

1513
/**
16-
* @param {Node | Array<Content>} node
17-
* @param {Options} [options]
14+
* Serialize hast as HTML.
15+
*
16+
* @param {Node | Array<Content>} tree
17+
* Tree to serialize.
18+
* @param {Options | null | undefined} [options]
19+
* Configuration.
1820
* @returns {string}
21+
* Serialized HTML.
1922
*/
2023
// eslint-disable-next-line complexity
21-
export function toHtml(node, options = {}) {
22-
const quote = options.quote || '"'
24+
export function toHtml(tree, options) {
25+
const options_ = options || {}
26+
const quote = options_.quote || '"'
2327
const alternative = quote === '"' ? "'" : '"'
2428

2529
if (quote !== '"' && quote !== "'") {
@@ -31,32 +35,32 @@ export function toHtml(node, options = {}) {
3135
one,
3236
all,
3337
settings: {
34-
omitOptionalTags: options.omitOptionalTags || false,
35-
allowParseErrors: options.allowParseErrors || false,
36-
allowDangerousCharacters: options.allowDangerousCharacters || false,
37-
quoteSmart: options.quoteSmart || false,
38-
preferUnquoted: options.preferUnquoted || false,
39-
tightAttributes: options.tightAttributes || false,
40-
upperDoctype: options.upperDoctype || false,
41-
tightDoctype: options.tightDoctype || false,
42-
bogusComments: options.bogusComments || false,
43-
tightCommaSeparatedLists: options.tightCommaSeparatedLists || false,
44-
tightSelfClosing: options.tightSelfClosing || false,
45-
collapseEmptyAttributes: options.collapseEmptyAttributes || false,
46-
allowDangerousHtml: options.allowDangerousHtml || false,
47-
voids: options.voids || htmlVoidElements,
38+
omitOptionalTags: options_.omitOptionalTags || false,
39+
allowParseErrors: options_.allowParseErrors || false,
40+
allowDangerousCharacters: options_.allowDangerousCharacters || false,
41+
quoteSmart: options_.quoteSmart || false,
42+
preferUnquoted: options_.preferUnquoted || false,
43+
tightAttributes: options_.tightAttributes || false,
44+
upperDoctype: options_.upperDoctype || false,
45+
tightDoctype: options_.tightDoctype || false,
46+
bogusComments: options_.bogusComments || false,
47+
tightCommaSeparatedLists: options_.tightCommaSeparatedLists || false,
48+
tightSelfClosing: options_.tightSelfClosing || false,
49+
collapseEmptyAttributes: options_.collapseEmptyAttributes || false,
50+
allowDangerousHtml: options_.allowDangerousHtml || false,
51+
voids: options_.voids || htmlVoidElements,
4852
characterReferences:
49-
options.characterReferences || options.entities || {},
50-
closeSelfClosing: options.closeSelfClosing || false,
51-
closeEmptyElements: options.closeEmptyElements || false
53+
options_.characterReferences || options_.entities || {},
54+
closeSelfClosing: options_.closeSelfClosing || false,
55+
closeEmptyElements: options_.closeEmptyElements || false
5256
},
53-
schema: options.space === 'svg' ? svg : html,
57+
schema: options_.space === 'svg' ? svg : html,
5458
quote,
5559
alternative
5660
}
5761

5862
return state.one(
59-
Array.isArray(node) ? {type: 'root', children: node} : node,
63+
Array.isArray(tree) ? {type: 'root', children: tree} : tree,
6064
undefined,
6165
undefined
6266
)

‎lib/types.js‎

Lines changed: 75 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -39,54 +39,41 @@
3939
*
4040
* @typedef Options
4141
* Configuration.
42-
* @property {Space | null | undefined} [space='html']
43-
* When an `<svg>` element is found in the HTML space, this package already
44-
* automatically switches to and from the SVG space when entering and exiting
45-
* it.
46-
*
47-
* > 👉 **Note**: hast is not XML.
48-
* > It supports SVG as embedded in HTML.
49-
* > It does not support the features available in XML.
50-
* > Passing SVG might break but fragments of modern SVG should be fine.
51-
* > Use [`xast`][xast] if you need to support SVG as XML.
52-
* @property {CharacterReferences | null | undefined} [entities]
53-
* Deprecated: please use `characterReferences`.
54-
* @property {CharacterReferences | null | undefined} [characterReferences]
55-
* Configure how to serialize character references.
56-
* @property {ReadonlyArray<string> | null | undefined} [voids]
57-
* Tag names of elements to serialize without closing tag.
42+
* @property {boolean | null | undefined} [allowDangerousCharacters=false]
43+
* Do not encode some characters which cause XSS vulnerabilities in older
44+
* browsers.
5845
*
59-
* Not used in the SVG space.
46+
* > ⚠️ **Danger**: only set this if you completely trust the content.
47+
* @property {boolean | null | undefined} [allowDangerousHtml=false]
48+
* Allow `raw` nodes and insert them as raw HTML.
6049
*
61-
* > 👉 **Note**: It’s highly unlikely that you want to pass this, because
62-
* > hast is not for XML, and HTML will not add more void elements.
63-
* @property {boolean | null | undefined} [upperDoctype=false]
64-
* Use a `<!DOCTYPE…` instead of `<!doctype…`.
50+
* When `false`, `Raw` nodes are encoded.
6551
*
66-
* Useless except for XHTML.
67-
* @property {Quote | null | undefined} [quote='"']
68-
* Preferred quote to use.
69-
* @property {boolean | null | undefined} [quoteSmart=false]
70-
* Use the other quote if that results in less bytes.
71-
* @property {boolean | null | undefined} [preferUnquoted=false]
72-
* Leave attributes unquoted if that results in less bytes.
52+
* > ⚠️ **Danger**: only set this if you completely trust the content.
53+
* @property {boolean | null | undefined} [allowParseErrors=false]
54+
* Do not encode characters which cause parse errors (even though they work),
55+
* to save bytes.
7356
*
7457
* Not used in the SVG space.
75-
* @property {boolean | null | undefined} [omitOptionalTags=false]
76-
* Omit optional opening and closing tags.
7758
*
78-
* For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing
79-
* tags can be omitted.
80-
* The first because it’s followed by another `li`, the last because it’s
81-
* followed by nothing.
59+
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
60+
* > errors are handled is well defined, so this works but isn’t pretty).
61+
* @property {boolean | null | undefined} [bogusComments=false]
62+
* Use “bogus comments” instead of comments to save byes: `<?charlie>`
63+
* instead of `<!--charlie-->`.
8264
*
83-
* Not used in the SVG space.
84-
* @property {boolean | null | undefined} [collapseEmptyAttributes=false]
85-
* Collapse empty attributes: get `class` instead of `class=""`.
65+
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
66+
* > errors are handled is well defined, so this works but isn’t pretty).
67+
* @property {CharacterReferences | null | undefined} [characterReferences]
68+
* Configure how to serialize character references.
69+
* @property {boolean | null | undefined} [closeEmptyElements=false]
70+
* Close SVG elements without any content with slash (`/`) on the opening tag
71+
* instead of an end tag: `<circle />` instead of `<circle></circle>`.
8672
*
87-
* Not used in the SVG space.
73+
* See `tightSelfClosing` to control whether a space is used before the
74+
* slash.
8875
*
89-
* > 👉 **Note**: boolean attributes (such as `hidden`) are always collapsed.
76+
* Not used in the HTML space.
9077
* @property {boolean | null | undefined} [closeSelfClosing=false]
9178
* Close self-closing nodes with an extra slash (`/`): `<img />` instead of
9279
* `<img>`.
@@ -95,24 +82,41 @@
9582
* slash.
9683
*
9784
* Not used in the SVG space.
98-
* @property {boolean | null | undefined} [closeEmptyElements=false]
99-
* Close SVG elements without any content with slash (`/`) on the opening tag
100-
* instead of an end tag: `<circle />` instead of `<circle></circle>`.
85+
* @property {boolean | null | undefined} [collapseEmptyAttributes=false]
86+
* Collapse empty attributes: get `class` instead of `class=""`.
10187
*
102-
* See `tightSelfClosing` to control whether a space is used before the
103-
* slash.
88+
* Not used in the SVG space.
10489
*
105-
* Not used in the HTML space.
106-
* @property {boolean | null | undefined} [tightSelfClosing=false]
107-
* Do not use an extra space when closing self-closing elements: `<img/>`
108-
* instead of `<img />`.
90+
* > 👉 **Note**: boolean attributes (such as `hidden`) are always collapsed.
91+
* @property {CharacterReferences | null | undefined} [entities]
92+
* Deprecated: please use `characterReferences`.
93+
* @property {boolean | null | undefined} [omitOptionalTags=false]
94+
* Omit optional opening and closing tags.
10995
*
110-
* > 👉 **Note**: only used if `closeSelfClosing: true` or
111-
* > `closeEmptyElements: true`.
112-
* @property {boolean | null | undefined} [tightCommaSeparatedLists=false]
113-
* Join known comma-separated attribute values with just a comma (`,`),
114-
* instead of padding them on the right as well (`,␠`, where `␠` represents a
115-
* space).
96+
* For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing
97+
* tags can be omitted.
98+
* The first because it’s followed by another `li`, the last because it’s
99+
* followed by nothing.
100+
*
101+
* Not used in the SVG space.
102+
* @property {boolean | null | undefined} [preferUnquoted=false]
103+
* Leave attributes unquoted if that results in less bytes.
104+
*
105+
* Not used in the SVG space.
106+
* @property {Quote | null | undefined} [quote='"']
107+
* Preferred quote to use.
108+
* @property {boolean | null | undefined} [quoteSmart=false]
109+
* Use the other quote if that results in less bytes.
110+
* @property {Space | null | undefined} [space='html']
111+
* When an `<svg>` element is found in the HTML space, this package already
112+
* automatically switches to and from the SVG space when entering and exiting
113+
* it.
114+
*
115+
* > 👉 **Note**: hast is not XML.
116+
* > It supports SVG as embedded in HTML.
117+
* > It does not support the features available in XML.
118+
* > Passing SVG might break but fragments of modern SVG should be fine.
119+
* > Use [`xast`][xast] if you need to support SVG as XML.
116120
* @property {boolean | null | undefined} [tightAttributes=false]
117121
* Join attributes together, without whitespace, if possible: get
118122
* `class="a b"title="c d"` instead of `class="a b" title="c d"` to save
@@ -122,37 +126,33 @@
122126
*
123127
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
124128
* > errors are handled is well defined, so this works but isn’t pretty).
129+
* @property {boolean | null | undefined} [tightCommaSeparatedLists=false]
130+
* Join known comma-separated attribute values with just a comma (`,`),
131+
* instead of padding them on the right as well (`,␠`, where `␠` represents a
132+
* space).
125133
* @property {boolean | null | undefined} [tightDoctype=false]
126134
* Drop unneeded spaces in doctypes: `<!doctypehtml>` instead of
127135
* `<!doctype html>` to save bytes.
128136
*
129137
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
130138
* > errors are handled is well defined, so this works but isn’t pretty).
131-
* @property {boolean | null | undefined} [bogusComments=false]
132-
* Use “bogus comments” instead of comments to save byes: `<?charlie>`
133-
* instead of `<!--charlie-->`.
134-
*
135-
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
136-
* > errors are handled is well defined, so this works but isn’t pretty).
137-
* @property {boolean | null | undefined} [allowParseErrors=false]
138-
* Do not encode characters which cause parse errors (even though they work),
139-
* to save bytes.
140-
*
141-
* Not used in the SVG space.
139+
* @property {boolean | null | undefined} [tightSelfClosing=false]
140+
* Do not use an extra space when closing self-closing elements: `<img/>`
141+
* instead of `<img />`.
142142
*
143-
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
144-
* > errors are handled is well defined, so this works but isn’t pretty).
145-
* @property {boolean | null | undefined} [allowDangerousCharacters=false]
146-
* Do not encode some characters which cause XSS vulnerabilities in older
147-
* browsers.
143+
* > 👉 **Note**: only used if `closeSelfClosing: true` or
144+
* > `closeEmptyElements: true`.
145+
* @property {boolean | null | undefined} [upperDoctype=false]
146+
* Use a `<!DOCTYPE…` instead of `<!doctype…`.
148147
*
149-
* > ⚠️ **Danger**: only set this if you completely trust the content.
150-
* @property {boolean | null | undefined} [allowDangerousHtml=false]
151-
* Allow `raw` nodes and insert them as raw HTML.
148+
* Useless except for XHTML.
149+
* @property {ReadonlyArray<string> | null | undefined} [voids]
150+
* Tag names of elements to serialize without closing tag.
152151
*
153-
* When `false`, `Raw` nodes are encoded.
152+
* Not used in the SVG space.
154153
*
155-
* > ⚠️ **Danger**: only set this if you completely trust the content.
154+
* > 👉 **Note**: It’s highly unlikely that you want to pass this, because
155+
* > hast is not for XML, and HTML will not add more void elements.
156156
*
157157
* @typedef {Omit<Required<{[key in keyof Options]: Exclude<Options[key], null | undefined>}>, 'quote' | 'entities' | 'space'>} Settings
158158
*

0 commit comments

Comments
 (0)