Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 17c1b1b

Browse files
committed
Refactor docs
1 parent 329625e commit 17c1b1b

File tree

1 file changed

+118
-72
lines changed

1 file changed

+118
-72
lines changed

β€Žreadme.mdβ€Ž

Lines changed: 118 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,10 @@ This package is a utility that turns a hast tree into a string of HTML.
3434
## When should I use this?
3535

3636
You can use this utility when you want to get the serialized HTML that is
37-
represented by the syntax tree, either because you’re done with the syntax
38-
tree, or because you’re integrating with another tool that does not support
39-
syntax trees.
37+
represented by the syntax tree,
38+
either because you’re done with the syntax tree,
39+
or because you’re integrating with another tool that does not support syntax
40+
trees.
4041

4142
This utility has many options to configure how the HTML is serialized.
4243
These options help when building tools that make output pretty (such as
@@ -106,9 +107,11 @@ Serialize hast as HTML.
106107

107108
###### Parameters
108109

109-
* `tree` ([`Node`][github-hast-nodes] or `Array<Node>`)
110+
* `tree`
111+
([`Node`][github-hast-nodes] or `Array<Node>`)
110112
β€” tree to serialize
111-
* `options` ([`Options`][api-options], optional)
113+
* `options`
114+
([`Options`][api-options], optional)
112115
β€” configuration
113116

114117
###### Returns
@@ -123,25 +126,28 @@ How to serialize character references (TypeScript type).
123126

124127
###### `useNamedReferences`
125128

126-
Prefer named character references (`&amp;`) where possible (`boolean`, default:
127-
`false`).
129+
Prefer named character references (`&amp;`) where possible
130+
(`boolean`, default: `false`).
128131

129132
###### `omitOptionalSemicolons`
130133

131-
Whether to omit semicolons when possible (`boolean`, default: `false`).
134+
Whether to omit semicolons when possible
135+
(`boolean`, default: `false`).
132136

133-
> ⚠️ **Note**: this creates what HTML calls "parse errors" but is otherwise
134-
> still valid HTML β€” don’t use this except when building a minifier.
135-
> Omitting semicolons is possible for certain named and numeric references in
137+
> ⚠️ **Note**:
138+
> this creates what HTML calls "parse errors" but is otherwise still valid HTML:
139+
> don’t use this except when building a minifier;
140+
> omitting semicolons is possible for certain named and numeric references in
136141
> some cases.
137142
138143
###### `useShortestReferences`
139144

140-
Prefer the shortest possible reference, if that results in less bytes
145+
Prefer the shortest possible reference,
146+
if that results in less bytes
141147
(`boolean`, default: `false`).
142148

143-
> ⚠️ **Note**:`useNamedReferences` can be omitted when using
144-
> `useShortestReferences`.
149+
> ⚠️ **Note**:
150+
> `useNamedReferences` can be omitted when using `useShortestReferences`.
145151
146152
### `Options`
147153

@@ -154,33 +160,44 @@ Configuration (TypeScript type).
154160
Do not encode some characters which cause XSS vulnerabilities in older browsers
155161
(`boolean`, default: `false`).
156162

157-
> ⚠️ **Danger**: only set this if you completely trust the content.
163+
> ⚠️ **Danger**:
164+
> only set this if you completely trust the content.
158165
159166
###### `allowDangerousHtml`
160167

161-
Allow `raw` nodes and insert them as raw HTML (`boolean`, default: `false`).
168+
Allow `raw` nodes and insert them as raw HTML
169+
(`boolean`, default: `false`).
162170

163-
When `false`, `Raw` nodes are encoded.
171+
When `false`,
172+
`Raw` nodes are encoded.
164173

165-
> ⚠️ **Danger**: only set this if you completely trust the content.
174+
> ⚠️ **Danger**:
175+
> only set this if you completely trust the content.
166176
167177
###### `allowParseErrors`
168178

169-
Do not encode characters which cause parse errors (even though they work), to
170-
save bytes (`boolean`, default: `false`).
179+
Do not encode characters which cause parse errors
180+
(even though they work),
181+
to save bytes
182+
(`boolean`, default: `false`).
171183

172184
Not used in the SVG space.
173185

174-
> πŸ‘‰ **Note**: intentionally creates parse errors in markup (how parse errors
175-
> are handled is well defined, so this works but isn’t pretty).
186+
> πŸ‘‰ **Note**:
187+
> intentionally creates parse errors in markup
188+
> (how parse errors are handled is well defined,
189+
> so this works but isn’t pretty).
176190
177191
###### `bogusComments`
178192

179-
Use "bogus comments" instead of comments to save byes: `<?charlie>` instead of
180-
`<!--charlie-->` (`boolean`, default: `false`).
193+
Use "bogus comments" instead of comments to save byes:
194+
`<?charlie>` instead of `<!--charlie-->`
195+
(`boolean`, default: `false`).
181196

182-
> πŸ‘‰ **Note**: intentionally creates parse errors in markup (how parse errors
183-
> are handled is well defined, so this works but isn’t pretty).
197+
> πŸ‘‰ **Note**:
198+
> intentionally creates parse errors in markup
199+
> (how parse errors are handled is well defined,
200+
> so this works but isn’t pretty).
184201
185202
###### `characterReferences`
186203

@@ -190,118 +207,144 @@ Configure how to serialize character references
190207
###### `closeEmptyElements`
191208

192209
Close SVG elements without any content with slash (`/`) on the opening tag
193-
instead of an end tag: `<circle />` instead of `<circle></circle>` (`boolean`,
194-
default: `false`).
210+
instead of an end tag:
211+
`<circle />` instead of `<circle></circle>`
212+
(`boolean`, default: `false`).
195213

196214
See `tightSelfClosing` to control whether a space is used before the slash.
197215

198216
Not used in the HTML space.
199217

200218
###### `closeSelfClosing`
201219

202-
Close self-closing nodes with an extra slash (`/`): `<img />` instead of
203-
`<img>` (`boolean`, default: `false`).
220+
Close self-closing nodes with an extra slash (`/`):
221+
`<img />` instead of `<img>`
222+
(`boolean`, default: `false`).
204223

205224
See `tightSelfClosing` to control whether a space is used before the slash.
206225

207226
Not used in the SVG space.
208227

209228
###### `collapseEmptyAttributes`
210229

211-
Collapse empty attributes: get `class` instead of `class=""` (`boolean`,
212-
default: `false`).
230+
Collapse empty attributes:
231+
get `class` instead of `class=""`
232+
(`boolean`, default: `false`).
213233

214234
Not used in the SVG space.
215235

216-
> πŸ‘‰ **Note**: boolean attributes (such as `hidden`) are always collapsed.
236+
> πŸ‘‰ **Note**:
237+
> boolean attributes
238+
> (such as `hidden`)
239+
> are always collapsed.
217240
218241
###### `omitOptionalTags`
219242

220-
Omit optional opening and closing tags (`boolean`, default: `false`).
243+
Omit optional opening and closing tags
244+
(`boolean`, default: `false`).
221245

222-
For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing tags
223-
can be omitted.
224-
The first because it’s followed by another `li`, the last because it’s followed
225-
by nothing.
246+
For example,
247+
in `<ol><li>one</li><li>two</li></ol>`,
248+
both `</li>` closing tags can be omitted.
249+
The first because it’s followed by another `li`,
250+
the last because it’s followed by nothing.
226251

227252
Not used in the SVG space.
228253

229254
###### `preferUnquoted`
230255

231-
Leave attributes unquoted if that results in less bytes (`boolean`, default:
232-
`false`).
256+
Leave attributes unquoted if that results in less bytes
257+
(`boolean`, default: `false`).
233258

234259
Not used in the SVG space.
235260

236261
###### `quote`
237262

238-
Preferred quote to use ([`Quote`][api-quote], default: `'"'`).
263+
Preferred quote to use
264+
([`Quote`][api-quote], default: `'"'`).
239265

240266
###### `quoteSmart`
241267

242-
Use the other quote if that results in less bytes (`boolean`, default: `false`).
268+
Use the other quote if that results in less bytes
269+
(`boolean`, default: `false`).
243270

244271
###### `space`
245272

246-
Which space the document is in ([`Space`][api-space], default: `'html'`).
273+
Which space the document is in
274+
([`Space`][api-space], default: `'html'`).
247275

248-
When an `<svg>` element is found in the HTML space, this package already
249-
automatically switches to and from the SVG space when entering and exiting it.
276+
When an `<svg>` element is found in the HTML space,
277+
this package already automatically switches to and from the SVG space when
278+
entering and exiting it.
250279

251-
> πŸ‘‰ **Note**: hast is not XML.
280+
> πŸ‘‰ **Note**:
281+
> hast is not XML.
252282
> It supports SVG as embedded in HTML.
253283
> It does not support the features available in XML.
254284
> Passing SVG might break but fragments of modern SVG should be fine.
255285
> Use [`xast`][github-xast] if you need to support SVG as XML.
256286
257287
###### `tightAttributes`
258288

259-
Join attributes together, without whitespace, if possible: get
260-
`class="a b"title="c d"` instead of `class="a b" title="c d"` to save bytes
289+
Join attributes together,
290+
without whitespace,
291+
if possible:
292+
get `class="a b"title="c d"` instead of `class="a b" title="c d"` to save bytes
261293
(`boolean`, default: `false`).
262294

263295
Not used in the SVG space.
264296

265-
> πŸ‘‰ **Note**: intentionally creates parse errors in markup (how parse errors
266-
> are handled is well defined, so this works but isn’t pretty).
297+
> πŸ‘‰ **Note**:
298+
> intentionally creates parse errors in markup
299+
> (how parse errors are handled is well defined,
300+
> so this works but isn’t pretty).
267301
268302
###### `tightCommaSeparatedLists`
269303

270-
Join known comma-separated attribute values with just a comma (`,`), instead of
271-
padding them on the right as well (`,␠`, where `␠` represents a space)
304+
Join known comma-separated attribute values with just a comma (`,`),
305+
instead of padding them on the right as well
306+
(`,␠`, where `␠` represents a space)
272307
(`boolean`, default: `false`).
273308

274309
###### `tightDoctype`
275310

276-
Drop unneeded spaces in doctypes: `<!doctypehtml>` instead of `<!doctype html>`
277-
to save bytes (`boolean`, default: `false`).
311+
Drop unneeded spaces in doctypes:
312+
`<!doctypehtml>` instead of `<!doctype html>` to save bytes
313+
(`boolean`, default: `false`).
278314

279-
> πŸ‘‰ **Note**: intentionally creates parse errors in markup (how parse errors
280-
> are handled is well defined, so this works but isn’t pretty).
315+
> πŸ‘‰ **Note**:
316+
> intentionally creates parse errors in markup
317+
> (how parse errors are handled is well defined,
318+
> so this works but isn’t pretty).
281319
282320
###### `tightSelfClosing`
283321

284-
Do not use an extra space when closing self-closing elements: `<img/>` instead
285-
of `<img />` (`boolean`, default: `false`).
322+
Do not use an extra space when closing self-closing elements:
323+
`<img/>` instead of `<img />`
324+
(`boolean`, default: `false`).
286325

287-
> πŸ‘‰ **Note**: only used if `closeSelfClosing: true` or
288-
> `closeEmptyElements: true`.
326+
> πŸ‘‰ **Note**:
327+
> only used if `closeSelfClosing: true` or `closeEmptyElements: true`.
289328
290329
###### `upperDoctype`
291330

292-
Use a `<!DOCTYPE...` instead of `<!doctype...` (`boolean`, default: `false`).
331+
Use a `<!DOCTYPE...` instead of `<!doctype...`
332+
(`boolean`, default: `false`).
293333

294334
Useless except for XHTML.
295335

296336
###### `voids`
297337

298-
Tag names of elements to serialize without closing tag (`Array<string>`,
338+
Tag names of elements to serialize without closing tag
339+
(`Array<string>`,
299340
default: [`html-void-elements`][github-html-void-elements]).
300341

301342
Not used in the SVG space.
302343

303-
> πŸ‘‰ **Note**: It’s highly unlikely that you want to pass this, because hast is
304-
> not for XML, and HTML will not add more void elements.
344+
> πŸ‘‰ **Note**:
345+
> it’s highly unlikely that you want to pass this,
346+
> because hast is not for XML,
347+
> and HTML will not add more void elements.
305348
306349
### `Quote`
307350

@@ -325,26 +368,28 @@ type Space = 'html' | 'svg'
325368
326369
## Syntax
327370
328-
HTML is serialized according to WHATWG HTML (the living standard), which is also
329-
followed by browsers such as Chrome and Firefox.
371+
HTML is serialized according to WHATWG HTML (the living standard),
372+
which is also followed by browsers such as Chrome and Firefox.
330373
331374
## Types
332375
333376
This package is fully typed with [TypeScript][].
334377
It exports the additional types
335378
[`CharacterReferences`][api-character-references],
336379
[`Options`][api-options],
337-
[`Quote`][api-quote], and
380+
[`Quote`][api-quote],
381+
and
338382
[`Space`][api-space].
339383
340384
## Compatibility
341385
342386
Projects maintained by the unified collective are compatible with maintained
343387
versions of Node.js.
344388
345-
When we cut a new major release, we drop support for unmaintained versions of
346-
Node.
347-
This means we try to keep the current release line, `hast-util-to-html@^9`,
389+
When we cut a new major release,
390+
we drop support for unmaintained versions of Node.
391+
This means we try to keep the current release line,
392+
`hast-util-to-html@9`,
348393
compatible with Node.js 16.
349394
350395
## Security
@@ -368,8 +413,9 @@ for ways to get started.
368413
See [`support.md`][health-support] for ways to get help.
369414
370415
This project has a [code of conduct][health-coc].
371-
By interacting with this repository, organization, or community you agree to
372-
abide by its terms.
416+
By interacting with this repository,
417+
organization,
418+
or community you agree to abide by its terms.
373419
374420
## License
375421

0 commit comments

Comments
(0)

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /