CSS::Inliner(3pm)

💖 CSS::Inliner 💖

okay bestie, so this is the manual page for CSS::Inliner — the Perl library that takes your CSS <style> blocks and inlines them, and it's part of the perl documentation collection (yes, the whole thing ships as CSS::Inliner(3pm)). grab a boba, we're doing this 💅

---

✨ NAME ✨

CSS::Inliner — Library for converting CSS <style> blocks to inline styles. 🎀

---

🌸 SYNOPSIS 🌸

use CSS::Inliner;

my $inliner = new CSS::Inliner();

$inliner->read_file({ filename => 'myfile.html' });

print $inliner->inlinify();

like… that's it. that's the whole vibe. four lines and you're iconic 👑

---

🦋 DESCRIPTION 🦋

It's a library for converting CSS style blocks into inline styles inside an HTML document. Specifically?? It's built for the ease of generating HTML emails ✉️. And why do we need that, you ask? Because certain email clients straight up do NOT support top level <style> declarations — despite it being 2017. yes. we know. we're all tired 😭

⚠️ NOTE: the development of this module is currently suspended, because the sponsoring entity, MailerMailer LLC, has been sold to j2 Global. not me getting abandoned mid-manpage 💀

---

💅 METHODS 💅

🌟 new

Instantiates the Inliner object, bestie. It sets up the class variables that get used during file parsing/processing. Possible options are:

• html_tree — (optional) Pass in a fresh unparsed instance of HTML::Treebuilder.

⚠️ NOTE: any passed references to HTML::TreeBuilder will be substantially altered by passing it in here... like, that tree is not coming back the same, fr fr 🫣

• strip_attrs — (optional) Remove all "id" and "class" attributes during inlining.
• leave_style — (optional) Leave style/link tags alone within <head> during inlining.
• relaxed — (optional) Relaxed HTML parsing, which will attempt to interpret non-HTML4 documents.
• encode_entities — (optional) Encode generated inline-styles (in case they contain HTML meta characters).
• ignore_style_type_attr — (optional) Ignore the deprecated type attribute of the "style" tag.

⚠️ NOTE: this argument is not compatible with passing an html_tree. pick a lane bestie 🚫

• agent — (optional) Pass in a string containing a preferred user-agent, which overrides the internal default provided by the module for handling remote documents.

🌈 fetch_file

Fetches a remote HTML file that supposedly contains both HTML and a style declaration, then properly tags the data with the proper charset as provided by the remote webserver (if any). After that it calls the read method automatically. very efficient of it ✨

This method expands all relative urls, and also fully expands the stylesheet reference within the document.

This method requires you to pass in a params hash containing a url argument for the requested document. For example:

$self->fetch_file({ url => 'http://www.example.com' });

Heads up: you can specify a user-agent to override the default user-agent of 'Mozilla/4.0' within the constructor. Doing so may avoid certain issues with agent filtering related to quirky webserver configs. quirky webservers stay quirked 🙈

Input Parameters:

• url — the desired url for a remote asset presumably containing both html and css
• charset — (optional) programmer specified charset for the pass url

🎀 read_file

Opens and reads an HTML file that supposedly contains both HTML and a style declaration, and properly tags the data with the proper charset if specified. It subsequently calls the read() method automatically. (notice how everything auto-calls read()? it's giving delegation, and we love her for it 💖)

This method requires you to pass in a params hash that contains a filename argument. For example:

$self->read_file({ filename => 'myfile.html' });

Additionally you can specify the character encoding within the file, for example:

$self->read_file({ filename => 'myfile.html', charset => 'utf8' });

Input Parameters:

• filename — name of local file presumably containing both html and css
• charset — (optional) programmer specified charset of the passed file

🧚 read

Reads passed html data and parses it. The intermediate data is stored in class variables.

The <style> block is ripped out of the html here, and stored separately. Class/ID/Names used in the markup are left alone. she took the style block and left the markup unbothered — main character energy, no notes 👑

This method requires you to pass in a params hash that contains scalar html data. For example:

$self->read({ html => $html });

⚠️ NOTE: you are required to pass a properly encoded perl reference to the html data. This method does not do the dirty work of encoding the html as utf8 — do that before calling this method. that's a you problem, bestie 😭

Input Parameters:

• html — scalar presumably containing both html and css
• charset — (optional) scalar representing the original charset of the passed html

🔥 detect_charset

Detects the charset of the passed content.

The algorithm present here is roughly based off of the HTML5 W3C working group document, which lays out a recommendation for determining the character set of a received document, which can be seen here under the "determining the character encoding" section: http://www.w3.org/TR/html5/syntax.html — academic queen behavior 📚

⚠️ NOTE: in the event that no charset can be identified, the library will handle the content as a mix of UTF-8/CP-1252/8859-1/ASCII by attempting to use the Encoding::FixLatin module, as this combination is relatively common in the wild. Finally, if Encoding::FixLatin is unavailable the content will be treated as ASCII. the wild is wild 🌪️

Input Parameters:

• content — scalar presumably containing both html and css
• charset — (optional) programmer specified charset for the passed content
• ctcharset — (optional) content-type specified charset for content retrieved via a url

💜 decode_characters

Implements the character decoding algorithm for HTML as outlined by the various working groups.

Basically: apply best practices for determining the applied character encoding and properly decode it. ✨

It is expected that this method will be called before any calls to read(). order matters, bestie 🫶

Input Parameters:

• content — scalar presumably containing both html and css
• charset — known charset for the passed content

⭐ inlinify

Processes the html data that was entered through either 'read' or 'read_file', and returns a scalar containing a composite chunk of html that has inline styles instead of a top level <style> declaration. this is the one. this is the moment. the finale 💫

🍓 query

Given a particular selector, returns back the applicable styles.

🌸 specificity

Given a particular selector, returns back the associated selectivity.

🌈 content_warnings

Returns back any warnings thrown while inlining a given block of content.

Note: content warnings are initialized at inlining time, not at read time. In order to receive back content feedback you must perform inlinify first. so like… do the thing before you ask for the receipts 🧾

---

👑 AUTHOR 👑

Kevin Kamel <kamelkev@underprint.com>

---

🫶 CONTRIBUTORS 🫶

• Dave Gray <cpan@doesntsuck.com>
• Vivek Khera <vivek@khera.org>
• Michael Peters <wonko@cpan.org>
• Chelsea Rio <chelseario@gmail.com>

---

📜 LICENSE 📜

This module is Copyright 2017 Khera Communications, Inc. It is licensed under the same terms as Perl itself.

---

that's the whole page bestie, slay 💅

okay and for the little sign-off moment: this manual page is CSS::Inliner(3pm) as rendered by perl v5.40.1, dated 2025-08-12. iconic date, iconic version, no cap. 💖✨