@docsector/docsector-reader 1.0.0 → 1.1.0

package/README.md

@@ -26,7 +26,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🤖 **LLM Bot Detection** — Automatically serves raw Markdown to known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, and others)
 - 🗺️ **Sitemap Generation** — Automatic `sitemap.xml` generation at build time with all page URLs (requires `siteUrl` in config)
 - 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 23 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, etc.)
-- 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
+- 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
 - 🔌 **MCP Server** — Auto-generated [MCP](https://modelcontextprotocol.io) server at `/mcp` for AI assistant integration (Claude Desktop, VS Code, etc.)
 - 📄 **llms.txt / llms-full.txt** — Auto-generated [llms.txt](https://llmstxt.org) index and full-content file for LLM discovery (requires `siteUrl` in config)
 
@@ -48,6 +48,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📊 **Translation Progress** — Automatic translation percentage based on header coverage
 - 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
+- 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
 
 ---
@@ -162,6 +163,7 @@ Docsector Reader adds homepage `Link` response headers at build time for agent d
 
 Default relations emitted on homepage (`/` and `/index.html`):
 
+- `rel="api-catalog"` → `</.well-known/api-catalog>`
 - `rel="service-doc"` → `</>`
 - `rel="service-desc"` → `</mcp>` (only when `mcp` is enabled)
 - `rel="describedby"` → `</llms.txt>` (only when `siteUrl` is configured, i.e. `llms.txt` is generated)
@@ -169,6 +171,7 @@ Default relations emitted on homepage (`/` and `/index.html`):
 Generated in:
 
 - `dist/spa/_headers`
+- `dist/spa/.well-known/api-catalog` (Linkset JSON)
 
 ### Optional configuration
 
@@ -178,9 +181,19 @@ export default {
 
   linkHeaders: {
     enabled: true,
+    apiCatalog: '/.well-known/api-catalog',
     serviceDoc: '/',
     serviceDesc: '/mcp',
     describedBy: '/llms.txt'
+  },
+
+  apiCatalog: {
+    enabled: true,
+    path: '/.well-known/api-catalog',
+    items: [
+      '/mcp',
+      'https://api.example.com/openapi.json'
+    ]
   }
 }
 ```
@@ -192,6 +205,7 @@ Set any target to `null` or `false` to disable that relation.
 ```bash
 npx docsector build
 cat dist/spa/_headers
+cat dist/spa/.well-known/api-catalog
 ```
 
 Or scan discoverability:
@@ -343,11 +357,18 @@ export default {
 
   linkHeaders: {
     enabled: true,
+    apiCatalog: '/.well-known/api-catalog',
     serviceDoc: '/',
     serviceDesc: '/mcp',
     describedBy: '/llms.txt'
   },
 
+  apiCatalog: {
+    enabled: true,
+    path: '/.well-known/api-catalog',
+    items: []
+  },
+
   languages: [
     { image: '/images/flags/united-states-of-america.png', label: 'English (US)', value: 'en-US' },
     { image: '/images/flags/brazil.png', label: 'Português (BR)', value: 'pt-BR' }

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '1.0.0'
+const VERSION = '1.1.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -136,11 +136,19 @@ export default {
   // @ Homepage Link headers for agent discovery (optional)
   // linkHeaders: {
   //   enabled: true,
+  //   apiCatalog: '/.well-known/api-catalog',
   //   serviceDoc: '/',
   //   serviceDesc: '/mcp',
   //   describedBy: '/llms.txt'
   // },
 
+  // @ API catalog artifact (RFC 9727) (optional)
+  // apiCatalog: {
+  //   enabled: true,
+  //   path: '/.well-known/api-catalog',
+  //   items: ['/mcp']
+  // },
+
   // @ Languages
   languages: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/src/index.js

@@ -47,8 +47,13 @@
  * @param {Object} [config.linkHeaders] - Homepage Link headers for agent discovery
  * @param {boolean} [config.linkHeaders.enabled=true] - Enables homepage Link headers generation
  * @param {string|null|false} [config.linkHeaders.serviceDoc='/'] - Target URI for rel="service-doc"
+ * @param {string|null|false} [config.linkHeaders.apiCatalog='/.well-known/api-catalog'] - Target URI for rel="api-catalog"
  * @param {string|null|false} [config.linkHeaders.serviceDesc='/mcp'] - Target URI for rel="service-desc" (only emitted when MCP is enabled)
  * @param {string|null|false} [config.linkHeaders.describedBy='/llms.txt'] - Target URI for rel="describedby" (only emitted when llms.txt is generated)
+ * @param {Object} [config.apiCatalog] - API catalog generation settings
+ * @param {boolean} [config.apiCatalog.enabled=true] - Enables generation of API catalog artifact
+ * @param {string} [config.apiCatalog.path='/.well-known/api-catalog'] - Output URI path for API catalog artifact
+ * @param {Array<string|{href: string}>} [config.apiCatalog.items=[]] - Additional API endpoint links to include as item relations
  * @returns {Object} Resolved Docsector configuration
  */
 export function createDocsector (config = {}) {
@@ -93,9 +98,17 @@ export function createDocsector (config = {}) {
     linkHeaders: {
       enabled: true,
       serviceDoc: '/',
+      apiCatalog: '/.well-known/api-catalog',
       serviceDesc: '/mcp',
       describedBy: '/llms.txt',
       ...config.linkHeaders
+    },
+
+    apiCatalog: {
+      enabled: true,
+      path: '/.well-known/api-catalog',
+      items: [],
+      ...config.apiCatalog
     }
   }
 }

package/src/quasar.factory.js

@@ -679,6 +679,13 @@ function createMarkdownBuildPlugin (projectRoot) {
           homepageLinks.push({ rel: 'service-doc', href: serviceDocHref })
         }
 
+        const apiCatalogHref = linkHeadersConfig.apiCatalog === undefined
+          ? '/.well-known/api-catalog'
+          : linkHeadersConfig.apiCatalog
+        if (apiCatalogHref) {
+          homepageLinks.push({ rel: 'api-catalog', href: apiCatalogHref })
+        }
+
         const serviceDescHref = linkHeadersConfig.serviceDesc === undefined
           ? '/mcp'
           : linkHeadersConfig.serviceDesc
@@ -694,19 +701,106 @@ function createMarkdownBuildPlugin (projectRoot) {
         }
 
         if (homepageLinks.length > 0) {
-          const linkLines = homepageLinks.map(({ rel, href }) => `  Link: <${href}>; rel="${rel}"`).join('\n')
-          const homepageRule = ['/','/index.html']
-            .map(path => `${path}\n${linkLines}`)
-            .join('\n\n') + '\n'
-
           const currentHeaders = readFileSync(headersPath, 'utf-8')
-          const hasAgentLinks = currentHeaders.includes('rel="service-doc"')
-            || currentHeaders.includes('rel="service-desc"')
-            || currentHeaders.includes('rel="describedby"')
+          const missingHomepageLinks = homepageLinks.filter(({ rel }) => !currentHeaders.includes(`rel="${rel}"`))
+
+          if (missingHomepageLinks.length > 0) {
+            const linkLines = missingHomepageLinks
+              .map(({ rel, href }) => `  Link: <${href}>; rel="${rel}"`)
+              .join('\n')
+            const homepageRule = ['/', '/index.html']
+              .map(path => `${path}\n${linkLines}`)
+              .join('\n\n') + '\n'
 
-          if (!hasAgentLinks) {
             writeFileSync(headersPath, currentHeaders.trimEnd() + '\n\n' + homepageRule)
-            console.log(`\x1b[36m[docsector]\x1b[0m Added homepage Link headers for agent discovery`)
+            console.log(`\x1b[36m[docsector]\x1b[0m Added homepage Link headers for agent discovery (${missingHomepageLinks.length} relation(s))`)
+          }
+        }
+
+        // Generate /.well-known/api-catalog Linkset document (RFC 9727)
+        const apiCatalogConfig = config.apiCatalog || {}
+        const apiCatalogEnabled = apiCatalogConfig.enabled !== false
+        const apiCatalogPath = (apiCatalogConfig.path || apiCatalogHref || '/.well-known/api-catalog')
+
+        const toUrl = (href) => {
+          if (!href) return null
+          if (/^https?:\/\//i.test(href)) return href
+          const normalizedHref = href.startsWith('/') ? href : `/${href}`
+          return siteUrl ? `${siteUrl}${normalizedHref}` : normalizedHref
+        }
+
+        const normalizeLocalPath = (href) => {
+          if (!href || /^https?:\/\//i.test(href)) return null
+          const path = href.startsWith('/') ? href.slice(1) : href
+          return path || null
+        }
+
+        if (apiCatalogEnabled && apiCatalogPath) {
+          const catalogDistPath = normalizeLocalPath(apiCatalogPath)
+
+          if (catalogDistPath) {
+            const catalogHref = apiCatalogPath.startsWith('/') ? apiCatalogPath : `/${apiCatalogPath}`
+            const catalogEntry = {
+              anchor: toUrl(catalogHref)
+            }
+
+            const catalogServiceDoc = toUrl(serviceDocHref)
+            if (catalogServiceDoc) {
+              catalogEntry['service-doc'] = [{ href: catalogServiceDoc }]
+            }
+
+            const catalogServiceDesc = config.mcp ? toUrl(serviceDescHref) : null
+            if (catalogServiceDesc) {
+              catalogEntry['service-desc'] = [{ href: catalogServiceDesc }]
+            }
+
+            const catalogDescribedBy = siteUrl ? toUrl(describedByHref) : null
+            if (catalogDescribedBy) {
+              catalogEntry.describedby = [{ href: catalogDescribedBy }]
+            }
+
+            const customItems = Array.isArray(apiCatalogConfig.items)
+              ? apiCatalogConfig.items
+              : []
+            const itemHrefs = new Set()
+
+            if (catalogServiceDesc) {
+              itemHrefs.add(catalogServiceDesc)
+            }
+
+            for (const item of customItems) {
+              if (typeof item === 'string') {
+                const href = toUrl(item)
+                if (href) itemHrefs.add(href)
+                continue
+              }
+
+              if (item && typeof item === 'object' && typeof item.href === 'string') {
+                const href = toUrl(item.href)
+                if (href) itemHrefs.add(href)
+              }
+            }
+
+            if (itemHrefs.size > 0) {
+              catalogEntry.item = [...itemHrefs].map(href => ({ href }))
+            }
+
+            const catalogDir = resolve(distDir, catalogDistPath, '..')
+            mkdirSync(catalogDir, { recursive: true })
+            writeFileSync(
+              resolve(distDir, catalogDistPath),
+              JSON.stringify({ linkset: [catalogEntry] }, null, 2) + '\n'
+            )
+            console.log(`\x1b[36m[docsector]\x1b[0m Generated ${catalogHref}`)
+
+            const headersWithLinks = readFileSync(headersPath, 'utf-8')
+            if (!headersWithLinks.includes(catalogHref)) {
+              const apiCatalogHeaders = `${catalogHref}\n  Content-Type: application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"\n`
+              writeFileSync(headersPath, headersWithLinks.trimEnd() + '\n\n' + apiCatalogHeaders)
+              console.log(`\x1b[36m[docsector]\x1b[0m Added _headers rule for ${catalogHref}`)
+            }
+          } else {
+            console.warn(`\x1b[33m[docsector]\x1b[0m Skipped API catalog generation: path must be a local URI path, got \"${apiCatalogPath}\"`)
           }
         }
       }