Auditing markup (validators, outlines, smell tests)

Writing markup is one job; checking it is another. Here are practical ways to audit HTML before it goes live: validators, outline checks, and smell tests you can run without becoming a spec nerd.

You already know the basics of valid tags and accessibility from the intro series. Auditing is about catching what slips through when you are tired, copying from Stack Overflow, or merging templates from three different eras.

Start with the validator

The W3C Markup Validation Service and the Nu HTML Checker parse your page and report syntax errors: unclosed tags, attributes that do not exist, elements in the wrong place.

Paste a URL, upload a file, or paste HTML directly. Fix red errors first. Yellow warnings are worth reading but not always worth chasing (some are opinions about style).

Validation does not mean the page is good. It means the browser is less likely to repair your markup in unpredictable ways. Invalid nesting (a <div> inside a <p>, for example) is a common source of weird layout bugs.

Check the document outline

Headings define the page structure for assistive technology and search engines. The outline should read like a table of contents: one logical <h1>, sections stepped down without skipping levels for styling convenience.

Tools that help:

• Browser extensions such as HeadingsMap (shows the heading tree).
• Accessibility inspectors in Firefox and Chrome DevTools.
• Your eyes: strip the CSS mentally and ask whether the heading order still makes sense.

Bad outline (skipped levels):

<h1>Services</h1>
<h3>Boiler repair</h3>  <!-- skipped h2 -->

Better:

<h1>Services</h1>
<h2>Boiler repair</h2>

Use CSS to make an <h2> look smaller if the design demands it. Do not pick heading levels for font size.

Landmarks and regions

Each page should have one <main>, a sensible header and footer, and navigation wrapped in <nav> with an accessible name when you have more than one nav block.

Quick check in DevTools: search the DOM for main, header, footer, nav. Screen reader users jump between landmarks; missing or duplicated <main> elements confuse them.

Automated accessibility scans

Tools like axe (browser extension or built into DevTools Lighthouse) catch low-hanging fruit: missing alt text, insufficient colour contrast (CSS-related but flagged in page audits), empty links, duplicate IDs.

Run Lighthouse in Chrome DevTools on a few key templates. Treat the accessibility score as a hint, not a certificate. Automated tools miss most of what a human would notice in a keyboard walkthrough.

Smell tests (manual)

These are fast checks experienced developers run by habit:

• Div soup – could any <div> be a <section>, <article>, <nav>, or <button>?
• Clickable divs – if it behaves like a link or button, is it one?
• Duplicate IDs – IDs must be unique per page. Search for id= and count.
• Empty links and buttons – <a href="#"></a> with an icon only needs visible text or aria-label.
• Placeholder as label – placeholders disappear when you type; every field needs a real <label>.
• Tables for layout – if it is not tabular data, it should not be a <table>.
• Inline styles everywhere – not invalid HTML, but a sign markup and CSS have tangled.

Keyboard and screen reader spot check

Tab through the page without a mouse. Can you reach every interactive element? Is focus visible? Does the tab order follow the visual order?

Turn on VoiceOver (Mac) or NVDA (Windows) for five minutes on one page. Listen to how headings and landmarks are announced. Painful the first time; invaluable.

Compare templates across the site

Audit one page of each type: home, inner content, listing, contact form, error page. Bugs love the page you built once and never looked at again.

Check that shared components (header, footer, cards) use identical HTML structure on every page. Drift between templates is how you end up with three different card markups and CSS that only works on the homepage.

A short audit checklist

• Validator: no errors on representative pages.
• One <h1>; heading levels do not skip.
• Single <main>; nav and footer landmarks present.
• Every <img> has appropriate alt (or alt="" if decorative).
• Form fields have labels; errors are readable text.
• No duplicate IDs.
• Keyboard navigation works; focus is visible.
• axe or Lighthouse run on key templates; obvious issues fixed.

Run this before launch and after any big template change. Catching a structural mistake in HTML is cheaper than patching it in CSS and JavaScript later.