docs: clarify off-site AI visibility limits (closes #53)#58
Conversation
Closes #53. palkim's proposal: make explicit what aeo.js can and cannot influence so users don't treat generated files as a complete AEO strategy. Adds a "Scope" section to the introduction page (between "How it works" and "Supported Frameworks") with two side-by-side Asides: - **What aeo.js does well**: machine-readable access to your own site via llms.txt, ai-index.json, JSON-LD, sitemap, raw markdown. - **What aeo.js cannot influence**: third-party mentions, inbound links, community discussions, model training data, off-site freshness signals. Frames aeo.js as a "necessary but not sufficient" foundation paired with off-site work for full coverage. Build clean: 21 pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Docs PreviewPreview URL: https://docs-off-site-visibility-sco.aeojs.pages.dev This preview was deployed from the latest commit on this PR. |
Greptile SummaryAdds a "Scope" section to the introduction page explaining what aeo.js controls (on-site machine-readable files) versus what it cannot influence (off-site signals like inbound links, community mentions, and training data), using two Starlight
Confidence Score: 4/5Documentation-only change that is safe to merge; no logic or configuration is affected. The change is purely additive prose and MDX markup. The two minor issues — a missing docs.json entry in the Aside that is already listed in the 'Why aeo.js?' section, and the ambiguous 'PR' abbreviation — do not block functionality but leave a small inconsistency in the docs that readers will notice. website/src/content/docs/getting-started/introduction.mdx — verify the generated-files list in the new Aside is consistent with the existing 'Why aeo.js?' bullet list. Important Files Changed
Prompt To Fix All With AIFix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
website/src/content/docs/getting-started/introduction.mdx:42
The "Why aeo.js?" section above lists `docs.json` as one of the files aeo.js generates, but this Aside omits it. A reader comparing the two sections will notice the inconsistency and wonder whether `docs.json` is no longer produced or was intentionally excluded from scope.
```suggestion
- generates `llms.txt`, `llms-full.txt`, `ai-index.json`, `docs.json`, raw markdown copies, JSON-LD schema, and a sitemap
```
### Issue 2 of 2
website/src/content/docs/getting-started/introduction.mdx:57
In a developer-facing doc, "PR" is almost universally read as "pull request." Spelling out "public relations" avoids any momentary confusion for the target audience.
```suggestion
Think of aeo.js as a strong foundation — necessary but not sufficient. For full AEO coverage, pair it with the off-site work above: public relations, community engagement, and being mentioned where your customers research.
```
Reviews (1): Last reviewed commit: "docs: add scope callout clarifying off-s..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| <Aside type="note" title="What aeo.js does well"> | ||
| Improves machine-readable access to **your own site**: | ||
|
|
||
| - generates `llms.txt`, `llms-full.txt`, `ai-index.json`, raw markdown copies, JSON-LD schema, and a sitemap |
There was a problem hiding this comment.
docs.json as one of the files aeo.js generates, but this Aside omits it. A reader comparing the two sections will notice the inconsistency and wonder whether docs.json is no longer produced or was intentionally excluded from scope.
| - generates `llms.txt`, `llms-full.txt`, `ai-index.json`, raw markdown copies, JSON-LD schema, and a sitemap | |
| - generates `llms.txt`, `llms-full.txt`, `ai-index.json`, `docs.json`, raw markdown copies, JSON-LD schema, and a sitemap |
Prompt To Fix With AI
This is a comment left during a code review.
Path: website/src/content/docs/getting-started/introduction.mdx
Line: 42
Comment:
The "Why aeo.js?" section above lists `docs.json` as one of the files aeo.js generates, but this Aside omits it. A reader comparing the two sections will notice the inconsistency and wonder whether `docs.json` is no longer produced or was intentionally excluded from scope.
```suggestion
- generates `llms.txt`, `llms-full.txt`, `ai-index.json`, `docs.json`, raw markdown copies, JSON-LD schema, and a sitemap
```
How can I resolve this? If you propose a fix, please make it concise.| - **freshness signals** outside your control (independent news, blog roundups, podcasts) | ||
| </Aside> | ||
|
|
||
| Think of aeo.js as a strong foundation — necessary but not sufficient. For full AEO coverage, pair it with the off-site work above: PR, community engagement, and being mentioned where your customers research. |
There was a problem hiding this comment.
| Think of aeo.js as a strong foundation — necessary but not sufficient. For full AEO coverage, pair it with the off-site work above: PR, community engagement, and being mentioned where your customers research. | |
| Think of aeo.js as a strong foundation — necessary but not sufficient. For full AEO coverage, pair it with the off-site work above: public relations, community engagement, and being mentioned where your customers research. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: website/src/content/docs/getting-started/introduction.mdx
Line: 57
Comment:
In a developer-facing doc, "PR" is almost universally read as "pull request." Spelling out "public relations" avoids any momentary confusion for the target audience.
```suggestion
Think of aeo.js as a strong foundation — necessary but not sufficient. For full AEO coverage, pair it with the off-site work above: public relations, community engagement, and being mentioned where your customers research.
```
How can I resolve this? If you propose a fix, please make it concise.![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-only addition of a scope section using standard Starlight Asides.
Extended reasoning...
Overview
This PR adds a new "Scope" section to website/src/content/docs/getting-started/introduction.mdx clarifying what aeo.js does and does not influence (on-site vs off-site AEO). It also adds the required import { Aside } from '@astrojs/starlight/components' and uses two standard Starlight Aside components (note + caution).
Security risks
None. This is a documentation-only change to a single MDX page. No code paths, build configuration, dependencies, or runtime behavior are affected.
Level of scrutiny
Minimal. Pure content addition to the docs site using an already-established component pattern (Starlight Asides). The import statement is correct, MDX syntax is valid, and the PR description confirms bun run build succeeds with 21 clean pages.
Other factors
The change directly closes issue #53 with the requested scope clarification, follows the project's existing documentation style, and Vercel preview deployed successfully. No reviewer comments are outstanding.
1 participant
Summary
Implements #53 from @KimHyeongRae0 — adds an explicit Scope section to the introduction page so users understand which half of AEO aeo.js owns vs which half lives off-site.
What changed
website/src/content/docs/getting-started/introduction.mdxgains a new "## Scope: what aeo.js does and doesn't influence" section, placed between "How it works" and "Supported Frameworks". Two Starlight Asides:What aeo.js does well (type: note):
What aeo.js cannot influence (type: caution):
Closes with a "necessary but not sufficient" framing so users pair aeo.js with the off-site work for full coverage.
Test plan
bun run build— 21 pages, clean/getting-started/introduction/in the dev server and verify the Asides render correctlyCloses #53
🤖 Generated with Claude Code