doctor

Diagnose configuration, template, and structure issues in your Hwaro site.

For content validation (frontmatter, alt text, internal links), use hwaro tool validate.

hwaro doctor

# Check only a specific content directory
hwaro doctor -c posts

# Normalize config values (base_url trailing slash, sitemap priority, …)
hwaro doctor --fix

# Add recommended config sections to config.toml
hwaro doctor --approve

# Do both (equivalent to --fix --approve)
hwaro doctor --full

# Preview changes without writing config.toml
hwaro doctor --full --dry-run

# Output result as JSON
hwaro doctor --json

hwaro tool doctor also works as a backward-compatible alias.

Options

What It Checks

Config diagnostics:

• base_url is not set, or has a trailing slash
• title is still a placeholder (Hwaro Site, My Hwaro Site)
• sitemap.changefreq has an invalid value
• sitemap.priority is out of range (0.0–1.0)
• Duplicate taxonomy names or language codes
• Invalid search.format, markdown.math_engine or pwa.cache_strategy value
• default_language with no matching [languages.<code>] block
• deployment.target / [related] taxonomies referencing something undefined
• [[menus.*]] entries whose parent names no identifier in the same menu
• Referenced files and directories that don't exist ([og] default_image, [pwa] icons, [auto_includes] dirs, [[assets.bundles]] files, …). Values that carry their own origin (https://…, //cdn…, data:…) are left alone — doctor can't validate a remote URL.

Template diagnostics:

• Templates directory not found
• Required templates missing (page.html, section.html)
• Template syntax errors, reported by the same Crinja parser the build uses (unknown project shortcodes are tolerated)

Content diagnostics:

• Content directory not found (the build would produce no pages)
• Front matter that fails to parse (TOML/YAML)
• Front matter registering a menu name no [[menus.*]] declares

Structure diagnostics:

• Section directories missing _index.md

Example Output

hwaro: doctor

  config.toml
    [ok]   file present & parseable
    [warn] base_url, title
    [ok]   sitemap (changefreq, priority)
    [ok]   taxonomies (duplicates)
    [ok]   search (format)
    [ok]   languages (default_language resolves)
    [ok]   markdown / pwa (valid enums)
    [ok]   deployment / related (refs resolve)
    [ok]   menus (parent references)
    [ok]   referenced files & dirs

  templates/
    [ok]   required files (page.html, section.html)
    [ok]   template syntax

  content/
    [ok]   directory present
    [ok]   front matter (TOML/YAML parse)
    [ok]   front matter menus (declared in config)
    [info] section index files (_index.md)

Config:
  [warn] config.toml: base_url is not set

Structure:
  [info] content/docs: Section directory missing _index.md: docs/

checked: 0 errors, 1 warning, 1 info

Tip: Use 'hwaro tool validate' for content checks

A check whose scan never ran renders as [--] … (skipped) rather than as a passing check — for example template syntax when templates/ is missing.

In a color terminal the check lines use ✓/⚠/✗/ℹ glyphs under an hwaro doctor heading, and the summary is a severity-colored ✦ checked outcome line. A clean run ends with checked: no issues found — your site looks great.

Ignoring Known Issues

If doctor reports issues you are aware of and want to suppress, add their rule IDs to the [doctor] section in config.toml:

[doctor]
ignore = [
  "title-default",
  "structure-missing-index",
]

Use hwaro doctor --json to find rule IDs in the output. Ignored issues are completely excluded from both human-readable and JSON output.

ignore only silences warning and info issues. Error-level rules (marked ✗ below) report problems that will fail hwaro build anyway, so listing one cannot disable the CI gate — doctor keeps reporting it and warns that the entry has no effect.

Available Rule IDs

Rows marked ✗ are error level and cannot be ignored.

An entry that matches no rule id is reported as having no effect, so a typo in this list never passes silently.

JSON Output

{
  "schema_version": 1,
  "issues": [
    {
      "id": "base-url-missing",
      "level": "warning",
      "category": "config",
      "file": "config.toml",
      "message": "base_url is not set"
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "infos": 0,
    "total": 1
  },
  "exit_code": 0
}