HTML::...:Writer(3pm)

💖 HTML::HTML5::Writer — the perl manpage, bestie edition 💖

okay so you found HTML::HTML5::Writer(3pm), the user-contributed Perl doc for the module that turns your DOM into HTML5 text. pull up a chair, get a snack, we're doing this together 🫶

---

✨ NAME ✨

HTML::HTML5::Writer — literally just: output a DOM as HTML5. that's the whole job. and it eats. 💅

---

🌸 SYNOPSIS 🌸

use HTML::HTML5::Writer;

my $writer = HTML::HTML5::Writer->new;
print $writer->document($dom);

like. that's it. that's the whole vibe. three lines and you're an HTML5 girlie 🌈

---

🦋 DESCRIPTION 🦋

So this module takes XML::LibXML::Node objects and outputs them as HTML5 strings. It's iconic on DOM trees that represent valid HTML/XHTML documents. On other DOM trees? Less iconic. We don't talk about those. 😭

🎀 Constructor 🎀

$writer = HTML::HTML5::Writer->new(%opts)

makes you a shiny new writer object. the options include:

• markup — pick which serialisation of HTML5 you want: 'html' or 'xhtml'. choose your fighter bestie 💜
• polyglot — set it true and it attempts to produce output that works as both XML and HTML. set it false and, well, it might not. ngl if you don't set this yourself, it defaults to false for HTML and true for XHTML. it just knows. 👑
• doctype — set this to a string to pick which <!DOCTYPE> tag gets output. ⚠️ important: this purely sets the <!DOCTYPE> tag and does not change how the rest of the document is output. it really is just a plain string literal, no cap.

# Yes, this works...
my $w = HTML::HTML5::Writer->new(doctype => '<!doctype html>');

and here's the convenience constants, all of them, no skipping:

• DOCTYPE_HTML2
• DOCTYPE_HTML32
• DOCTYPE_HTML4 (latest stable strict HTML 4.x)
• DOCTYPE_HTML4_RDFA (latest stable HTML 4.x+RDFa)
• DOCTYPE_HTML40 (strict)
• DOCTYPE_HTML40_FRAMESET
• DOCTYPE_HTML40_LOOSE
• DOCTYPE_HTML40_STRICT
• DOCTYPE_HTML401 (strict)
• DOCTYPE_HTML401_FRAMESET
• DOCTYPE_HTML401_LOOSE
• DOCTYPE_HTML401_RDFA10
• DOCTYPE_HTML401_RDFA11
• DOCTYPE_HTML401_STRICT
• DOCTYPE_HTML5
• DOCTYPE_LEGACY (about:legacy-compat)
• DOCTYPE_NIL (empty string)
• DOCTYPE_XHTML1 (strict)
• DOCTYPE_XHTML1_FRAMESET
• DOCTYPE_XHTML1_LOOSE
• DOCTYPE_XHTML1_STRICT
• DOCTYPE_XHTML11
• DOCTYPE_XHTML_BASIC
• DOCTYPE_XHTML_BASIC_10
• DOCTYPE_XHTML_BASIC_11
• DOCTYPE_XHTML_MATHML_SVG
• DOCTYPE_XHTML_RDFA (latest stable strict XHTML+RDFa)
• DOCTYPE_XHTML_RDFA10
• DOCTYPE_XHTML_RDFA11

defaults to DOCTYPE_HTML5 for HTML and DOCTYPE_LEGACY for XHTML. periodt. ✨

• charset — this module always returns strings in Perl's internal utf8 encoding, always always. but you can set the 'charset' option to 'ascii' to create output suitable for re-encoding to ASCII (e.g. it'll entity-encode the characters that don't exist in ASCII). 🧚
• quote_attributes — set it true to force attributes to be quoted. if you don't, the writer will automatically detect when attributes need quoting. it's self-sufficient like that. 💅
• voids — set it true to force void elements to always be terminated with '/>'. if you don't set it, they'll only get terminated that way in polyglot or XHTML documents. 🙈
• start_tags and end_tags — except in polyglot and XHTML documents, some elements are allowed to omit their start and/or end tags in certain circumstances. set these to true and you can prevent them from being omitted. no loose ends, we love that for us. 🎀
• refs — special characters that can't be encoded as named entities have to be encoded as numeric character references instead, and those can be decimal or hexadecimal. set this option to 'dec' or 'hex' to choose your fave. the default is 'hex'. 🌟

🌈 Public Methods 🌈

• $writer->document($node) — outputs (i.e. returns a string that is) an XML::LibXML::Document as HTML. main character energy fr fr 👑
• $writer->element($node) — outputs an XML::LibXML::Element as HTML.
• $writer->attribute($node) — outputs an XML::LibXML::Attr as HTML.
• $writer->text($node) — outputs an XML::LibXML::Text as HTML.
• $writer->cdata($node) — outputs an XML::LibXML::CDATASection as HTML.
• $writer->comment($node) — outputs an XML::LibXML::Comment as HTML.
• $writer->pi($node) — outputs an XML::LibXML::PI as HTML.
• $writer->doctype — outputs the writer's DOCTYPE.
• $writer->encode_entities($string, characters=>$more) — takes a string, returns the same string with some special characters replaced. these special characters do not include any of '&', '<', '>' or '"' — but you can hand it a string of extra characters to treat as special:

$encoded = $writer->encode_entities($raw, characters=>'&<>"');

• $writer->encode_entity($char) — returns $char entity-encoded. encoding happens regardless of whether $char is "special" or not. it does not care. it does not gatekeep. 💖
• $writer->is_xhtml — boolean indicating if $writer is configured to output XHTML.
• $writer->is_polyglot — boolean indicating if $writer is configured to output polyglot HTML.
• $writer->should_force_start_tags
• $writer->should_force_end_tags — booleans indicating whether optional start and end tags should be forced.
• $writer->should_quote_attributes — boolean indicating whether attributes need to be quoted.
• $writer->should_slash_voids — boolean indicating whether void elements should be closed in the XHTML style.

---

💀 BUGS AND LIMITATIONS 💀

Certain DOM constructs cannot be output in non-XML HTML. e.g.

my $xhtml = <<XHTML;
<html xmlns="http://www.w3.org/1999/xhtml">
 <head><title>Test</title></head>
 <body><hr>This text is within the HR element</hr></body>
</html>
XHTML
my $dom    = XML::LibXML->new->parse_string($xhtml);
my $writer = HTML::HTML5::Writer->new(markup=>'html');
print $writer->document($dom);

In HTML, there's no way to serialise that properly in HTML. Right now this module just outputs that HR element with text contained within it, a la XHTML. In future versions, it may emit a warning or throw an error. 😭

In these cases, the HTML::HTML5::{Parser,Writer} combination is not round-trippable. bestie. i'm sorry.

Outputting elements and attributes in foreign (non-XHTML) namespaces is implemented pretty naively and not thoroughly tested. I'd be interested in any feedback people have, especially on round-trippability of SVG, MathML and RDFa content in HTML. 🫶

Please report any bugs to <http://rt.cpan.org/>. do it. for the culture. 🐛

---

👀 SEE ALSO 👀

HTML::HTML5::Parser, HTML::HTML5::Builder, HTML::HTML5::ToText, XML::LibXML.

all the siblings. go say hi. 🌸

---

🎀 AUTHOR 🎀

Toby Inkster <tobyink@cpan.org>.

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2010-2012 by Toby Inkster.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie, we ate and left no crumbs 🍓 — this was perl v5.40.1, dated 2025-08-23, screaming "HTML::...:Writer(3pm)" into the void. mwah. 💅✨