Skip to contents

Render a self-contained HTML report for a sitemap

Source: R/report.R
report_sitemap.Rd

Produces a single, fully self-contained HTML report for a sitemap source, modeled on the sitemap-validator reference renderer. Unlike read_sitemap() (which returns a tidy tibble) and validate_sitemap() (which returns the findings contract), report_sitemap() is the human-readable surface: it consumes those existing outputs and renders them, and never re-implements any parsing or validation itself.

Usage

report_sitemap(
  x,
  output = NULL,
  mode = c("strict", "non-strict"),
  urls = NULL,
  findings = NULL,
  audit = NULL,
  title = NULL,
  user_agent = default_user_agent(),
  limits = fetch_limits(),
  index_limits = NULL,
  policy = request_policy()
)

Arguments

x

A single source: a sitemap URL (character) or a path to a local sitemap file. When both urls and findings are supplied, x is used only as the displayed source label.

output

Optional path to write the HTML file to. When supplied, the report is written there (UTF-8) and the path is returned invisibly; otherwise the HTML is returned as an htmltools::HTML string.

mode

"strict" (the default) or "non-strict", passed to validate_sitemap() when findings is not supplied.

urls

Optional precomputed read_sitemap() result (a tibble with the sources attribute). When NULL (the default) it is computed from x.

findings

Optional precomputed validate_sitemap() findings tibble. When NULL (the default) it is computed from x.

audit

Optional audit_sitemap() result supplying both the URL rows and the findings from a single pass (so a URL source is fetched once, not twice). It fills whichever of urls/findings you leave NULL; an explicit urls or findings still wins. x is then used only as the source label.

title

The HTML document <title>. Defaults to a title derived from x.

user_agent

The User-Agent header for HTTP fetches. Defaults to the package User-Agent.

limits

Network limits for HTTP fetches, as from fetch_limits().

index_limits

Sitemapindex-expansion bounds (recursion depth and per-index child-count cap), as from index_limits(). Defaults to index_limits().

policy

A request_policy() applied to every HTTP hop (root, robots.txt, discovery, redirects, and index children) — configure custom headers, authentication, a proxy, TLS options, retry/backoff, and per-host throttling there. Defaults to the no-op policy.

Value

If output is supplied, the output path, invisibly. Otherwise, the report HTML as an htmltools::HTML character string.

Details

The report contains a hero banner (source, overall status, URL/index/sitemap counts), a per-source sitemap table (format, HTTP status, URL count, and lastmod/priority/changefreq presence), lastmod coverage cards with a by-month histogram, a collapsible URL folder tree grouped by path segment, a severity dashboard, the findings grouped by validation layer (deduplicated by code, with evidence excerpts), the checks that ran and passed, prescriptive recommendations, and a searchable, sortable, CSV-exportable URL table.

Two sections read the run rather than the findings. The Checks section is driven by the finding-code registry: it enumerates the checks this package actually implements, marks those that ran and did not fire as passed, and names the layers the run did not exercise as neither passed nor failed — so an empty findings table can be told apart from a validation that never ran. A layer counts as having run only on positive evidence, which understates rather than overstates: check_robots = TRUE leaves no trace when nothing is disallowed, so a clean robots run reads as "not exercised". A check is also gated on the registry's ruleset column, independently of its layer: a baseline call cannot reach an engine-gated emitter however thoroughly it exercised the surrounding layer, so those checks are reported as unknown rather than clean. Pass the result of validate_sitemap_ruleset() as findings to have the selected engine's checks counted. The Recommendations section is prescriptive rather than diagnostic — stale or absent lastmod, priority/changefreq that the major engines ignore, and the 50,000-URL / 50 MB / 50,000-child bounds as they are approached — each carrying its source and one provenance tag.

The output is entirely self-contained: all CSS, JavaScript (search, sort, CSV export, tree toggle, and a light/dark theme toggle), and data are inlined, so the file references no external hosts and works offline. The palette follows the viewer's prefers-color-scheme by default; the in-page toggle stamps a data-theme attribute on the root element that wins in both directions.

By default the source x is both read (via read_sitemap(), for the URL rows and per-source metadata) and validated (via validate_sitemap(), for the findings). To avoid re-fetching a URL source, or to render results you have already computed, pass them via urls and/or findings; in that case x is used only as the report's source label.

See also

read_sitemap() and validate_sitemap() for the underlying data.

Examples

# Render a report for a local sitemap file to a temporary HTML file.
xml <- paste0(
  '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
  '<url><loc>https://example.com/</loc>',
  '<lastmod>2024-01-01</lastmod></url>',
  '<url><loc>https://example.com/about</loc></url>',
  '</urlset>'
)
path <- tempfile(fileext = ".xml")
writeLines(xml, path)
out <- tempfile(fileext = ".html")
report_sitemap(path, output = out)

# Render directly from a sitemap URL (fetches twice: read + validate).
# report_sitemap("https://example.com/sitemap.xml", output = "report.html")

# Reuse results you have already computed to avoid re-fetching.
# u <- read_sitemap("https://example.com/sitemap.xml")
# f <- validate_sitemap("https://example.com/sitemap.xml")
# report_sitemap(
#   "example.com", urls = u, findings = f, output = "report.html"
# )