How to Format and Clean HTML Files in Linux Terminal Using HTML Tidy

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 (&amp;).

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 1 when warnings occurred (even if the file was repaired successfully). It returns 2 for fatal errors and 0 when no errors were detected. If calling Tidy in bash CI pipelines, check for exit_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 no to 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-footer to prevent Tidy from stripping them.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.