@vkuttyp/docus 5.4.6

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@vkuttyp/docus",
+  "description": "Nuxt layer for Docus documentation theme",
+  "version": "5.4.6",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuxt-content/docus.git"
+  },
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "app",
+    "i18n",
+    "content.config.ts",
+    "modules",
+    "nuxt.config.ts",
+    "nuxt.schema.ts",
+    "server",
+    "utils",
+    "README.md"
+  ],
+  "dependencies": {
+    "@iconify-json/lucide": "^1.2.81",
+    "@iconify-json/simple-icons": "^1.2.63",
+    "@iconify-json/vscode-icons": "^1.2.37",
+    "@nuxt/content": "^3.9.0",
+    "@nuxt/image": "^2.0.0",
+    "@nuxt/kit": "^4.2.2",
+    "@nuxt/ui": "^4.3.0",
+    "@nuxtjs/i18n": "^10.2.1",
+    "@nuxtjs/mcp-toolkit": "^0.5.2",
+    "@nuxtjs/mdc": "^0.19.1",
+    "@nuxtjs/robots": "^5.6.7",
+    "@vueuse/core": "^13.9.0",
+    "defu": "^6.1.4",
+    "exsolve": "^1.0.8",
+    "git-url-parse": "^16.1.0",
+    "minimark": "^0.2.0",
+    "motion-v": "^1.7.4",
+    "nuxt-llms": "^0.1.3",
+    "nuxt-og-image": "^5.1.13",
+    "pkg-types": "^2.3.0",
+    "scule": "^1.3.0",
+    "tailwindcss": "^4.1.18",
+    "ufo": "^1.6.1",
+    "zod": "^4.2.1",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "12.x",
+    "nuxt": "4.x"
+  }
+}

package/server/mcp/tools/get-page.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections } from '@nuxt/content'
+import { getAvailableLocales, getCollectionFromPath } from '../../utils/content'
+import { inferSiteURL } from '../../../utils/meta'
+
+export default defineMcpTool({
+  description: `Retrieves the full content and details of a specific documentation page.
+
+WHEN TO USE: Use this tool when you know the EXACT path to a documentation page. Common use cases:
+- User asks for a specific page: "Show me the getting started guide" → /en/getting-started/installation
+- User asks about a known topic with a dedicated page
+- You found a relevant path from list-pages and want the full content
+- User references a specific section or guide they want to read
+
+WHEN NOT TO USE: If you don't know the exact path and need to search/explore, use list-pages first.
+
+WORKFLOW: This tool returns the complete page content including title, description, and full markdown. Use this when you need to provide detailed answers or code examples from specific documentation pages.
+`,
+  inputSchema: {
+    path: z.string().describe('The page path from list-pages or provided by the user (e.g., /en/getting-started/installation)'),
+  },
+  cache: '1h',
+  handler: async ({ path }) => {
+    const event = useEvent()
+    const config = useRuntimeConfig(event).public
+    const siteUrl = import.meta.dev ? 'http://localhost:3000' : inferSiteURL()
+
+    const availableLocales = getAvailableLocales(config)
+    const collectionName = config.i18n?.locales
+      ? getCollectionFromPath(path, availableLocales)
+      : 'docs'
+
+    try {
+      const page = await queryCollection(event, collectionName as keyof Collections)
+        .where('path', '=', path)
+        .select('title', 'path', 'description')
+        .first()
+
+      if (!page) {
+        return errorResult('Page not found')
+      }
+
+      const content = await $fetch<string>(`/raw${path}.md`, {
+        baseURL: siteUrl,
+      })
+
+      return jsonResult({
+        title: page.title,
+        path: page.path,
+        description: page.description,
+        content,
+        url: `${siteUrl}${page.path}`,
+      })
+    }
+    catch {
+      return errorResult('Failed to get page')
+    }
+  },
+})

package/server/mcp/tools/list-pages.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections } from '@nuxt/content'
+import { getCollectionsToQuery, getAvailableLocales } from '../../utils/content'
+
+export default defineMcpTool({
+  description: `Lists all available documentation pages with their categories and basic information.
+
+WHEN TO USE: Use this tool when you need to EXPLORE or SEARCH for documentation about a topic but don't know the exact page path. Common scenarios:
+- "Find documentation about markdown features" - explore available guides
+- "Show me all getting started guides" - browse introductory content
+- "Search for advanced configuration options" - find specific topics
+- User asks general questions without specifying exact pages
+- You need to understand the overall documentation structure
+
+WHEN NOT TO USE: If you already know the specific page path (e.g., "/en/getting-started/installation"), use get-page directly instead.
+
+WORKFLOW: This tool returns page titles, descriptions, and paths. After finding relevant pages, use get-page to retrieve the full content of specific pages that match the user's needs.
+
+OUTPUT: Returns a structured list with:
+- title: Human-readable page name
+- path: Exact path for use with get-page
+- description: Brief summary of page content
+- url: Full URL for reference`,
+  inputSchema: {
+    locale: z.string().optional().describe('The locale to filter pages by'),
+  },
+  cache: '1h',
+  handler: async ({ locale }) => {
+    const event = useEvent()
+    const config = useRuntimeConfig(event).public
+
+    const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin
+    const availableLocales = getAvailableLocales(config)
+    const collections = getCollectionsToQuery(locale, availableLocales)
+
+    try {
+      const allPages = await Promise.all(
+        collections.map(async (collectionName) => {
+          const pages = await queryCollection(event, collectionName as keyof Collections)
+            .select('title', 'path', 'description')
+            .all()
+
+          return pages.map(page => ({
+            title: page.title,
+            path: page.path,
+            description: page.description,
+            locale: collectionName.replace('docs_', ''),
+            url: `${siteUrl}${page.path}`,
+          }))
+        }),
+      )
+
+      return jsonResult(allPages.flat())
+    }
+    catch {
+      return errorResult('Failed to list pages')
+    }
+  },
+})

package/server/routes/raw/[...slug].md.get.ts

@@ -0,0 +1,45 @@
+import { withLeadingSlash } from 'ufo'
+import { stringify } from 'minimark/stringify'
+import { queryCollection } from '@nuxt/content/server'
+import type { Collections } from '@nuxt/content'
+
+export default eventHandler(async (event) => {
+  const slug = getRouterParams(event)['slug.md']
+  if (!slug?.endsWith('.md')) {
+    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  }
+
+  const path = withLeadingSlash(slug.replace('.md', ''))
+  const config = useRuntimeConfig(event).public
+
+  let collectionName = 'docs'
+  if (config.i18n?.locales) {
+    const pathSegments = path.split('/').filter(Boolean)
+    const firstSegment = pathSegments[0]
+
+    const availableLocales = config.i18n.locales.map((locale: string | { code: string }) =>
+      typeof locale === 'string' ? locale : locale.code,
+    )
+
+    if (firstSegment && availableLocales.includes(firstSegment)) {
+      collectionName = `docs_${firstSegment}`
+    }
+    else if (config.i18n.defaultLocale) {
+      collectionName = `docs_${config.i18n.defaultLocale}`
+    }
+  }
+
+  const page = await queryCollection(event, collectionName as keyof Collections).path(path).first()
+  if (!page) {
+    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  }
+
+  // Add title and description to the top of the page if missing
+  if (page.body.value[0]?.[0] !== 'h1') {
+    page.body.value.unshift(['blockquote', {}, page.description])
+    page.body.value.unshift(['h1', {}, page.title])
+  }
+
+  setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
+  return stringify({ ...page.body, type: 'minimark' }, { format: 'markdown/html' })
+})

package/server/utils/content.ts

@@ -0,0 +1,37 @@
+import type { LocaleObject } from '@nuxtjs/i18n'
+
+type ConfigWithLocales = {
+  i18n?: { locales?: Array<string | LocaleObject> }
+  docus?: { filteredLocales?: LocaleObject<string>[] }
+}
+
+export function getAvailableLocales(config: ConfigWithLocales): string[] {
+  if (config.docus?.filteredLocales) {
+    return config.docus.filteredLocales.map(locale => locale.code)
+  }
+
+  return config.i18n?.locales
+    ? config.i18n.locales.map(locale => typeof locale === 'string' ? locale : locale.code)
+    : []
+}
+
+export function getCollectionsToQuery(locale: string | undefined, availableLocales: string[]): string[] {
+  if (locale && availableLocales.includes(locale)) {
+    return [`docs_${locale}`]
+  }
+
+  return availableLocales.length > 0
+    ? availableLocales.map(l => `docs_${l}`)
+    : ['docs']
+}
+
+export function getCollectionFromPath(path: string, availableLocales: string[]): string {
+  const pathSegments = path.split('/').filter(Boolean)
+  const firstSegment = pathSegments[0]
+
+  if (firstSegment && availableLocales.includes(firstSegment)) {
+    return `docs_${firstSegment}`
+  }
+
+  return 'docs'
+}

package/utils/git.ts

@@ -0,0 +1,110 @@
+import { execSync } from 'node:child_process'
+import { readGitConfig } from 'pkg-types'
+import gitUrlParse from 'git-url-parse'
+
+export interface GitInfo {
+  // Repository name
+  name: string
+  // Repository owner/organization
+  owner: string
+  // Repository URL
+  url: string
+}
+
+export function getGitBranch() {
+  const envName
+    = process.env.CF_PAGES_BRANCH
+      || process.env.CI_COMMIT_BRANCH
+      || process.env.VERCEL_GIT_COMMIT_REF
+      || process.env.BRANCH
+      || process.env.GITHUB_REF_NAME
+
+  if (envName && envName !== 'HEAD') {
+    return envName
+  }
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
+    if (branch && branch !== 'HEAD') {
+      return branch
+    }
+  }
+  catch {
+    // Ignore error
+  }
+
+  return 'main'
+}
+
+export async function getLocalGitInfo(rootDir: string): Promise<GitInfo | undefined> {
+  const remote = await getLocalGitRemote(rootDir)
+  if (!remote) {
+    return
+  }
+
+  // https://www.npmjs.com/package/git-url-parse#clipboard-example
+  const { name, owner, source } = gitUrlParse(remote)
+  const url = `https://${source}/${owner}/${name}`
+
+  return {
+    name,
+    owner,
+    url,
+  }
+}
+
+async function getLocalGitRemote(dir: string): Promise<string | undefined> {
+  try {
+    const parsed = await readGitConfig(dir)
+    if (!parsed) {
+      return
+    }
+    return parsed.remote?.['origin']?.url
+  }
+  catch {
+    // Ignore error
+  }
+}
+
+export function getGitEnv(): GitInfo {
+  // https://github.com/unjs/std-env/issues/59
+  const envInfo = {
+    // Provider
+    provider: process.env.VERCEL_GIT_PROVIDER // vercel
+      || (process.env.GITHUB_SERVER_URL ? 'github' : undefined) // github
+      || '',
+    // Owner
+    owner: process.env.VERCEL_GIT_REPO_OWNER // vercel
+      || process.env.GITHUB_REPOSITORY_OWNER // github
+      || process.env.CI_PROJECT_PATH?.split('/').shift() // gitlab
+      || '',
+    // Name
+    name: process.env.VERCEL_GIT_REPO_SLUG
+      || process.env.GITHUB_REPOSITORY?.split('/').pop() // github
+      || process.env.CI_PROJECT_PATH?.split('/').splice(1).join('/') // gitlab
+      || '',
+    // Url
+    url: process.env.REPOSITORY_URL || '', // netlify
+  }
+
+  if (!envInfo.url && envInfo.provider && envInfo.owner && envInfo.name) {
+    envInfo.url = `https://${envInfo.provider}.com/${envInfo.owner}/${envInfo.name}`
+  }
+
+  // If only url available (ex: Netlify)
+  if (!envInfo.name && !envInfo.owner && envInfo.url) {
+    try {
+      const { name, owner } = gitUrlParse(envInfo.url)
+      envInfo.name = name
+      envInfo.owner = owner
+    }
+    catch {
+      // Ignore error
+    }
+  }
+
+  return {
+    name: envInfo.name,
+    owner: envInfo.owner,
+    url: envInfo.url,
+  }
+}

package/utils/meta.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+export function inferSiteURL() {
+  // https://github.com/unjs/std-env/issues/59
+  return (
+    process.env.NUXT_SITE_URL
+    || (process.env.NEXT_PUBLIC_VERCEL_URL && `https://${process.env.NEXT_PUBLIC_VERCEL_URL}`) // Vercel
+    || process.env.URL // Netlify
+    || process.env.CI_PAGES_URL // Gitlab Pages
+    || process.env.CF_PAGES_URL // Cloudflare Pages
+  )
+}
+
+export async function getPackageJsonMetadata(dir: string) {
+  try {
+    const packageJson = await readFile(resolve(dir, 'package.json'), 'utf-8')
+    const parsed = JSON.parse(packageJson)
+    return {
+      name: parsed.name,
+      description: parsed.description,
+    }
+  }
+  catch {
+    return {
+      name: 'docs',
+    }
+  }
+}