starred/herdr
1
0
Fork 0
mirror of https://github.com/herdrdev/herdr.git synced 2026-09-22 16:01:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): link agents to config reference data

Browse Source
This commit is contained in:
Ogulcan Celik
2026-08-18 00:31:15 +03:00
parent 76211757ec
commit b3166d794e
2 changed files with 35 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/scripts/check-built-docs.mjs
+22 -7
View File
@@ -82,23 +82,35 @@ if (!currentDocs?.tag || !currentDocs.source) {
}
const stableRawRoot = `https://raw.githubusercontent.com/herdrdev/herdr/${currentDocs.tag}`;
const stableRawBase = `${stableRawRoot}/${currentDocs.source}`;
const previewRawBase = `https://raw.githubusercontent.com/herdrdev/herdr/${versions.preview.commit}/docs/next/website/src/content/docs`;
const stableConfigReferenceUrl = `${stableRawRoot}/${currentDocs.source.replace(/\/content\/docs$/, '/data/config-reference.json')}`;
const previewRawRoot = `https://raw.githubusercontent.com/herdrdev/herdr/${versions.preview.commit}`;
const previewRawBase = `${previewRawRoot}/docs/next/website/src/content/docs`;
const previewConfigReferenceUrl = `${previewRawRoot}/docs/next/website/src/data/config-reference.json`;
assertIncludes(llmsIndex, `Current stable release: ${versions.current}.`);
assertIncludes(llmsIndex, `${stableRawBase}/quick-start.mdx`);
assertIncludes(
llmsIndex,
`${stableRawRoot}/${currentDocs.source.replace(/\/content\/docs$/, '/data/config-reference.json')}`,
);
assertIncludes(llmsIndex, `- [Config reference](${stableConfigReferenceUrl})`);
assertIncludes(llmsIndex, '## Using the config reference');
assertIncludes(llmsIndex, "jq --arg key 'ui.sidebar_width'");
if (llmsIndex.includes(`${stableRawBase}/config-reference.mdx`)) {
throw new Error('llms.txt must link to config reference data instead of the unrendered MDX component');
}
assertIncludes(llmsIndex, 'https://herdr.dev/llms-small.txt');
assertIncludes(llmsIndex, 'https://herdr.dev/llms-full.txt');
assertIncludes(llmsIndex, 'https://herdr.dev/agent-guide.md');
assertIncludes(llmsIndex, 'https://herdr.dev/llms-preview.txt');
assertIncludes(llmsPreview, `Active preview build: ${versions.preview.build_id}`);
assertIncludes(llmsPreview, `${previewRawBase}/quick-start.mdx`);
assertIncludes(llmsPreview, `- [Config reference](${previewConfigReferenceUrl})`);
if (llmsPreview.includes(`${previewRawBase}/config-reference.mdx`)) {
throw new Error('llms-preview.txt must link to config reference data instead of the unrendered MDX component');
}
assertIncludes(llmsPreview, 'https://herdr.dev/llms.txt');
const stablePageLinks = llmsIndex
.split('\n')
.filter((line) => line.includes(`](${stableRawBase}/`));
.filter(
(line) =>
line.includes(`](${stableRawBase}/`) || line.includes(`](${stableConfigReferenceUrl})`),
);
if (stablePageLinks.length !== versions.scopes.stable.locales.root.length) {
throw new Error(
`llms.txt lists ${stablePageLinks.length} stable pages, expected ${versions.scopes.stable.locales.root.length}`,
@@ -106,7 +118,10 @@ if (stablePageLinks.length !== versions.scopes.stable.locales.root.length) {
}
const previewPageLinks = llmsPreview
.split('\n')
.filter((line) => line.includes(`](${previewRawBase}/`));
.filter(
(line) =>
line.includes(`](${previewRawBase}/`) || line.includes(`](${previewConfigReferenceUrl})`),
);
if (previewPageLinks.length !== versions.scopes.preview.locales.root.length) {
throw new Error(
`llms-preview.txt lists ${previewPageLinks.length} preview pages, expected ${versions.scopes.preview.locales.root.length}`,
website/scripts/prepare-docs.mjs
+13 -7
View File
@@ -261,24 +261,30 @@ async function writeAgentDocsIndex({
if (configDataPath === repositoryPath) {
throw new Error(`cannot derive config reference path from ${repositoryPath}`);
}
const configDataUrl = `${rawRoot}/${configDataPath}`;
const lines = [
`# ${heading}`,
'',
`> ${summary}`,
'',
'Open only the pages relevant to the current task. Links return raw MDX from the exact documented source revision. For another topic, return to this index instead of following `/docs/` links inside a page, which serve human-facing HTML.',
'Open only the pages relevant to the current task. Links return raw source files from the exact documented revision. For another topic, return to this index instead of following `/docs/` links inside a page, which serve human-facing HTML.',
'',
'## Documentation',
'',
...pages.map(
({ title, description, path }) =>
`- [${title}](${rawBase}/${path})${description ? `: ${description}` : ''}`,
),
...pages.map(({ title, description, path }) => {
const url = /^config-reference\.mdx?$/.test(path) ? configDataUrl : `${rawBase}/${path}`;
return `- [${title}](${url})${description ? `: ${description}` : ''}`;
}),
'',
'## Generated reference data',
'## Using the config reference',
'',
`- [Config reference data](${rawRoot}/${configDataPath}): every canonical config.toml key, type, default, and description`,
'The Config reference link above is a large structured JSON file. When command tools are available, fetch and filter it by exact key instead of loading the whole file:',
'',
'```sh',
`curl -fsSL '${configDataUrl}' | jq --arg key 'ui.sidebar_width' \\`,
" '.sections[].keys[] | select(.key == $key)'",
'```',
'',
...extraSections,
'',