Fixing HTML Errors in Static Site Generators

Where static site errors come from

A static site page is assembled from three layers, and each produces its own kind of error:

1. Layouts and partials, written in Go templates for Hugo, Liquid for Jekyll, Nunjucks, Liquid or others for Eleventy, and .astro components for Astro. Errors here repeat on every page that uses the layout.
2. Markdown conversion, done by Goldmark in Hugo, kramdown in Jekyll by default, markdown-it in Eleventy and remark in Astro. Each follows its own rules for raw HTML, blank lines and indentation, and those rules decide whether your HTML survives intact.
3. Shortcodes, includes and components dropped into content. They are written by developers but placed by authors, often in positions the developer did not expect, such as the middle of a paragraph.

Because the output is generated, the fix is never to edit the HTML file in the output folder. It will be overwritten on the next build. Every fix goes into a layout, a partial, a content file or the generator's configuration.

Validating the build output

Run the HTML Checker against a few deployed pages of each type to see the errors as visitors get them. To check every page at once, validate the output folder locally with a command-line validator.

# html-validate (Node)
npm install --save-dev html-validate
npx html-validate "public/**/*.html"

# The Nu HTML Checker, the engine behind the W3C validator (Java)
java -jar vnu.jar --skip-non-html --errors-only _site/

html-validate reads its rules from a .htmlvalidate.json file. Start with its recommended preset and turn off rules that do not reflect real problems on your site, rather than ignoring the whole report. The Nu checker gives the same messages as the W3C online validator, which makes it easier to compare with the HTML Checker results.

Turn off minification while you debug

Minified output puts a whole page on one line, so every error is reported at line 1 and a column number in the tens of thousands. Build without minification when validating: in Hugo, leave off the --minify flag; in Eleventy and Astro, disable the minifying transform or integration for the debug build. Minifiers also legitimately remove optional end tags and attribute quotes, which is valid HTML but can confuse stricter lint rules.

Layout and partial errors

Content wrapped in a paragraph

The most common layout error is a template that wraps the rendered content in an element that cannot hold it. Rendered Markdown contains paragraphs, lists, headings and tables, so it needs a block container.

{{/* Hugo: invalid, because .Content contains its own paragraphs */}}
<p class="lead">{{ .Content }}</p>

{{/* Valid */}}
<div class="prose">{{ .Content }}</div>

The same applies to Jekyll's {{ content }}, Eleventy's {{ content | safe }} and an Astro <slot /> placed inside a <p> or <span>. Front matter descriptions rendered through Markdown have the same problem, because the converter adds its own paragraph; render them as plain text or use an inline Markdown function such as Hugo's markdownify or .RenderString, which avoid the wrapper for short text.

Partials that open what another closes

A header partial that opens <main> and a footer partial that closes it will break the day a layout uses one without the other. Keep each partial self-contained, and let the base layout own the page skeleton: doctype, html, head, body and main.

Layouts nested twice

In Jekyll and Eleventy, a layout can itself use another layout. If both include the full skeleton, the output contains two html and body elements and a stray doctype. Only the outermost layout should contain the skeleton; inner layouts output a fragment.

Escaped output

If the content shows literal tags such as <p> on the page, the template language is escaping HTML it should trust. In Nunjucks use the safe filter on rendered content; in Hugo, use safeHTML only for HTML you control; in Astro use the set:html directive. Escaped output is not a validation error, but the fix is often made wrongly by pasting HTML into a place that then nests badly.

Markdown and shortcode quirks

Shortcodes and components inside paragraphs

Authors often place a shortcode on the same line as text, or directly under a line of text with no blank line in between. The converter then treats it as part of the paragraph, and a shortcode that outputs a figure, div or iframe ends up inside a <p>. Put block shortcodes on their own line with a blank line above and below. In Hugo, note the difference between the two call styles: output from the {{< >}} form is inserted as it is, while output from the {{% %}} form is passed through the Markdown converter, which can add paragraph tags around it.

Indented HTML becomes a code block

In Markdown, a line indented by four spaces is code. Raw HTML in a Markdown file that is neatly indented for readability can be turned into an escaped code block halfway through, leaving an opening <div> without its closing tag. Keep raw HTML blocks flush with the left margin, or move complex HTML into a shortcode or component.

Blank lines end HTML blocks

Under CommonMark rules, which Goldmark, markdown-it and remark follow, a raw HTML block ends at the first blank line. Text after the blank line is treated as Markdown again. That can be useful, but it also means a blank line inside a <table> or <details> written by hand can split the HTML so that part of it is wrapped in paragraphs.

Hugo's raw HTML omitted comment

In Hugo, raw HTML in Markdown is removed by default and replaced with the comment <!-- raw HTML omitted -->. If only the opening tag of an element was on its own line, the result can be a closing tag with nothing to close. Either enable raw HTML deliberately with markup.goldmark.renderer.unsafe = true in the site configuration, or replace raw HTML in content with shortcodes.

Jekyll and markdown inside HTML

kramdown does not convert Markdown inside an HTML block unless the block carries markdown="1". Authors who expect Markdown to work inside a div sometimes add HTML tags by hand to compensate and leave some unclosed. The markdown="1" attribute is removed from the output by kramdown, so it does not become a validation error itself.

The fix, step by step

A build check you can adapt

This GitHub Actions workflow builds a Hugo site and validates the output. The same pattern works for Jekyll, Eleventy or Astro by changing the build command and folder.

name: Validate HTML
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true
      - run: hugo --environment production
      - run: npx --yes html-validate "public/**/*.html"

If the site is large, validate a sample of pages on every pull request and the whole site on a schedule. Pin the validator version in package.json so an upgrade with new rules does not unexpectedly fail an unrelated change.

Edge cases

• Astro scoped styles add data-astro-cid attributes to elements. These are valid data attributes and not an error.
• Astro islands render framework components, and a React component inside an island can produce the same nesting errors covered in the React and Next.js guide.
• MDX treats HTML as JSX, so it fails loudly on unclosed tags at build time. That is stricter, and usually helpful.
• Eleventy preprocessing. Markdown files are run through a template language before Markdown conversion. Characters such as {{ in content can be misread as template syntax and break the surrounding HTML.
• Generated heading anchors can produce duplicate IDs when two headings share the same text. The duplicate ID guide covers that separately.
• Gatsby is React-based, so its HTML errors follow the React patterns rather than the Markdown ones here.