Skip to main content

Z401-missing-directory-index — Directory Without Index

Z-Code: Z401 MISSING_DIRECTORY_INDEX · Engine: zensical · Exit: 0

zenzic check all --show-info
zensical - 1 file (1 docs, 0 assets) - 0.0s - 68 files/s
docs/guide
💡[Z401]Directory contains Markdown files but has no index page — the directory URL may return a 404.
────────────────────────────────────────────────────────────────────────────────
Summary:✘ 0 errors⚠ 0 warnings💡 1 info- 1 file with findings
✨ Analysis complete: All statically-detectable links, credentials, and references verified.
Refer to https://zenzic.dev/docs/reference/finding-codes for remediation · Try
'zenzic check --help' for options.
🔒 Suppression Audit: 0/30 (inline: 0, per-file: 0)
exit 0

The Fixture​

The fixture lives at examples/z401-missing-directory-index/ in the Zenzic repository. It uses the Zensical engine (requires zensical.toml).

The docs/guide/ directory contains page.md but has no index.md:

docs/
  guide/
    page.md   ✓ exists
    index.md  ✘ missing

When the site is built, visiting /guide/ will return a 404 because no page maps to that directory URL:

examples/z401-missing-directory-index/.zenzic.toml
docs_dir = "docs"
fail_under = 0

[build_context]
engine = "zensical"

Running the Example​

# Clone the Zenzic repository — no install required
cd examples/z401-missing-directory-index
uvx zenzic check all --show-info
info

Z401 is an info finding — it is suppressed by default to keep CI output concise. Pass --show-info to make it visible.

Expected output:

zensical · 1 file (1 docs, 0 assets) · 0.0s · 68 files/s

docs/guide  i  [Z401]  Directory contains Markdown files but has no index page
— the directory URL may return a 404.

────────────────────────────────────────────────────────────────────────────────

Summary:  x 0 errors  ! 0 warnings  i 1 info  · 1 file with findings

Analysis complete: All statically-detectable links, credentials, and references
verified.

Exit code: 0

Interpreting the Output​

The Z401 finding indicates a MISSING_DIRECTORY_INDEX issue.

Documentation engines that use directory-style URLs (e.g., /guide/ instead of /guide.html) require each directory that is browsable to have an index.md (or index.mdx) as its landing page. Without one, the build engine may silently omit the directory URL or return a 404:

  • Scan Type: Structure Validator (zensical engine)
  • Severity: Info
  • Impact: Deducts 2.0 DQS points (navigation category, weight 0.25).

Resolve the Issue​

Create docs/guide/index.md with a landing page for the section:

touch docs/guide/index.md

Or rename page.md to index.md if it is the only page in the directory:

mv docs/guide/page.md docs/guide/index.md

See Also​