Skip to content

Commit 8d3f60c

Browse files
dacharycdacharyc
authored
Merge pull request #14 from agent-ecosystem/add-docs-site
Add docs site
2 parents fd4674a + c2c68cc commit 8d3f60c

68 files changed

Lines changed: 5651 additions & 331 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,6 @@ node_modules/
22
dist/
33
coverage/
44
*.tsbuildinfo
5+
docs/.vitepress/cache/
6+
docs/deploy
57
.DS_Store

‎README.md‎

Lines changed: 25 additions & 329 deletions
Large diffs are not rendered by default.

‎docs/.vitepress/config.ts‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
import { defineConfig } from 'vitepress';
2+
3+
export default defineConfig({
4+
title: 'AFDocs',
5+
description: 'Test your documentation site against the Agent-Friendly Documentation Spec',
6+
7+
sitemap: {
8+
hostname: 'https://afdocs.dev',
9+
},
10+
11+
head: [
12+
['link', { rel: 'icon', type: 'image/x-icon', href: '/favicons/favicon.ico' }],
13+
[
14+
'link',
15+
{ rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicons/favicon-32x32.png' },
16+
],
17+
[
18+
'link',
19+
{ rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicons/favicon-16x16.png' },
20+
],
21+
[
22+
'link',
23+
{ rel: 'apple-touch-icon', sizes: '180x180', href: '/favicons/apple-icon-180x180.png' },
24+
],
25+
],
26+
27+
themeConfig: {
28+
siteTitle: 'AFDocs',
29+
logo: {
30+
light: '/logos/afdoc_logo_light.svg',
31+
dark: '/logos/afdoc_logo_dark.svg',
32+
},
33+
34+
nav: [
35+
{ text: 'Guide', link: '/what-is-agent-score' },
36+
{ text: 'Checks', link: '/checks/' },
37+
{ text: 'Reference', link: '/reference/cli' },
38+
],
39+
40+
sidebar: [
41+
{
42+
text: 'The Score',
43+
items: [
44+
{ text: 'What Is the Agent Score?', link: '/what-is-agent-score' },
45+
{
46+
text: 'Why Agent-Friendliness Matters',
47+
link: '/why-agent-friendliness-matters',
48+
},
49+
{
50+
text: 'Score Calculation',
51+
link: '/agent-score-calculation',
52+
},
53+
{
54+
text: 'Interaction Diagnostics',
55+
link: '/interaction-diagnostics',
56+
},
57+
],
58+
},
59+
{
60+
text: 'Get Started',
61+
items: [
62+
{ text: 'Quick Start', link: '/quick-start' },
63+
{ text: 'Run Locally', link: '/run-locally' },
64+
{ text: 'Improve Your Score', link: '/improve-your-score' },
65+
{ text: 'CI Integration', link: '/ci-integration' },
66+
],
67+
},
68+
{
69+
text: 'Checks Reference',
70+
items: [
71+
{ text: 'Overview', link: '/checks/' },
72+
{
73+
text: 'Content Discoverability',
74+
link: '/checks/content-discoverability',
75+
},
76+
{
77+
text: 'Markdown Availability',
78+
link: '/checks/markdown-availability',
79+
},
80+
{ text: 'Page Size', link: '/checks/page-size' },
81+
{ text: 'Content Structure', link: '/checks/content-structure' },
82+
{ text: 'URL Stability', link: '/checks/url-stability' },
83+
{ text: 'Observability', link: '/checks/observability' },
84+
{ text: 'Authentication', link: '/checks/authentication' },
85+
],
86+
},
87+
{
88+
text: 'API Reference',
89+
items: [
90+
{ text: 'CLI', link: '/reference/cli' },
91+
{ text: 'Programmatic API', link: '/reference/programmatic-api' },
92+
{ text: 'Scoring API', link: '/reference/scoring-api' },
93+
{ text: 'Config File', link: '/reference/config-file' },
94+
],
95+
},
96+
{
97+
text: 'About',
98+
items: [{ text: 'About AFDocs', link: '/about' }],
99+
},
100+
],
101+
102+
socialLinks: [
103+
{
104+
icon: 'github',
105+
link: 'https://github.com/agent-ecosystem/afdocs',
106+
},
107+
],
108+
109+
editLink: {
110+
pattern: 'https://github.com/agent-ecosystem/afdocs/edit/main/docs/:path',
111+
},
112+
113+
footer: {
114+
message: 'Released under the MIT License.',
115+
},
116+
},
117+
});

‎docs/.vitepress/theme/HomeLayout.vue‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<script setup>
2+
import DefaultTheme from 'vitepress/theme';
3+
import HeroScorecard from './components/HeroScorecard.vue';
4+
import LlmsDirective from './components/LlmsDirective.vue';
5+
</script>
6+
7+
<template>
8+
<DefaultTheme.Layout>
9+
<template #home-hero-image>
10+
<HeroScorecard />
11+
</template>
12+
<template #layout-top>
13+
<LlmsDirective />
14+
</template>
15+
</DefaultTheme.Layout>
16+
</template>

‎docs/.vitepress/theme/components/HeroScorecard.vue‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<template>
2+
<div class="hero-scorecard">
3+
<pre><code><span class="header">Agent-Friendly Docs Scorecard</span>
4+
<span class="divider">==============================</span>
5+
6+
Overall Score: <span class="score-c">72 / 100 (C)</span>
7+
8+
Category Scores:
9+
Content Discoverability <span class="score-c">72 / 100 (C)</span>
10+
Markdown Availability <span class="score-d">60 / 100 (D)</span>
11+
Page Size &amp; Truncation Risk <span class="score-f">45 / 100 (F)</span>
12+
Content Structure <span class="score-b">82 / 100 (B)</span>
13+
URL Stability <span class="score-a">93 / 100 (A)</span>
14+
Observability <span class="score-c">71 / 100 (C)</span>
15+
Authentication <span class="score-a">100 / 100 (A+)</span></code></pre>
16+
</div>
17+
</template>
18+
19+
<style scoped>
20+
.hero-scorecard {
21+
width: 100%;
22+
max-width: 440px;
23+
margin: 0 auto;
24+
}
25+
26+
.hero-scorecard pre {
27+
background: var(--vp-c-bg-soft);
28+
border: 1px solid var(--vp-c-border);
29+
border-radius: 12px;
30+
padding: 20px 24px;
31+
font-size: 13px;
32+
line-height: 1.6;
33+
overflow-x: auto;
34+
margin: 0;
35+
}
36+
37+
.hero-scorecard code {
38+
font-family: var(--vp-font-family-mono);
39+
color: var(--vp-c-text-1);
40+
}
41+
42+
.header {
43+
font-weight: 700;
44+
color: var(--vp-c-brand-1);
45+
}
46+
47+
.divider {
48+
color: var(--vp-c-text-3);
49+
}
50+
51+
.score-a {
52+
color: var(--vp-c-green-1);
53+
font-weight: 600;
54+
}
55+
56+
.score-b {
57+
color: var(--vp-c-green-2);
58+
font-weight: 600;
59+
}
60+
61+
.score-c {
62+
color: var(--vp-c-yellow-1);
63+
font-weight: 600;
64+
}
65+
66+
.score-d {
67+
color: var(--vp-c-yellow-2);
68+
font-weight: 600;
69+
}
70+
71+
.score-f {
72+
color: var(--vp-c-red-1);
73+
font-weight: 600;
74+
}
75+
</style>

‎docs/.vitepress/theme/components/LlmsDirective.vue‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<template>
2+
<div
3+
class="sr-only"
4+
style="
5+
position: absolute;
6+
width: 1px;
7+
height: 1px;
8+
padding: 0;
9+
margin: -1px;
10+
overflow: hidden;
11+
clip: rect(0, 0, 0, 0);
12+
white-space: nowrap;
13+
border: 0;
14+
"
15+
>
16+
For AI agents: a documentation index is available at /llms.txt — markdown versions of all pages
17+
are available by appending .md to any URL path.
18+
</div>
19+
</template>

‎docs/.vitepress/theme/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import DefaultTheme from 'vitepress/theme';
2+
import HomeLayout from './HomeLayout.vue';
3+
4+
export default {
5+
extends: DefaultTheme,
6+
Layout: HomeLayout,
7+
};

‎docs/about.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# About AFDocs
2+
3+
<div class="about-intro">
4+
<div class="about-text">
5+
6+
AFDocs is an open-source tool that tests documentation sites against the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). The spec defines what makes documentation accessible to AI coding agents, based on observed behavior across real agent platforms. AFDocs automates those observations into 22 checks that produce a score and actionable fix suggestions.
7+
8+
</div>
9+
<div class="about-logo">
10+
<img class="light-only" src="/logos/afdoc_logo_light.svg" alt="afdocs logo" width="200" height="200">
11+
<img class="dark-only" src="/logos/afdoc_logo_dark.svg" alt="afdocs logo" width="200" height="200">
12+
</div>
13+
</div>
14+
15+
## The Agent-Friendly Documentation Spec
16+
17+
The [Agent-Friendly Documentation Spec](https://agentdocsspec.com) is the foundation for everything AFDocs checks. It documents:
18+
19+
- How agents actually discover, fetch, and consume documentation
20+
- What fails in practice (truncation, empty SPA shells, auth gates, broken redirects)
21+
- What works (llms.txt, markdown availability, content negotiation, proper status codes)
22+
- Specific agent behaviors observed across Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, and others
23+
24+
The spec is maintained at [github.com/agent-ecosystem/agent-docs-spec](https://github.com/agent-ecosystem/agent-docs-spec) and is open for contributions.
25+
26+
AFDocs implements spec v0.3.0 (2026-03-31).
27+
28+
## Status
29+
30+
AFDocs is in early development (0.x). Check IDs, CLI flags, and output formats may change between minor versions. The tool is usable today, but don't build automation against specific output details until 1.0.
31+
32+
## Contributing
33+
34+
AFDocs is developed at [github.com/agent-ecosystem/afdocs](https://github.com/agent-ecosystem/afdocs). Issues, bug reports, and pull requests are welcome.
35+
36+
If you've tested AFDocs against your docs site and found a check that doesn't accurately reflect agent behavior, or a failure mode that isn't covered, that's especially valuable feedback. The checks are based on observed behavior, and more observations make them better.
37+
38+
## License
39+
40+
MIT
41+
42+
<style>
43+
.about-intro {
44+
display: flex;
45+
align-items: center;
46+
gap: 4.5rem;
47+
}
48+
.about-text {
49+
flex: 1;
50+
}
51+
.about-logo {
52+
flex-shrink: 0;
53+
}
54+
.dark .light-only {
55+
display: none;
56+
}
57+
.dark-only {
58+
display: none;
59+
}
60+
.dark .dark-only {
61+
display: block;
62+
}
63+
@media (max-width: 768px) {
64+
.about-intro {
65+
flex-direction: column;
66+
}
67+
.about-logo {
68+
order: -1;
69+
text-align: center;
70+
}
71+
}
72+
</style>

0 commit comments

Comments
 (0)