TIDY(1)

📦

version 5.8.0 · 2 versions

5.8.0 · alpine 3.24, arch rolling, debian trixie, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
5.6.0 · debian bookworm, ubuntu jammy, ubuntu noble

, in alpine 3.24, arch rolling, debian trixie, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 TIDY(1) 🎀 — the manual, but make it bestie 💅

Version 5.8.0, manual section 1. Okay so, this is the whole vibe of tidy, and honestly? She ate. Let's go ✨

💖 NAME 💖

tidy — check, correct, and pretty-print HTML(5) files. That's the whole job. Iconic, lowkey.

🦋 SYNOPSIS 🦋

tidy [options] [file ...] [options] [file ...] ...

🌸 DESCRIPTION 🌸

Bestie. Tidy reads HTML, XHTML, and XML files and writes out cleaned-up markup. For the HTML variants, she detects, reports, and corrects sooo many common coding errors, and she strives to produce visually equivalent markup that's both conformant to the HTML specifications and that actually works in most browsers. Queen behavior, fr fr 👑

A super common use of Tidy is converting plain HTML to XHTML. For generic XML files though, Tidy is limited — she's just correcting basic well-formedness errors and pretty printing. That's it. No notes.

If you don't specify an input file, Tidy reads the standard input. If you don't specify an output file, Tidy writes the tidied markup to the standard output. And if you don't specify an error file, Tidy writes messages to the standard error. Simple as 💅

✨ OPTIONS ✨

Tidy supports two different kinds of options, and you need to know which is which:

Purely command-line options start with a single dash -. These can only be used on the command-line, NOT in configuration files. They're listed in the first part of this section.
Configuration options can either be passed on the command line starting with two dashes --, OR specified in a configuration file using the option name, followed by a colon :, plus the value, without the starting dashes. They're listed in the second part of this section, with a sample config file.

For command-line options that expect a numerical argument, a default is assumed if no meaningful value can be found. On the other hand, configuration options cannot be used without a value — a configuration option without a value is simply discarded and reported as an error. Bye 🙈

Using a command-line option is sometimes equivalent to setting the value of a configuration option. The equivalent option and value are shown in parentheses in the list below, as they would appear in a configuration file. For example, -quiet, -q (quiet: yes) means that using the command-line option -quiet or -q is equivalent to setting the configuration option quiet to yes. Slay, consistent ✨

Single-letter command-line options without an associated value can be combined — for example '-i', '-m' and '-u' may be combined as '-imu'. Efficiency 💅

🌈 File manipulation 🌈

-output <file>, -o <file> (output-file: <file>) — write output to the specified <file> 📝
-config <file> — set configuration options from the specified <file> ⚙️
-file <file>, -f <file> (error-file: <file>) — write errors and warnings to the specified <file> 🚨
-modify, -m (write-back: yes) — modify the original input files 😳 (yes, she edits in place, be brave)

💫 Processing directives 💫

-indent, -i (indent: auto) — indent element content 🌸
-wrap <column>, -w <column> (wrap: <column>) — wrap text at the specified <column>. 0 is assumed if <column> is missing. When this option is omitted, the default of the configuration option 'wrap' applies.
-upper, -u (uppercase-tags: yes) — force tags to upper case 🔠
-clean, -c (clean: yes) — replace FONT, NOBR and CENTER tags with CSS ✨
-bare, -b (bare: yes) — strip out smart quotes and em dashes, etc. 🧼
-gdoc, -g (gdoc: yes) — produce clean version of html exported by Google Docs 📄
-numeric, -n (numeric-entities: yes) — output numeric rather than named entities 🔢
-errors, -e (markup: no) — show only errors and warnings ⚠️
-quiet, -q (quiet: yes) — suppress nonessential output 🤫
-omit (omit-optional-tags: yes) — omit optional start tags and end tags ✂️
-xml (input-xml: yes) — specify the input is well formed XML 🧚
-asxml, -asxhtml (output-xhtml: yes) — convert HTML to well formed XHTML 💜
-ashtml (output-html: yes) — force XHTML to well formed HTML 🔁
-access <level> (accessibility-check: <level>) — do additional accessibility checks (<level> = 0, 1, 2, 3). 0 is assumed if <level> is missing. ♿

🔤 Character encodings 🔤

-raw — output values above 127 without conversion to entities 🌶️
-ascii — use ISO-8859-1 for input, US-ASCII for output
-latin0 — use ISO-8859-15 for input, US-ASCII for output
-latin1 — use ISO-8859-1 for both input and output
-iso2022 — use ISO-2022 for both input and output
-utf8 — use UTF-8 for both input and output 🌍
-mac — use MacRoman for input, US-ASCII for output 🍎
-win1252 — use Windows-1252 for input, US-ASCII for output 🪟
-ibm858 — use IBM-858 (CP850+Euro) for input, US-ASCII for output
-utf16le — use UTF-16LE for both input and output
-utf16be — use UTF-16BE for both input and output
-utf16 — use UTF-16 for both input and output
-big5 — use Big5 for both input and output
-shiftjis — use Shift_JIS for both input and output 🇯🇵

🌟 Miscellaneous 🌟

-version, -v — show the version of Tidy 🏷️
-help, -h, -? — list the command line options ❓
-help-config — list all configuration options ⚙️
-help-env — show information about the environment and runtime configuration 🌱
-show-config — list the current configuration settings 📋
-export-config — list the current configuration settings, suitable for a config file 📤
-export-default-config — list the default configuration settings, suitable for a config file 📦
-help-option <option> — show a description of the <option> 🔍
-language <lang> (language: <lang>) — set Tidy's output language to <lang>. Specify '-language help' for more help. Use before output-causing arguments to ensure the language takes effect, e.g., tidy -lang es -lang help. 🗣️

🧚 XML 🧚

-xml-help — list the command line options in XML format 📜
-xml-config — list all configuration options in XML format 📜
-xml-strings — output all of Tidy's strings in XML format 📜
-xml-error-strings — output error constants and strings in XML format 📜
-xml-options-strings — output option descriptions in XML format 📜

👑 Configuration Options General 👑

Configuration options can be specified by preceding each option with -- at the command line, followed by its desired value, OR by placing the options and values in a configuration file, and telling tidy to read that file with the -config option:

tidy --option1 value1 --option2 value2 ...
tidy -config config-file  ...

Configuration options can be conveniently grouped in a single config file. A Tidy configuration file is simply a text file, where each option is listed on a separate line in the form

option1: value1
option2: value2
etc.

The permissible values for a given option depend on the option's Type. There are five Types: Boolean, AutoBool, DocType, Enum, and String. Boolean Types allow any of yes/no, y/n, true/false, t/f, 1/0. AutoBools allow auto in addition to the values allowed by Booleans. Integer Types take non-negative integers. String Types generally have no defaults, and you should provide them in non-quoted form (unless you wish the output to contain the literal quotes). Careful with those quotes bestie 😭

Enum, Encoding, and DocType Types have a fixed repertoire of items, which are listed in the Supported values sections below.

You only need to provide options and values for those whose defaults you wish to override, although you may wish to include some already-defaulted options and values for the sake of documentation and explicitness. Do it for the lore 💅

Here is a sample config file, with at least one example of each of the five Types:

// sample Tidy configuration options
output-xhtml: yes
add-xml-decl: no
doctype: strict
char-encoding: ascii
indent: auto
wrap: 76
repeated-attributes: keep-last
error-file: errs.txt

Below is a summary and brief description of each of the options. They are listed alphabetically within each category.

🫶 Document Display options 🫶

--gnu-emacs Boolean (no if unset) — This option specifies that Tidy should change the format for reporting errors and warnings to a format that is more easily parsed by GNU Emacs or some other program. It changes them from the default

line <line number> column <column number> - (Error|Warning): <message>

to a form which includes the input filename:

<filename>:<line number>:<column number>: (Error|Warning): <message>

🎀 Document In and Out options 🎀

--add-meta-charset Boolean (no if unset) — turn this on and Tidy drops a <meta> element into the doc and sets the charset attribute to whatever encoding the document is using. Set it to yes to make it happen. periodt.
--add-xml-decl Boolean (no if unset) — says whether Tidy should add the XML declaration when it's outputting XML or XHTML.

heads up: if your input already has an <?xml ... ?> declaration, this option just gets ignored. no cap.

Also, if the output encoding is something other than ascii, one of the utf* encodings, or raw, then the declaration is always added, because the XML standard literally requires it. not negotiable, the standard said so 💀

See also: --char-encoding, --output-encoding

--add-xml-space Boolean (no if unset) — when generating XML, this makes Tidy add xml:space="preserve" to elements like <pre>, <style> and <script>. You need this if you want the whitespace in those elements to be parsed correctly without having access to the DTD. iconic behavior tbh.
--doctype String (auto if unset) — this is the one that decides which DOCTYPE declaration Tidy generates. so many moods, let's go:
- set it to omit and your output won't contain a DOCTYPE declaration at all. btw this also implies numeric-entities gets set to yes. sneaky.
- set it to html5 and the DOCTYPE becomes <!DOCTYPE html>.
- set it to auto (the default) and Tidy makes an educated guess based on the contents of the document. note that picking this option will not change the current document's DOCTYPE on output.
- set it to strict and Tidy sets the DOCTYPE to the HTML4 or XHTML1 strict DTD.
- set it to loose and the DOCTYPE becomes the HTML4 or XHTML1 loose (transitional) DTD.
- or you can hand it a string for the formal public identifier (FPI) 💅

For example:

doctype: "-//ACME//DTD HTML 3.14159//EN"

If you specify the FPI for an XHTML document, Tidy sets the system identifier to an empty string. For an HTML document, Tidy only adds a system identifier if one was already there, so it can preserve the processing mode of some browsers. And for generic XML documents? Tidy leaves the DOCTYPE unchanged. respecting boundaries, we love to see it 🫶

also lowkey important: this option does not offer validation of document conformance. it's not doing that job, bestie.

--input-xml Boolean (no if unset) — do you want Tidy to use the XML parser instead of the error-correcting HTML parser? that's the whole option. yes = XML parser, no = the chill HTML one that fixes ur mistakes.
--output-html Boolean (no if unset) — says whether Tidy should generate pretty printed output and write it as HTML. simple, clean, elegant 💖
--output-xhtml Boolean (no if unset) — same deal but the pretty printed output gets written as extensible HTML. This option makes Tidy set the DOCTYPE and default namespace as appropriate to XHTML, and it uses the corrected value in the output no matter what other sources say. she's stubborn and she's right.

For XHTML, entities can be written as named or numeric entities depending on how numeric-entities is set.

And the original case of tags and attributes will be preserved, regardless of other options. the case stays. we don't touch the case. 💅

--output-xml Boolean (no if unset) — pretty prints the output and writes it as well-formed XML ✨ Any entities that aren't defined in XML 1.0 get written as numeric entities so an XML parser can actually parse them.

Same as above: the original case of tags and attributes will be preserved, regardless of other options.

🌸 File Input-Output options 🌸

--error-file String — tells Tidy which error file to use for errors and warnings. Normally errors and warnings go to stderr. now you can redirect the yelling.

🔥 Diagnostics options 🔥

--accessibility-check Enum (0 (Tidy Classic) if unset) — Supported values: 0 (Tidy Classic), 1 (Priority 1 Checks), 2 (Priority 2 Checks), 3 (Priority 3 Checks)

This specifies what level of accessibility checking, if any, Tidy should perform. let's break down the levels:

Level 0 (Tidy Classic) performs no additional accessibility checking. just vibes.
Level 1 (Priority 1 Checks) performs the Priority Level 1 checks.
Level 2 (Priority 2 Checks) performs the Priority Level 1 and 2 checks.
Level 3 (Priority 3 Checks) performs the Priority Level 1, 2, and 3 checks.

For more info on Tidy's accessibility checking, including the specific checks made for each Priority Level, go visit Tidy's Accessibility Page at http://www.html-tidy.org/accessibility/. 🫶

--force-output Boolean (no if unset) — makes Tidy produce output even if errors are encountered. sounds fun, is not always fun.

use this option with care!! if Tidy reports an error, that means Tidy was not able to fix it (or isn't sure how), so the resulting output may not reflect your intention at all. 😭

--show-meta-change Boolean (no if unset) — enables a message whenever Tidy changes the content attribute of a meta charset declaration to match the encoding of the document. Set it to yes to switch it on. keeping receipts 📝
--warn-proprietary-attributes Boolean (yes if unset) — says whether Tidy should warn on proprietary attributes. on by default, she's watching 👀

💜 Encoding options 💜

--char-encoding Encoding (utf8 if unset) — Supported values: raw, ascii, latin0, latin1, utf8, iso2022, mac, win1252, ibm858, utf16le, utf16be, utf16, big5, shiftjis

This is the character encoding Tidy uses for input — and when you set it, Tidy automatically picks an appropriate character encoding to use for output too. note that the output encoding it chooses may be different from the input encoding. she's making decisions.

For ascii, latin0, ibm858, mac, and win1252 input encodings, the output-encoding option automatically gets set to ascii. You can set output-encoding manually to override that.
For other input encodings, output-encoding automatically gets set to the same value.
Regardless of the preset value, you can set output-encoding manually to override this.

Tidy is not an encoding converter. Although the Latin and UTF encodings can be mixed freely, it is not possible to convert Asian encodings to Latin encodings with Tidy. just so we're clear 💅

See also: --input-encoding, --output-encoding

--input-encoding Encoding (utf8 if unset) — Supported values: raw, ascii, latin0, latin1, utf8, iso2022, mac, win1252, ibm858, utf16le, utf16be, utf16, big5, shiftjis

The character encoding Tidy uses for input. Tidy makes certain assumptions about some of the input encodings, so here's the tea:

For ascii, Tidy will accept Latin-1 (ISO-8859-1) character values and convert them to entities as necessary.
For raw, Tidy makes no assumptions about the character values and passes them unchanged to output.
For mac and win1252, vendor specific character values will be accepted and converted to entities as necessary.
Asian encodings such as iso2022 will be handled appropriately, assuming the corresponding output-encoding is also specified.

same warning as above: Tidy is not an encoding converter. Latin and UTF can mix freely, but Asian encodings cannot be converted to Latin encodings with Tidy.

🧼✨ Cleanup options ✨🧼

--bare Boolean (no if unset) — this one says whether Tidy should swap smart quotes and em dashes for plain ASCII, and spit out spaces instead of non-breaking spaces, wherever those lil guys show up in the input.
--clean Boolean (no if unset) — tells Tidy to clean up some legacy presentational tags (right now that's <i>, <b>, <center> when they're wrapped inside appropriate inline tags, plus <font>). Set it to yes and those legacy tags get replaced with CSS <style> tags and structural markup where that makes sense. 💅
--drop-empty-elements Boolean (yes if unset) — should Tidy just yeet empty elements? That's the question this answers.
--drop-empty-paras Boolean (yes if unset) — same energy, but for empty paragraphs specifically.
--drop-proprietary-attributes Boolean (no if unset) — should Tidy strip out proprietary attributes, like those Microsoft data binding ones? Also: attributes that aren't allowed in the output version of HTML get dropped when this is used together with strict-tags-attributes.
--gdoc Boolean (no if unset) — turns on special behavior for cleaning up HTML that got exported from Google Docs. 🫶
--logical-emphasis Boolean (no if unset) — Tidy replaces every <i> with <em> and every <b> with <strong>. Any attributes? Preserved unchanged, no cap. This one can be set independently of the clean option.
--merge-divs Enum (auto if unset) — Supported values: no, yes, auto. This one tweaks how clean behaves when clean is set to yes. It says whether Tidy should merge nested <div> like <div><div>...</div></div>. If it's auto, the attributes of the inner <div> get moved to the outer one, and nested <div> with id attributes are not merged. If it's yes, the inner <div>'s attributes get discarded — except for class and style. See also: --clean, --merge-spans
--merge-spans Enum (auto if unset) — Supported values: no, yes, auto. Also tweaks clean's behavior when clean is yes. This one says whether Tidy should merge nested <span> like <span><span>...</span></span>. The algorithm is identical to the one merge-divs uses. See also: --clean, --merge-divs
--word-2000 Boolean (no if unset) — Tidy will go to great pains to strip out all the surplus junk Microsoft Word 2000 inserts when you save Word docs as "Web pages". It does not handle embedded images or VML. Honestly? Consider saving with Word's Save As... and picking Web Page, Filtered instead. 🙈

🌸 Entities options 🌸

--ascii-chars Boolean (no if unset) — can modify how the clean option behaves when clean is yes. When this is yes and you're using clean, then &emdash;, ”, and other named character entities get downgraded to their closest ASCII equivalents. See also: --clean
--ncr Boolean (yes if unset) — should Tidy allow numeric character references? Yes? No? This is the switch.
--numeric-entities Boolean (no if unset) — Tidy outputs entities other than the built-in HTML entities (&, <, >, and ") in numeric form instead of named form. Only entities compatible with the generated DOCTYPE declaration get used, and entities that can be represented in the output encoding get translated correspondingly. See also: --doctype, --preserve-entities
--preserve-entities Boolean (no if unset) — should Tidy preserve well-formed entities exactly as found in the input? That's the vibe. ✨
--quote-ampersand Boolean (yes if unset) — should Tidy output unadorned & characters as &? Note: in legacy doctypes only.
--quote-marks Boolean (no if unset) — Tidy outputs " characters as ", which some editing environments prefer. And the apostrophe character ' gets written out as ', because lots of web browsers don't support ' yet. 😭
--quote-nbsp Boolean (yes if unset) — should Tidy output non-breaking space characters as entities, rather than as the Unicode character value 160 (decimal)? 👑

🔧💖 Repair options 💖🔧

--alt-text String — sets the default alt= text Tidy uses for <img> attributes when the alt= attribute is missing. ⚠️ Use with care, bestie — it is your responsibility to make your documents accessible to people who cannot see the images.
--anchor-as-name Boolean (yes if unset) — controls the deletion or addition of the name attribute in elements where it can serve as an anchor. If yes: a name attribute, if one doesn't already exist, is added alongside an existing id attribute if the DTD allows it. If no: any existing name attribute gets removed if an id attribute exists or has been added.
--assume-xml-procins Boolean (no if unset) — changes how processing instructions get parsed, requiring ?> as the terminator rather than >. This option is automatically set if the input is in XML.
--coerce-endtags Boolean (yes if unset) — should Tidy coerce a start tag into an end tag when it looks like an end tag was probably intended? Like, given:

<span>foo <b>bar<b> baz</span>

Tidy will output:

<span>foo <b>bar</b> baz</span>

--css-prefix String (c if unset) — the prefix Tidy uses for styles rules. By default, c is used. 🎀
--custom-tags Enum (no if unset) — Supported values: no, blocklevel, empty, inline, pre. This enables the use of tags for autonomous custom elements, e.g. <flag-icon>, with Tidy. Custom tags are disabled if this value is no. The other settings — blocklevel, empty, inline, and pre — treat all detected custom tags accordingly. Heads up: using new-blocklevel-tags, new-empty-tags, new-inline-tags, or new-pre-tags will override the treatment of custom tags by this configuration option — handy if you've got different types of custom tags. When enabled, these tags are determined during the processing of your document using opening tags; matching closing tags get recognized accordingly, and unknown closing tags get discarded. See also: --new-blocklevel-tags, --new-empty-tags, --new-inline-tags, --new-pre-tags
--enclose-block-text Boolean (no if unset) — should Tidy insert a <p> element to enclose any text it finds in any element that allows mixed content for HTML transitional but not HTML strict? 👀
--enclose-text Boolean (no if unset) — Tidy encloses any text it finds in the body element within a <p> element. Super useful when you want to take existing HTML and use it with a style sheet. ✨
--escape-scripts Boolean (yes if unset) — causes items that look like closing tags, like </g, to be escaped to <\/g. Set this option to no if you do not want that.
--fix-backslash Boolean (yes if unset) — should Tidy replace backslash characters \ in URLs with forward slashes /? Fix it, bestie. 🩹
--fix-bad-comments Enum (auto if unset) — Supported values: no, yes, auto. This one says whether Tidy should replace unexpected hyphens with = characters when it comes across adjacent hyphens. The default, auto, will act as no for HTML5 document types, and yes for all other document types. Here's the lore: HTML has abandoned SGML comment syntax, and allows adjacent hyphens for all versions of HTML — although XML and XHTML do not. If you plan to support older browsers that require SGML comment syntax, then consider setting this value to yes.
--fix-style-tags Boolean (yes if unset) — should Tidy move all style tags to the head of the document? Yes. 👑
--fix-uri Boolean (yes if unset) — Tidy checks attribute values that carry URIs for illegal characters, and if any are found, escapes them as HTML4 recommends.
--literal-attributes Boolean (no if unset) — controls how Tidy deals with whitespace characters inside attribute values. If the value is no, Tidy normalizes attribute values by replacing any newline or tab with a single space, and then further by replacing any contiguous whitespace with a single space. To force Tidy to preserve the original, literal values of all attributes and ensure that whitespace within attribute values passes through unchanged, set this option to yes.
--lower-literals Boolean (yes if unset) — should Tidy convert the value of an attribute that takes a list of predefined values to lower case? This is required for XHTML documents. periodt.
--repeated-attributes Enum (keep-last if unset) — Supported values: keep-first, keep-last. Says whether Tidy should keep the first or the last attribute if an attribute is repeated — like when something's got two align attributes. See also: --join-classes, --join-styles
--skip-nested Boolean (yes if unset) — says Tidy should skip nested tags when parsing script and style data.
--strict-tags-attributes Boolean (no if unset) — ensures that tags and attributes are applicable for the version of HTML that Tidy outputs. When set to yes and the output document type is a strict doctype, then Tidy will report errors. If the output document type is a loose or transitional doctype, then Tidy will report warnings. 🚨

Also — and this is the fun part — if drop-proprietary-attributes is switched on, then the attributes that don't apply to the element get dropped too 💅. And when it's set to no, none of these checks are performed at all. Like, zero. Not one.

--uppercase-attributes — Enum (no if unset). Supported values: no, yes, preserve. This one decides whether Tidy writes attribute names in ALL CAPS. Set it to no and attribute names get written in lower case. Say yes and they come out in upper case, and preserve can be used to leave attribute names untouched, exactly as they were. BUT — when you're using XML input, the original case is always preserved, no matter what you pick. 🦋
--uppercase-tags — Boolean (no if unset). Should Tidy output tag names in upper case? Default is no, which gets you lower case tag names — except for XML input, where the original case is preserved. 👑

🦋 Transformation options 🦋

--decorate-inferred-ul — Boolean (no if unset). This one says whether Tidy should decorate inferred <ul> elements with some CSS markup, so they don't get indented to the right. Slay. ✨
--escape-cdata — Boolean (no if unset). Should Tidy convert <![CDATA[]]> sections into normal text? That's the whole vibe here.
--hide-comments — Boolean (no if unset). Should Tidy not print out comments. Yes, the option name says hide and the description says not print, it's giving double negative, we move. 🙈
--join-classes — Boolean (no if unset). If Tidy spots multiple class assignments on one element, should it combine those class names to generate a single, new class name? That's it, that's the option.
--join-styles — Boolean (yes if unset — yes bestie, this one's on by default). If Tidy detects multiple style values on an element, should it combine styles to generate a single, new style? 💅
--merge-emphasis — Boolean (yes if unset). Should Tidy merge nested <b> and <i> elements? For example, for the case <b class="rtop-2">foo <b class="r2-2">bar</b> baz</b>, Tidy will output <b class="rtop-2">foo bar baz</b>. Nested bold said goodbye, iconic behaviour, no cap. 🔥
--replace-color — Boolean (no if unset). Should Tidy replace numeric values in color attributes with HTML/XHTML color names where those names are defined? Like, replace #ffffff with white. Little glow-up for your hex codes. 🌈

🎀 Teaching Tidy options 🎀

Yes, this section is literally called "Teaching Tidy" and I'm obsessed. You're about to teach Tidy about tags it's never met before. 🧚

--new-blocklevel-tags — Tag Names. Supported values: tagX, tagY, ... This option specifies new block-level tags, and it takes a space or comma separated list of tag names. Unless you declare new tags, Tidy will refuse to generate a tidied file if the input includes previously unknown tags — like, it will simply not do it, bestie. Also note you can't change the content model for elements such as <table>, <ul>, <ol> and <dl>. This option is ignored in XML mode. See also: --new-empty-tags, --new-inline-tags, --new-pre-tags, --custom-tags.
--new-empty-tags — Tag Names. Supported values: tagX, tagY, ... This option specifies new empty inline tags, and it takes a space or comma separated list of tag names. Same rule as above: unless you declare new tags, Tidy will refuse to generate a tidied file if the input includes previously unknown tags. And remember to also declare empty tags as either inline or blocklevel — don't leave them hanging. This option is ignored in XML mode. See also: --new-blocklevel-tags, --new-inline-tags, --new-pre-tags, --custom-tags.
--new-inline-tags — Tag Names. Supported values: tagX, tagY, ... This option specifies new non-empty inline tags, and it takes a space or comma separated list of tag names. And yep, unless you declare new tags, Tidy will refuse to generate a tidied file if the input includes previously unknown tags. This option is ignored in XML mode. See also: --new-blocklevel-tags, --new-empty-tags, --new-pre-tags, --custom-tags.
--new-pre-tags — Tag Names. Supported values: tagX, tagY, ... This option specifies new tags that are to be processed in exactly the same way as HTML's <pre> element, and it takes a space or comma separated list of tag names. Same energy as the others: unless you declare new tags, Tidy will refuse to generate a tidied file if the input includes previously unknown tags. Note you cannot as yet add new CDATA elements. This option is ignored in XML mode. See also: --new-blocklevel-tags, --new-empty-tags, --new-inline-tags, --custom-tags.

✨ Pretty Print options ✨

--break-before-br — Boolean (no if unset). Should Tidy output a line break before each <br> element? Simple as that.
--indent — Enum (no if unset). Supported values: no, yes, auto. Should Tidy indent block-level tags? If you set it to auto, Tidy will decide whether or not to indent the content of tags such as <title>, <h1>-<h6>, <li>, <td>, or <p> based on whether that content includes a block-level element. Setting indent to yes can expose layout bugs in some browsers — so, heads up. Use the option indent-spaces to control the number of spaces or tabs output per level of indent, and indent-with-tabs to specify whether spaces or tabs are used. See also: --indent-spaces.
--indent-attributes — Boolean (no if unset). Should Tidy begin each attribute on a new line? One attribute per line, very demure, very mindful. 🎀
--indent-cdata — Boolean (no if unset). Should Tidy indent <![CDATA[]]> sections? Yep, that's the whole thing.
--indent-spaces — Integer (2 if unset). The number of spaces or tabs that Tidy uses to indent content when indent is enabled. Note that the default value for this option is dependent upon the value of indent-with-tabs (see also). See also: --indent.
--indent-with-tabs — Boolean (no if unset). Should Tidy indent with tabs instead of spaces, assuming indent is yes? Set it to yes to indent using tabs instead of the default spaces. Use the option indent-spaces to control the number of tabs output per level of indent — and note that when indent-with-tabs is enabled, the default value of indent-spaces is reset to 1. Also note tab-size controls converting input tabs to spaces; set it to zero to retain input tabs. 💅
--keep-tabs — Boolean (no if unset). With the default no, Tidy will replace all source tabs with spaces, controlled by the option tab-size, and the current line offset. Of course, except in the special blocks/elements enumerated below, this will later be reduced to just one space. If you set it to yes, this option specifies that Tidy should keep certain tabs found in the source — but only in preformatted blocks like <pre>, and other CDATA elements like <script>, <style>, and other pseudo elements like <?php ... ?>. As always, all other tabs, or sequences of tabs, in the source will continue to be replaced with a space.
--omit-optional-tags — Boolean (no if unset). Should Tidy omit optional start tags and end tags when generating output? Setting this option causes all tags for the <html>, <head>, and <body> elements to be omitted from output, as well as such end tags as </p>, </li>, </dt>, </dd>, </option>, </tr>, </td>, and </th>. This option is ignored for XML output.
--priority-attributes — Attributes Names. Supported values: attributeX, attributeY, ... This option lets you prioritize the writing of attributes in tidied documents, so they get written before the other attributes of an element. For example, you might specify that id and name are written before every other attribute. It takes a space or comma separated list of attribute names. 💅
--punctuation-wrap — Boolean (no if unset). Should Tidy line wrap after some Unicode or Chinese punctuation characters? That's the vibe.
--sort-attributes — Enum (none if unset). Supported values: none, alpha. This specifies that Tidy should sort attributes within an element using the specified sort algorithm. If set to alpha, the algorithm is an ascending alphabetic sort. When used while sorting with priority-attributes, any attribute sorting will take place after the priority attributes have been output. See also: --priority-attributes.
--tab-size — Integer (8 if unset). The number of columns that Tidy uses between successive tab stops. It's used to map tabs to spaces when reading the input.
--tidy-mark — Boolean (yes if unset). Should Tidy add a meta element to the document head to indicate that the document has been tidied? And nope, Tidy won't add a meta element if one is already present — it's not about to double up. ✨
--vertical-space — Enum (no if unset). Supported values: no, yes, auto. Should Tidy add some extra empty lines for readability? The default is no. If set to auto, Tidy will eliminate nearly all newline characters. 🌀
--wrap — Integer (68 if unset). The right margin Tidy uses for line wrapping. Tidy tries to wrap lines so that they do not exceed this length. Set wrap to 0 (zero) if you want to disable line wrapping entirely. Periodt.
--wrap-asp — Boolean (yes if unset). Should Tidy line wrap text contained within ASP pseudo elements, which look like: <% ... %>. Yes bestie, it's on by default.
--wrap-attributes — Boolean (no if unset). Should Tidy line-wrap attribute values? Meaning: if the value of an attribute causes a line to exceed the width specified by wrap, Tidy will add one or more line breaks to the value, causing it to be wrapped into multiple lines. Note that this option can be set independently of wrap-script-literals. By default Tidy replaces any newline or tab with a single space and replaces any sequences of whitespace with a single space. To force Tidy to preserve the original, literal values of all attributes, and ensure that whitespace characters within attribute values are passed through unchanged, set literal-attributes to yes. See also: --wrap-script-literals, --literal-attributes.

and bestie, the wrap girlies are literally not done yet 💅

--wrap-jste — Boolean, and it's yes if unset. This one decides whether Tidy line wraps the text sitting inside JSTE pseudo elements, which are the little guys that look like: <# ... #>.
--wrap-php — Boolean, no if unset. Controls whether Tidy drops a new line after PHP pseudo elements, which look like: <?php ... ?>.
--wrap-script-literals — Boolean, no if unset. Says whether Tidy should line wrap the string literals that get assigned to element event handler attributes, like element.onmouseover().

Also go look at: --wrap-attributes

--wrap-sections — Boolean, yes if unset. Decides if Tidy line wraps the text hanging out inside <![ ... ]> section tags.

🌸 ENVIRONMENT 🌸

HTML_TIDY — the name of your default configuration file, bestie. 💖

Make it an absolute path, okay? Because fr fr you're probably gonna invoke tidy from a bunch of different directories and a relative path is gonna ghost you.

Timing matters here, so listen up: the value of HTML_TIDY gets parsed after the compiled-in default (the one defined with -DTIDY_CONFIG_FILE), but before any of the files you specify using -config. Order of operations, queen. 👑

🫶 RUNTIME CONFIGURATION FILES 🫶

You can also point Tidy at runtime configuration files and it will try to load a configuration from them automatically. No cap.

The system runtime configuration file, /etc/tidy.conf, gets loaded and applied first — but only if it exists.
Then comes the user runtime configuration file, ~/.tidyrc.
And if you use a specific option more than once? The later usage overrides any previous usage. Periodt.

Heads up 💀: if you use the HTML_TIDY environment variable, then the user runtime configuration file will not be used. And yes, that is a feature, not a bug. The manpage said it, not me.

✨ EXIT STATUS ✨

0 — all your input files were processed successfully. Slay. 🎀
1 — there were warnings. Not fatal, but the vibe check failed a little. 🙈
2 — there were errors. It's giving chaos. 😭

🔥 SEE ALSO 🔥

Want more info about HTML Tidy? Say less:

http://www.html-tidy.org/

Want more info on HTML itself? Here you go:

HTML: Edition for Web Authors (the latest HTML specification)
http://dev.w3.org/html5/spec-author-view

HTML: The Markup Language (an HTML language reference)
http://dev.w3.org/html5/markup/

Got bugs? Got thoughts? Got feelings?

https://github.com/htacg/tidy-html5/issues/

Or you can send questions and comments to public-htacg@w3.org. They're listening, bestie. 🫶

And if you wanna validate your HTML documents, use the W3C Nu Markup Validator:

http://validator.w3.org/nu/

👑 AUTHOR 👑

Tidy was written by Dave Raggett <dsr@w3.org>, and then subsequently maintained by a team at http://tidy.sourceforge.net/, and now it's maintained by HTACG (http://www.htacg.org). A whole lineage. Iconic succession planning, honestly. 💅

The sources for HTML Tidy are available at https://github.com/htacg/tidy-html5/ under the MIT Licence. Go read them, go contribute, go be the main character.

And that's the whole page, babe. 💖 This was the HTML Tidy manual page, version 5.8.0, straight from the HTML Tidy source itself — the date lives in that footer, and yes, this is the official TIDY(1) page you just read all the way through. Proud of you. Now go tidy some markup. ✨🦋🌸

📦 where this page comes from

alpine 3.24: tidyhtml-doc 5.8.0-r5 · W3C
arch rolling: tidy 5.8.0-4 · custom
debian trixie: tidy 2:5.8.0-2 · tidy
epel 10: tidy 5.8.0-9.el10_0 · W3C
epel 9: tidy 5.8.0-2.el9 · W3C
fedora 43: tidy 5.8.0-12.fc43 · W3C
fedora 44: tidy 5.8.0-13.fc44 · W3C
nixos 26.05: html-tidy 5.8.0
nixpkgs unstable: html-tidy 5.8.0
opensuse-leap 16.0: tidy 5.8.0-160000.2.2 · W3C
opensuse-leap 16.0: tidy 5.8.0-160000.2.2 · W3C
opensuse-leap 16.0: tidy 5.8.0-160000.2.2 · W3C
opensuse-leap 16.0: tidy 5.8.0-160000.2.2 · W3C
ubuntu questing: tidy 2:5.8.0-2
ubuntu resolute: tidy 2:5.8.0-2.1 · tidy
ubuntu stonking: tidy 2:5.8.0-2.1 · tidy
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms