Verify Markdown twins and JSON-LD entity links on every PR - #7614
Open
jstirnaman wants to merge 3 commits into
Open
Verify Markdown twins and JSON-LD entity links on every PR#7614jstirnaman wants to merge 3 commits into
jstirnaman wants to merge 3 commits into
Conversation
Contributor
Vale Style Check Results
✅ Check passed |
jstirnaman
force-pushed
the
docs/ai-visibility
branch
from
August 5, 2026 21:59
605976c to
1849a3a
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Adds CI validation for AI discovery artifacts, Markdown twins, and JSON-LD entity links.
Changes:
- Adds a full-build PR workflow for AI artifacts.
- Adds JSON-LD link validation and tests.
- Documents AI visibility architecture and review guidance.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/pr-ai-artifacts-check.yml |
Adds AI artifact CI validation. |
.agents/skills/ai-visibility/SKILL.md |
Adds AI visibility review guidance. |
DOCS-AI-VISIBILITY.md |
Documents AI discovery surfaces. |
DOCS-TESTING.md |
Lists the new CI check. |
scripts/check-jsonld-links.js |
Validates JSON-LD references. |
scripts/__tests__/check-jsonld-links.test.mjs |
Tests JSON-LD validation. |
| - 'scripts/check-jsonld-links.js' | ||
| - 'scripts/check-md-alternate-coherence.js' | ||
| - 'scripts/lib/**' | ||
| - 'scripts/rust-markdown-converter/**' |
jstirnaman
added a commit
that referenced
this pull request
Aug 5, 2026
- Register check-jsonld-links.js as `yarn check:jsonld-links` so it matches every sibling build/check script and is runnable locally. - Add `yarn test:jsonld-links` and run it in the workflow. The unit test was not referenced by any script or workflow, so it never executed. - Document why this workflow builds the site instead of reusing the CircleCI build or the pr-render-check job, and warn against switching `build:md` to `--only-changed` (which would gut the checks). - Add a concurrency group so rapid pushes cannot stack full site builds. - Add timeout-minutes and list the two test files in the path filter. - List the workflow in the docs-testing skill CI table.
- Register check-jsonld-links.js as `yarn check:jsonld-links` so it matches every sibling build/check script and is runnable locally. - Add `yarn test:jsonld-links` and run it in the workflow. The unit test was not referenced by any script or workflow, so it never executed. - Document why this workflow builds the site instead of reusing the CircleCI build or the pr-render-check job, and warn against switching `build:md` to `--only-changed` (which would gut the checks). - Add a concurrency group so rapid pushes cannot stack full site builds. - Add timeout-minutes and list the two test files in the path filter. - List the workflow in the docs-testing skill CI table.
jstirnaman
changed the title
jstirnaman
force-pushed
the
docs/ai-visibility
branch
from
August 5, 2026 22:24
53e2348 to
96b04ce
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
pr-ai-artifacts-check.yml, a pre-merge gate for the Markdown-twinand AI-discovery artifact set.
scripts/check-jsonld-links.js(yarn check:jsonld-links) and unittests. It verifies that every JSON-LD
@idreference in built HTMLresolves to a node defined somewhere in the site's entity graph.
Why
CircleCI already generates these artifacts, but not in a form that can gate
a PR. On non-master branches it runs
build:md --only-changedand skipsbuild:llms-fullandcheck:md-coherenceentirely, because a partial.mdset would false-positive them. Nothing verified JSON-LD
@idreferences atall.
The job builds the site because the checks need a complete
public/to runagainst. That build is a cost, not the feature.
Impact
llms-fullcorpora,and dangling JSON-LD
@idreferences.pr-render-checkbuilds without API docs, andpr-previewbuilds thembut verifies nothing.
scripts that generate the artifacts.
Verification
CI run on this PR: 4447 URLs in
sitemap-md.xml, 15 corpora coherent,markdown-completeness 2/2, JSON-LD 18 nodes across 6195 HTML pages.
Locally:
yarn test:jsonld-linksyarn check:jsonld-links --public-dir publicyarn check:md-coherence --public-dir publicPUBLIC_DIR=public yarn test:markdown-completenessPreview pages
Not applicable — CI and build-validation changes only.
Checklist