Repository navigation
Add lightweight AsciiDoc validation for agent and CI use #240
Description
Activity
🤖 Finished Triage · ✅ Success · Started 10:20 AM UTC · Completed 10:23 AM UTC
Commit:87c4a29· View workflow run →Triage Summary
Severity: Medium · Category: Feature request
Problem
The repository lacks lightweight documentation validation. The existing
make ec-docs-previewtarget requires cloningconforma/conforma.github.ioand running a full Antora build, making it unusable in agent sandboxes or CI environments. There is currently no way for agents to verify that their.adocedits produce valid AsciiDoc or correct cross-references.Recommended Approach
- Add a
make validate-docstarget that runsasciidoctor --failure-level=WARNacross all.adocfiles inmodules/ROOT/pages/to catch syntax errors without external dependencies. - Add xref validation — either a shell script that checks
xref:targets resolve to existing files, or useantora-xref-validator. - Update
CLAUDE.mdto document the new validation command under "Common Commands." - Optionally add CI — a workflow step that runs validation on PRs touching
modules/**paths.
Proposed Test Case
1. Run `make validate-docs` on current repo — should pass cleanly. 2. Introduce a syntax error (e.g., unclosed block delimiter) — should fail. 3. Add a broken xref (e.g., xref:nonexistent-page.adoc[]) — should report it. 4. Verify the command works offline with no external repo dependencies.The issue is well-specified with clear validation criteria and is ready for implementation.
Labels: This is a new feature request for adding documentation validation tooling, matching the 'enhancement' label.
- Add a
- added 5 commits that reference this issue
on Sep 8, 2026
What happened
PR #238 (#238) onboarded the fullsend agent infrastructure. The
CLAUDE.mdwas added with repo structure guidance and mentionsmake ec-docs-previewas the documentation preview command. However, this command requires cloning an external repository (conforma/conforma.github.io) and its full Antora build dependencies, making it unusable in agent sandboxes or lightweight CI environments. There is no alternative validation step — no AsciiDoc linting, no cross-reference checking, and no link validation. Agents making documentation changes currently have no way to verify their work beyond reading the raw AsciiDoc.What could go better
Future agent-authored documentation PRs risk introducing broken cross-references (xref), invalid AsciiDoc syntax, or dead links that won't be caught until a human previews the built site. For a docs-only repo where agents will primarily be editing
.adocfiles, having a fast validation step is important for both review quality (the review agent can flag build errors) and rework rate (the code agent can catch its own mistakes before pushing).Confidence: Medium-high. This is a structural gap observable from the repo configuration. The actual impact depends on how frequently agents will make documentation changes, which I cannot determine from this single onboarding PR.
Proposed change
Add a lightweight AsciiDoc validation target to the Makefile (e.g.,
make validate-docs) that can run without external dependencies. Options include:asciidoctorwith--failure-level=WARNto catch syntax errorsxref:targets resolve to existing.adocfiles in thepages/directoryantora-xref-validatorfor cross-reference checkingUpdate
CLAUDE.mdto document the new validation command under "Common Commands" so agents discover and use it.Optionally add a CI workflow step that runs this validation on PRs touching
modules/**paths, providing automated feedback before human review.Validation criteria
make validate-docs(or similar) target exists and completes successfully on the current repo content without requiring external repos or network access.xref:references to non-existent pages.CLAUDE.mddocuments the validation command..adocfile can run the validation command in its sandbox and get pass/fail feedback.Generated by retro agent from #238