Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(docs): add sitemap, robots, canonical/hreflang, page descriptions and GA (#5975)

Zayn Jarvis70d3e1d30208
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index dc4e3d761..b74bb0f1f 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitepress'
import taskLists from 'markdown-it-task-lists'
import { hasPageLlmsTxt, pageLlmsTxtPath } from './theme/llms-txt'
+import { inferDescription, seoLinks } from './theme/seo'
import { titleFromMarkdown, docPageTitle, documentationNav, documentationSidebars, documentationSections } from './docs-navigation'
const docsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
@@ -11,8 +12,11 @@ const repo = process.env.GITHUB_REPOSITORY || 'volcengine/OpenViking'
const githubRepositoryUrl = `https://github.com/${repo}?utm_source=docs&utm_medium=referral&utm_campaign=docs`
const configuredBase = '/' + (process.env.DOCS_BASE || '/').split('/').filter(Boolean).join('/') + '/'
const base = configuredBase === '//' ? '/' : configuredBase
+const siteRoot = `${(process.env.DOCS_SITE_URL || 'https://docs.openviking.ai').replace(/\/$/, '')}${base}`
// Version the filename so social crawlers do not reuse the previous artwork.
-const ogImageUrl = `${(process.env.DOCS_SITE_URL || 'https://docs.openviking.ai').replace(/\/$/, '')}${base}og-openviking-docs-8efb541b.png`
+const ogImageUrl = `${siteRoot}og-openviking-docs-8efb541b.png`
+// Same GA4 property as openviking.ai; the linker keeps one session across both domains.
+const gaMeasurementId = 'G-86SNDZ0EY9'
const languageSource = fs.readFileSync(path.join(docsRoot, '.vitepress/theme/language-preference.js'), 'utf8').replace('export function', 'function')
const entrySource = fs.readFileSync(path.join(docsRoot, '.vitepress/theme/language-entry.js'), 'utf8').replace('export function', 'function')
const languageBootstrapScript = `${languageSource}\n${entrySource}\n;(() => {
@@ -195,6 +199,7 @@ export default defineConfig({
description: 'Open-source context database for AI Agents',
cleanUrls: true,
lastUpdated: true,
+ sitemap: { hostname: siteRoot },
markdown: { config: md => md.use(taskLists, { label: true }) },
// Repository guides are read on GitHub; review notes are local artifacts.
// images/ is the public asset directory, including raw Markdown consumed by other apps.
@@ -213,18 +218,26 @@ export default defineConfig({
['meta', { name: 'twitter:card', content: 'summary_large_image' }],
['meta', { name: 'twitter:image', content: ogImageUrl }],
['meta', { name: 'twitter:image:alt', content: 'OpenViking / docs — Guides and API reference for AI agent context.' }],
+ ['script', { async: '', src: `https://www.googletagmanager.com/gtag/js?id=${gaMeasurementId}` }],
+ ['script', {}, `window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', '${gaMeasurementId}', { linker: { domains: ['openviking.ai', 'docs.openviking.ai'] } });`],
['script', {}, preferenceBootstrapScript],
['script', {}, languageBootstrapScript]
],
transformPageData(pageData, { siteConfig }) {
+ const head = pageData.frontmatter.head ??= []
if (hasPageLlmsTxt(pageData.relativePath)) {
- const head = pageData.frontmatter.head ??= []
head.push(['link', { rel: 'alternate', type: 'text/plain', title: 'LLM page content', href: `${base.replace(/\/$/, '')}${pageLlmsTxtPath(pageData.relativePath)}` }])
}
+ head.push(...seoLinks(siteRoot, pageData.relativePath, relativePath => fs.existsSync(path.join(siteConfig.srcDir, relativePath))))
const srcPath = path.join(siteConfig.srcDir, pageData.relativePath)
try {
+ const markdown = fs.readFileSync(srcPath, 'utf-8')
+ pageData.description ||= inferDescription(markdown)
// Raw SFC closing tags must not terminate VitePress's generated script block.
- pageData.frontmatter._rawMarkdownEncoded = encodeURIComponent(fs.readFileSync(srcPath, 'utf-8'))
+ pageData.frontmatter._rawMarkdownEncoded = encodeURIComponent(markdown)
} catch {
pageData.frontmatter._rawMarkdownEncoded = ''
}
diff --git a/docs/.vitepress/theme/seo.ts b/docs/.vitepress/theme/seo.ts
new file mode 100644
index 000000000..a3a957197
--- /dev/null
+++ b/docs/.vitepress/theme/seo.ts
@@ -0,0 +1,47 @@
+type HeadEntry = [string, Record<string, string>]
+
+const locales = { en: 'en-US', zh: 'zh-CN' } as const
+
+/** Public URL of a page source path, e.g. `zh/guides/01-a.md` -> `${siteRoot}zh/guides/01-a`. */
+export function pageUrl(siteRoot: string, relativePath: string): string {
+ return siteRoot + relativePath.replace(/(^|\/)index\.md$/, '$1').replace(/\.md$/, '')
+}
+
+/** Canonical plus hreflang alternates for every language version that exists. */
+export function seoLinks(siteRoot: string, relativePath: string, exists: (relativePath: string) => boolean): HeadEntry[] {
+ const head: HeadEntry[] = [['link', { rel: 'canonical', href: pageUrl(siteRoot, relativePath) }]]
+ const match = relativePath.match(/^(en|zh)\/(.*)$/)
+ if (!match) return head
+
+ const versions = Object.entries(locales)
+ .map(([locale, lang]) => ({ path: `${locale}/${match[2]}`, lang }))
+ .filter(version => exists(version.path))
+ if (versions.length < 2) return head
+
+ for (const { path, lang } of versions) {
+ head.push(['link', { rel: 'alternate', hreflang: lang, href: pageUrl(siteRoot, path) }])
+ }
+ head.push(['link', { rel: 'alternate', hreflang: 'x-default', href: pageUrl(siteRoot, versions[0].path) }])
+ return head
+}
+
+/** First prose paragraph after the title, as plain text, for pages without a description. */
+export function inferDescription(markdown: string, maxLength = 160): string {
+ const body = markdown
+ .replace(/^---[\s\S]*?---\s*/, '')
+ .replace(/```[\s\S]*?```/g, '\n\n')
+ .replace(/<[^>]+>/g, '')
+ const paragraph = body.split(/\n\s*\n/)
+ .map(block => block.trim())
+ .find(block => block && !/^(#|>|[-*+]\s|\d+\.\s|\||:::|!\[)/.test(block))
+ if (!paragraph) return ''
+
+ const text = paragraph
+ .replace(/!\[[^\]]*\]\([^)]+\)/g, '')
+ .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+ .replace(/`([^`]+)`/g, '$1')
+ .replace(/(\*\*|\*)([^*\n]+)\1/g, '$2')
+ .replace(/\s+/g, ' ')
+ .trim()
+ return text.length <= maxLength ? text : text.slice(0, maxLength - 1).trimEnd() + '…'
+}
diff --git a/docs/images/robots.txt b/docs/images/robots.txt
new file mode 100644
index 000000000..342a7626f
--- /dev/null
+++ b/docs/images/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://docs.openviking.ai/sitemap.xml