Working with legacy HTML markups, web scraped payloads, or machine-generated templates frequently produces malformed, improperly indented, or non-compliant documents. Unclosed tags, mismatched nesting, missing doctype declarations, and unescaped ampersands degrade page rendering performance and fail automated web accessibility audits.
Originally authored by Dave Raggett at the World Wide Web Consortium (W3C) and maintained modernly as HTACG (HTML Tidy Advocacy Community Group), HTML Tidy (tidy) is the definitive open-source terminal utility for parsing, cleaning, and formatting HTML, XHTML, and XML documents in Linux. This tutorial demonstrates how to install HTML Tidy on Linux distributions, format messy HTML files with clean indentation, repair broken markup structures, and integrate Tidy into automated validation scripts.
Installing HTML Tidy on Modern Linux Distributions
The tidy utility is readily packaged in the official repositories of all primary Linux operating systems.
On Ubuntu, Debian, and Linux Mint
sudo apt update && sudo apt install tidy -y
On Fedora, CentOS, and RHEL
sudo dnf install tidy -y
On Arch Linux and Manjaro
sudo pacman -S tidy
Verify that the binary is operational and inspect its build release version:
tidy -version
Basic HTML Formatting and Prettifying
By default, executing tidy against an input file parses the document, corrects structural issues, formats the indentation, and prints the result directly to standard output (stdout):
tidy -indent -quiet index.html
-indent: Enforces structured multi-level indentation across nested HTML tags.-quiet(or-q): Suppresses introductory copyright notices and non-critical status banners, outputting only warnings and errors.
To output the cleaned code directly into a new target file:
tidy -indent -quiet index.html > clean_index.html
To overwrite and update the source file directly in place, pass the -modify (or -m) flag:
tidy -modify -indent -quiet index.html
Repairing Broken and Malformed Tags
One of HTML Tidy’s most valuable capabilities is its structural correction engine. When processing corrupted markup, Tidy automatically executes the following fixes:
- Inserts missing opening or closing tags (e.g. closing an unclosed
<p>or<div>before parent boundaries). - Injects mandatory
<!DOCTYPE html>,<html>,<head>, and<title>containers if omitted. - Corrects improper tag nesting (e.g. turning
<b><i>Text</b></i>into valid<b><i>Text</i></b>). - Converts non-standard uppercase HTML tags (like
<DIV>or<BODY>) into lowercase W3C standards. - Escapes naked ampersands (
&) in URLs and copy into standard HTML entity references (&).
Configuring Custom Indentation and Wrap Limits
You can fine-tune Tidy’s formatting rules directly via command-line arguments:
Setting Custom Indentation Spaces
By default, Tidy indents nested tags using 2 spaces. You can scale this to 4 spaces:
tidy -indent --indent-spaces 4 -quiet index.html
Controlling Line Wrapping Limits
Tidy automatically wraps long lines at 66 characters. In modern development environments, hard line breaks inside paragraphs disrupt responsive layouts. To disable line wrapping entirely, set the wrap width to 0:
tidy -indent --wrap 0 -quiet index.html
Converting HTML to Clean XHTML
If you are processing markup for XML pipelines or strict EPUB publications, instruct Tidy to output fully compliant XHTML with self-closing tags (such as <br /> and <img />):
tidy -indent -asxhtml -quiet page.html > page.xhtml
Creating a Reusable Tidy Configuration File
Instead of typing lengthy CLI flags repeatedly, you can establish an authoritative configuration file (e.g. ~/.tidyrc or tidy.conf):
# tidy.conf configuration file
indent: auto
indent-spaces: 2
wrap: 0
markup: yes
output-html: yes
numeric-entities: no
quote-marks: yes
tidy-mark: no
quiet: yes
Apply your configuration file to any document using the -config switch:
tidy -config tidy.conf -modify index.html
Batch Processing Multiple HTML Files
To batch clean and reformat an entire directory containing hundreds of HTML templates, combine Tidy with the Linux find command:
find ./templates -name "*.html" -exec tidy -modify -indent --wrap 0 -quiet {} \;
This command traverses the entire subfolder hierarchy, formats every matching HTML document in place, and preserves your directory structure.
Command Flag Summary Table
| Flag Argument | Alternative Syntax | Functional Purpose |
|---|---|---|
-indent |
--indent yes |
Enforces hierarchical multi-line indentation |
-modify |
-m |
Overwrites the source file in place |
-quiet |
-q |
Suppresses non-essential notices and banner text |
-asxhtml |
--output-xhtml yes |
Converts markup to strict W3C XHTML syntax |
--wrap 0 |
-wrap 0 |
Disables automatic line wrapping on long lines |
-errors |
-e |
Outputs only syntax errors without generating markup |
Troubleshooting Common HTML Tidy Warnings
- Exit status code 1 returned in scripts: Unlike standard utilities where exit code 1 indicates a critical failure, HTML Tidy returns
1when warnings occurred (even if the file was repaired successfully). It returns2for fatal errors and0when no errors were detected. If calling Tidy in bash CI pipelines, check forexit_code -le 1. - Tidy removes empty span or div containers: By default, Tidy strips elements that contain no text or child tags. To preserve empty placeholder elements for dynamic JavaScript injection, add
--drop-empty-elements noto your arguments. - Custom framework tags flagged as errors: If your templates include custom web components or frontend tags (e.g.
<app-header>), define them as custom tags using--new-block-tags app-header,app-footerto prevent Tidy from stripping them.