feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
Steve Yegge
202
website/docusaurus.config.ts
Normal file
202
website/docusaurus.config.ts
Normal file
@@ -0,0 +1,202 @@
|
||||
import {themes as prismThemes} from 'prism-react-renderer';
|
||||
import type {Config} from '@docusaurus/types';
|
||||
import type * as Preset from '@docusaurus/preset-classic';
|
||||
|
||||
// Environment-based URL configuration for fork flexibility
|
||||
// SITE_URL: Full URL (e.g., "https://myuser.github.io/beads" or "https://myuser.github.io")
|
||||
// ORG_NAME: GitHub organization/user name (defaults to "steveyegge")
|
||||
// PROJECT_NAME: Repository/project name (defaults to "beads")
|
||||
const orgName = process.env.ORG_NAME || 'steveyegge';
|
||||
const projectName = process.env.PROJECT_NAME || 'beads';
|
||||
const siteUrlEnv = process.env.SITE_URL || `https://${orgName}.github.io/${projectName}`;
|
||||
|
||||
// Parse SITE_URL into origin (url) and pathname (baseUrl)
|
||||
function parseUrl(fullUrl: string): { origin: string; baseUrl: string } {
|
||||
try {
|
||||
const parsed = new URL(fullUrl);
|
||||
const baseUrl = parsed.pathname === '/' ? `/${projectName}/` :
|
||||
parsed.pathname.endsWith('/') ? parsed.pathname : `${parsed.pathname}/`;
|
||||
return { origin: parsed.origin, baseUrl };
|
||||
} catch {
|
||||
return { origin: `https://${orgName}.github.io`, baseUrl: `/${projectName}/` };
|
||||
}
|
||||
}
|
||||
|
||||
const { origin: siteUrl, baseUrl } = parseUrl(siteUrlEnv);
|
||||
|
||||
const config: Config = {
|
||||
title: 'Beads Documentation',
|
||||
tagline: 'Git-backed issue tracker for AI-supervised coding workflows',
|
||||
favicon: 'img/favicon.svg',
|
||||
|
||||
// Enable Mermaid diagrams in markdown
|
||||
markdown: {
|
||||
mermaid: true,
|
||||
},
|
||||
themes: ['@docusaurus/theme-mermaid'],
|
||||
|
||||
// future: {
|
||||
// v4: true,
|
||||
// },
|
||||
|
||||
// GitHub Pages deployment (environment-configurable)
|
||||
url: siteUrl,
|
||||
baseUrl: baseUrl,
|
||||
organizationName: orgName,
|
||||
projectName: projectName,
|
||||
trailingSlash: false,
|
||||
|
||||
onBrokenLinks: 'warn',
|
||||
|
||||
markdown: {
|
||||
hooks: {
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
},
|
||||
},
|
||||
|
||||
i18n: {
|
||||
defaultLocale: 'en',
|
||||
locales: ['en'],
|
||||
},
|
||||
|
||||
// Meta tags for AI agents (uses baseUrl for fork flexibility)
|
||||
// Order: ai-terms (discovery), llms-full (complete docs), llms (index)
|
||||
headTags: [
|
||||
{
|
||||
tagName: 'meta',
|
||||
attributes: {
|
||||
name: 'ai-terms',
|
||||
content: `Load ${baseUrl}llms-full.txt (<50K tokens) for complete documentation, ${baseUrl}llms.txt for index`,
|
||||
},
|
||||
},
|
||||
{
|
||||
tagName: 'meta',
|
||||
attributes: {
|
||||
name: 'llms-full',
|
||||
content: `${baseUrl}llms-full.txt`,
|
||||
},
|
||||
},
|
||||
{
|
||||
tagName: 'meta',
|
||||
attributes: {
|
||||
name: 'llms',
|
||||
content: `${baseUrl}llms.txt`,
|
||||
},
|
||||
},
|
||||
],
|
||||
|
||||
presets: [
|
||||
[
|
||||
'classic',
|
||||
{
|
||||
docs: {
|
||||
routeBasePath: '/', // Docs as homepage
|
||||
sidebarPath: './sidebars.ts',
|
||||
editUrl: `https://github.com/${orgName}/${projectName}/tree/docs/docusaurus-site/website/`,
|
||||
showLastUpdateTime: true,
|
||||
},
|
||||
blog: false, // Disable blog
|
||||
theme: {
|
||||
customCss: './src/css/custom.css',
|
||||
},
|
||||
} satisfies Preset.Options,
|
||||
],
|
||||
],
|
||||
|
||||
themeConfig: {
|
||||
// No social card image - using default
|
||||
colorMode: {
|
||||
defaultMode: 'dark',
|
||||
respectPrefersColorScheme: true,
|
||||
},
|
||||
navbar: {
|
||||
title: 'Beads',
|
||||
logo: {
|
||||
alt: 'Beads Logo',
|
||||
src: 'img/logo.svg',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: 'docSidebar',
|
||||
sidebarId: 'docsSidebar',
|
||||
position: 'left',
|
||||
label: 'Documentation',
|
||||
},
|
||||
{
|
||||
href: `pathname://${baseUrl}llms.txt`,
|
||||
label: 'llms.txt',
|
||||
position: 'right',
|
||||
},
|
||||
{
|
||||
href: `https://github.com/${orgName}/${projectName}`,
|
||||
label: 'GitHub',
|
||||
position: 'right',
|
||||
},
|
||||
],
|
||||
},
|
||||
footer: {
|
||||
style: 'dark',
|
||||
links: [
|
||||
{
|
||||
title: 'Documentation',
|
||||
items: [
|
||||
{
|
||||
label: 'Getting Started',
|
||||
to: '/getting-started/installation',
|
||||
},
|
||||
{
|
||||
label: 'CLI Reference',
|
||||
to: '/cli-reference',
|
||||
},
|
||||
{
|
||||
label: 'Workflows',
|
||||
to: '/workflows/molecules',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Integrations',
|
||||
items: [
|
||||
{
|
||||
label: 'Claude Code',
|
||||
to: '/integrations/claude-code',
|
||||
},
|
||||
{
|
||||
label: 'MCP Server',
|
||||
to: '/integrations/mcp-server',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Resources',
|
||||
items: [
|
||||
{
|
||||
label: 'GitHub',
|
||||
href: `https://github.com/${orgName}/${projectName}`,
|
||||
},
|
||||
{
|
||||
label: 'llms.txt',
|
||||
href: `pathname://${baseUrl}llms.txt`,
|
||||
},
|
||||
{
|
||||
label: 'npm Package',
|
||||
href: 'https://www.npmjs.com/package/@beads/bd',
|
||||
},
|
||||
{
|
||||
label: 'PyPI (MCP)',
|
||||
href: 'https://pypi.org/project/beads-mcp/',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Steve Yegge. Built with Docusaurus.`,
|
||||
},
|
||||
prism: {
|
||||
theme: prismThemes.github,
|
||||
darkTheme: prismThemes.dracula,
|
||||
additionalLanguages: ['bash', 'json', 'toml', 'go'],
|
||||
},
|
||||
} satisfies Preset.ThemeConfig,
|
||||
};
|
||||
|
||||
export default config;
|
||||
Reference in New Issue
Block a user