# HTML output
Source: https://pinyinjs.dev/html/
Index of every page: https://pinyinjs.dev/llms.txt
`convertToHtml` converts Chinese text to pinyin with one HTML element per
syllable. Each element can carry a tone class and uncertainty information.
```ts
import { convertToHtml } from "@kensio/pinyinjs";
convertToHtml(dictionary, "行");
// xíng
```
Use the classes to colour tones or show readers where a pronunciation is
uncertain.
## Generated markup
```ts
convertToHtml(dictionary, "银行");
// yínháng
```
| Class | On |
| ------------------------- | ------------------------------------------ |
| `py-syllable` | every syllable element |
| `py-tone-1` … `py-tone-5` | the syllable's tone; 5 is the neutral tone |
| `py-uncertain` | a syllable the decoder was guessing at |
An uncertain syllable has a `data-alternatives` attribute containing the other
readings, separated by spaces and ordered by the decoder.
Non-Han text is escaped and emitted without a wrapper:
```ts
convertToHtml(dictionary, "3D银行");
// sān D yínháng
```
HTML escaping is always enabled, including for input that cannot be parsed as
a syllable.
## Language tags
Each syllable has a `lang` attribute:
| Conversion | `lang` |
| ----------------- | ------------------- |
| `zh-CN` (default) | `zh-Latn-CN-pinyin` |
| `zh-TW` | `zh-Latn-TW-pinyin` |
```ts
convertToHtml(dictionary, "垃圾", { locale: "zh-TW" });
// lèsè
```
The tag identifies Mandarin written in pinyin. Screen readers and browsers can
use it for pronunciation, hyphenation and font selection. `zh-Latn-CN-pinyin`
uses registered BCP 47 subtags. Without an explicit tag, pinyin would inherit
the surrounding page’s language.
The region follows the conversion locale. Tone notation leaves the tag
unchanged, so `hang2` and `háng` have the same language tag.
To set the language once on a wrapper, disable per-syllable language tags:
```ts
`${convertToHtml(dictionary, "银行", { lang: false })}`;
```
## Styling
The package includes no CSS. Add styles for the generated classes:
```css
.py-tone-1 {
color: #c1272d;
}
.py-tone-2 {
color: #e08a1e;
}
.py-tone-3 {
color: #2d8a4e;
}
.py-tone-4 {
color: #2b5fa8;
}
.py-tone-5 {
color: #777;
}
.py-uncertain {
border-bottom: 1px dotted currentcolor;
}
```
The alternatives are available to CSS through their attribute:
```css
.py-uncertain::after {
content: " (" attr(data-alternatives) ")";
}
```
## Options
HTML conversion accepts every [conversion option](https://pinyinjs.dev/options/), plus these
four options:
| Option | Default | Does |
| --------------- | -------- | --------------------------------------------------------- |
| `toneClasses` | `true` | `false` leaves off `py-tone-*` |
| `markUncertain` | `true` | `false` leaves off `py-uncertain` and `data-alternatives` |
| `lang` | `true` | `false` leaves off `lang` |
| `transcription` | (pinyin) | writes the reading in another system |
```ts
convertToHtml(dictionary, "银行", { toneClasses: false });
// yínháng
convertToHtml(dictionary, "行", { markUncertain: false });
// xíng
convertToHtml(dictionary, "银行", { lang: false });
// yínháng
```
Turning off the three boolean options leaves a bare `py-syllable` element for
each syllable. You can still style syllable boundaries.
For example, conversion options can change the tone notation:
```ts
convertToHtml(dictionary, "银行", { notation: "numbers" });
```
## Other transcription systems
Set `transcription` to write bopomofo, Wade-Giles, Yale, Gwoyeu Romatzyh or IPA.
The option also works with annotated HTML:
```ts
import { convertToAnnotatedHtml, BOPOMOFO } from "@kensio/pinyinjs";
convertToAnnotatedHtml(dictionary, "银行", { transcription: BOPOMOFO });
```
```html
银…
```
Tone and uncertainty classes remain the same across systems. `data-alternatives`
contains the alternatives in the selected system.
### Word grouping and syllable separators
All systems use the same [word grouping](https://pinyinjs.dev/romanization/#the-word-segmentation-is-shared-and-only-the-join-changes).
Each system supplies its own separator between syllable elements:
```ts
convertToHtml(dictionary, "北京", { transcription: WADE_GILES });
// Pei³-ching¹
```
A source span can contain several syllables. For example, 95% has six bopomofo
syllables inside one `