How to Format HTML: Best Practices for Clean, Readable Code

Well-formatted HTML is easier to read, easier to debug and easier for your team to maintain. Whether you are writing HTML by hand, generating it from a template engine or cleaning up legacy markup, consistent formatting makes a real difference. In this guide, we will cover the rules and conventions that keep HTML clean and readable, when to minify for production, and common formatting mistakes to avoid.

Why HTML Formatting Matters

Unlike Python, HTML does not care about whitespace. Browsers parse and render your markup the same way whether it is beautifully indented or compressed into a single line. But developers care. Poorly formatted HTML makes it harder to spot nesting errors, find specific elements and understand the document structure. When you are working in a team, inconsistent formatting leads to noisy diffs in version control, making code review more difficult than it needs to be.

Indentation Rules

The most important formatting rule is consistent indentation. Most teams use 2 spaces per level, though some prefer 4 spaces or tabs. Pick one and stick with it across the project.

Each nested element should be indented one level deeper than its parent. The closing tag should be at the same indentation level as the opening tag. This visual hierarchy makes it immediately clear which elements are children of which parents.

Attribute Formatting

When an element has many attributes, putting them all on one line makes the tag hard to read. Break attributes onto separate lines when the tag exceeds roughly 80-100 characters:

When breaking attributes, indent them one level deeper than the tag name. Some formatters align attributes with the first attribute after the tag name, but the indented style is more common and works better with smaller indentation widths.

Attribute Order Convention

While HTML does not enforce attribute order, using a consistent order makes elements easier to scan. A widely adopted convention is:

1. Structural attributes: id, class
2. Behavioral attributes: type, name, value, href, src
3. Display attributes: alt, title, placeholder
4. Accessibility: aria-*, role
5. Data attributes: data-*
6. Boolean attributes: required, disabled, hidden

Void Elements and Self-Closing Tags

HTML5 void elements like <img>, <input>, <br>, <hr>, <meta> and <link> do not need closing tags. In HTML5, both <br> and <br /> are valid, but pick one style and be consistent. The shorter form without the trailing slash is the HTML5 convention.

Semantic HTML Structure

Good formatting goes beyond indentation. Using semantic elements like <header>, <nav>, <main>, <article>, <section>, <aside> and <footer> makes your document self-documenting. When you see a <nav> tag, you immediately know it is navigation without reading the class names or content.

Formatting Tools and Editor Setup

Modern editors and tools can format HTML automatically:

• Prettier. The most popular code formatter. It handles HTML, JSX, Vue templates and more. Configure it in your project with a .prettierrc file and enable format-on-save in your editor.
• VS Code built-in formatter. Press Shift+Alt+F (Windows/Linux) or Shift+Option+F (Mac) to format the current file.
• HTMLHint. A linter specifically for HTML that catches common errors like missing closing tags, duplicate attributes and invalid nesting.
• EditorConfig. A .editorconfig file ensures consistent indentation settings across different editors and team members.

Minification for Production

While formatted HTML is great for development, minified HTML is better for production. Minification removes all unnecessary whitespace, comments and optional tags, reducing file size by 10-30%. Most build tools handle this automatically:

• html-minifier-terser is the standard library for HTML minification in Node.js projects
• Webpack, Vite and Next.js minify HTML output in production builds by default
• Gzip/Brotli compression on your web server further reduces the size of the minified HTML in transit

The key insight: keep your source code formatted and readable, let the build process handle minification. Never write minified code by hand.

Common Formatting Mistakes

• Inconsistent indentation. Mixing tabs and spaces, or switching between 2-space and 4-space indentation within the same file. Use an EditorConfig file or Prettier to enforce consistency.
• Deep nesting without structure. If your HTML is nested 8+ levels deep with only div elements, consider refactoring with semantic tags or extracting components.
• Inline styles everywhere. Long style attributes make tags unreadable. Move styles to CSS classes.
• Missing quotes on attributes. While HTML5 allows unquoted attribute values in some cases, always use double quotes for consistency and safety: class="name" not class=name.
• Leaving commented-out code. Old commented-out HTML blocks add visual noise. Delete them and rely on version control to recover old code if needed.