Diagnosing Invisible Hugo Pages: A Step‑by‑Step Checklist

Recognizable Condition

During a hugo build you notice a Markdown file under content/ is missing from the public/ tree and does not appear in section listings. No error or warning is emitted. The page is silently filtered out.

Common Causes

Hugo intentionally excludes pages based on front‑matter flags and dates. The most frequent culprits are:

• Draft flag – draft: true causes the page to be omitted unless --buildDrafts (-D) is used.
• Future/Expired dates – date, publishDate, expiryDate outside the current time window exclude the page unless --buildFuture (-F) or --buildExpired (-E) is passed.
• Ignore patterns – ignoreFiles in config.toml can match the file name or path.
• Template lookup order – a missing or misnamed layout may render an empty page instead of an error.
• Section outputs – outputs configuration that omits HTML for a section can hide the page from the final site.

Diagnostic Table

Finding	What to Check	Command/Action	Expected Result
Draft flag	Front matter contains draft: true	hugo --buildDrafts	Page appears in public/
Future date	Front matter date > current time	hugo --buildFuture	Page appears in public/
Expired date	Front matter expiryDate < current time	hugo --buildExpired	Page appears in public/
Ignore pattern	File path matches ignoreFiles glob	Run hugo config | grep ignoreFiles	Adjust glob or move file
Template missing	Layout not found for page type	Use hugo --debug to see lookup order	Provide correct layout or rename

Ordered Checks

1. Verify Draft Status
   

   Open the file and look for draft: true. If present, run:

   hugo --buildDrafts -D

   Check public/ for the page. If it appears, the issue is the draft flag.

2. Inspect Dates
   

   Confirm the date, publishDate, and expiryDate fields. Ensure they are in ISO 8601 (e.g., 2026-10-12T10:00:00Z) and that the server clock matches the timezone used.

   Run:

   hugo --buildFuture -F --buildExpired -E

   If the page shows, adjust the dates or add the appropriate flag to your CI build.

3. Check ignoreFiles
   

   Run:

   hugo config | grep -i ignoreFiles

   Review the glob patterns. If the file path matches, either rename the file or modify the pattern.

4. Validate Template Lookup
   

   Hugo selects a layout based on the page type and the layouts folder hierarchy. Add a debug snippet to the list template to confirm the page is considered:

   {{/* layouts/_default/list.html */}}
   {{/* Debug: print every file processed */}}
   {{- range .Pages -}}
     
   {{ .File.Path }}
   {{- end -}}

   Rebuild. If the file never appears in the debug output, the page is filtered before template rendering.

5. Inspect Section Output Settings
   

   Open config.toml and look for an outputs section that excludes HTML for the page’s section. Example:

   [outputs]

   Adjust to include HTML or remove the restriction.

Fixes by Finding

• Draft – Remove draft: true or add -D to the production build.
• Future/Expired – Correct the date or add -F/-E to the build command.
• IgnoreFiles – Update the glob in config.toml or relocate the file.
• Template – Create or rename the layout file to match Hugo’s lookup order (e.g., layouts/_default/single.html for all pages).
• Outputs – Ensure the section’s output list includes HTML.

Escalation Criteria

If after all checks the page still builds but renders empty or with a wrong layout, the problem is deeper:

• Run hugo --templateMetrics to see which layout was chosen.
• Inspect custom render hooks or shortcodes that may return empty or nil values.
• Verify that the theme’s list.html or single.html does not filter pages based on .Params or .Type.

Practical Verification

After applying a fix, run a dry build and compare the public/ tree to a previous successful build:

hugo --buildDrafts --buildFuture --buildExpired
# then use a diff tool
diff -r public/ previous-public/

Look for the missing file’s path. If it now appears, the issue is resolved.

Limitations & Notes

• Front‑matter date parsing is version‑dependent; older Hugo releases have different defaults for expiryDate handling.
• Local hugo server -D can mask draft omissions that only surface in CI builds. Always test CI commands locally.
• Timezone mismatches between the host clock and the date fields can cause a page to appear yesterday and vanish today. Use UTC in front matter or set timeZone in config.toml.
• When using JSON front matter, field names are case‑sensitive. A typo like Draft will be ignored.

Conclusion

Missing pages in a Hugo build are almost always intentional filtering. By following the ordered checks and applying the targeted fixes above, you can quickly determine whether a draft flag, date issue, ignore pattern, template problem, or output configuration is the culprit. If the page still fails to render correctly, use --templateMetrics and review custom hooks before escalating to theme support or the Hugo community.