docs: Savanna documentation refresh, LLM export, and video walkthrough

.gitignore

@@ -1,4 +1,29 @@
-.idea/
+# Dependencies
+node_modules/
+
+# Antora build output and cache
+build/
+.cache/
+antora.log
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Lockfile — yarn.lock is the committed source of truth
+package-lock.json
+
+# Local-only Antora playbook (sibling antora-ui path)
+antora-playbook.local.yml
+
+# OS
 .DS_Store
-node_modules
-build
+Thumbs.db
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*~

antora-playbook.yml

@@ -1,17 +1,28 @@
 site:
-  title: "Cloud Doc Test"
-  start_page: "savanna:overview:index.adoc"
+  title: Docs
+  url: https://www.tigergraph.com/docs
+  start_page: savanna:overview:index.adoc
 
 content:
   sources:
     - url: .
       branches: HEAD
       start_paths: [modules/savanna, modules/cloud]
 
+antora:
+  extensions:
+    - ./lib/markdown-for-llm.js
+    # ./lib/llms-txt.js is kept in the repo for a later site-wide /llms.txt. Do not
+    # enable it here: this playbook only builds Savanna and Cloud Classic.
+
+asciidoc:
+  extensions:
+    - '@asciidoctor/tabs'
+
 output:
   dir: ./build/site
 
 ui:
   bundle:
     url: https://github.com/tigergraph/antora-ui/blob/main/build/ui-bundle.zip?raw=true
-    snapshot: true
+    snapshot: true

gulpfile.js

@@ -7,10 +7,10 @@ const { reload: livereload } = process.env.LIVERELOAD === 'true' ? require('gulp
 const { series, src, watch } = require('gulp')
 const yaml = require('js-yaml')
 
-const playbookFilename = 'antora-playbook.yml'
+const playbookFilename = process.env.PLAYBOOK || 'antora-playbook.yml'
 const playbook = yaml.load(fs.readFileSync(playbookFilename, 'utf8'))
 const outputDir = (playbook.output || {}).dir || './build/site'
-const serverConfig = { name: 'Preview Site', livereload, port: 5000, root: outputDir }
+const serverConfig = { name: 'Preview Site', livereload, port: Number(process.env.PORT) || 5000, root: outputDir }
 const antoraArgs = ['--playbook', playbookFilename]
 const watchPatterns = playbook.content.sources.filter((source) => !source.url.includes(':')).reduce((accum, source) => {
   accum.push(`${source.url}/${source.start_path ? source.start_path + '/' : ''}antora.yml`)

lib/llm-utils.js

@@ -0,0 +1,32 @@
+'use strict'
+
+/**
+ * Shared helpers for LLM-oriented Antora extensions.
+ */
+
+function stripTags (html) {
+  return String(html || '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function htmlToMdUrl (url) {
+  if (typeof url !== 'string') return url
+  const match = /^(.*?)([?#].*)?$/.exec(url)
+  const path = match[1]
+  const rest = match[2] || ''
+  if (/\.md$/i.test(path)) return url
+  if (/\.html$/i.test(path)) return path.replace(/\.html$/i, '.md') + rest
+  if (path.endsWith('/')) return path + 'index.md' + rest
+  if (!path) return url
+  return path + '.md' + rest
+}
+
+module.exports = { stripTags, htmlToMdUrl }

lib/llms-txt.js

@@ -0,0 +1,132 @@
+'use strict'
+
+/**
+ * Antora extension: generate /llms.txt from the site navigation model.
+ *
+ * Not registered in antora-playbook.yml. This playbook only builds Savanna and
+ * Cloud Classic; the live site-wide index is tigergraph.com/docs/llms.txt.
+ * Re-enable later when this can feed the full docs set (or a product subpath).
+ *
+ * Inspired by Couchbase's llms-txt.js, but adapted for this dual HTML+Markdown
+ * site: navigation links point at the generated `.md` twins rather than HTML,
+ * and we walk Antora's navigationCatalog directly (no separate nav-data JSON).
+ *
+ * Spec: https://llmstxt.org/
+ */
+
+const { htmlToMdUrl, stripTags } = require('./llm-utils')
+
+function absoluteUrl (siteUrl, path) {
+  if (!path) return path
+  if (/^https?:\/\//i.test(path)) return htmlToMdUrl(path)
+  const base = (siteUrl || '').replace(/\/$/, '')
+  const rel = path.startsWith('/') ? path : `/${path}`
+  return htmlToMdUrl(base ? `${base}${rel}` : rel)
+}
+
+function navLabel (item) {
+  return stripTags(item.content) || stripTags(item.title) || 'Untitled'
+}
+
+function renderNavItems (items, siteUrl, lines, depth) {
+  if (!items || !items.length) return
+
+  for (const item of items) {
+    const label = navLabel(item)
+    const indent = '  '.repeat(depth)
+    const hasChildren = item.items && item.items.length
+
+    if (item.url && item.urlType !== 'fragment') {
+      lines.push(`${indent}- [${label}](${absoluteUrl(siteUrl, item.url)})`)
+      if (hasChildren) renderNavItems(item.items, siteUrl, lines, depth + 1)
+      continue
+    }
+
+    // Section heading without its own page
+    if (depth === 0 && hasChildren) {
+      lines.push('')
+      lines.push(`### ${label}`)
+      lines.push('')
+      renderNavItems(item.items, siteUrl, lines, 0)
+      continue
+    }
+
+    if (label) lines.push(`${indent}- ${label}`)
+    if (hasChildren) renderNavItems(item.items, siteUrl, lines, depth + 1)
+  }
+}
+
+function buildLlmsTxt (playbook, contentCatalog, navigationCatalog) {
+  const siteTitle = (playbook.site && playbook.site.title) || 'TigerGraph Documentation'
+  const siteUrl = (playbook.site && playbook.site.url) || ''
+  const lines = []
+
+  lines.push(`# ${siteTitle}`)
+  lines.push('')
+  lines.push(
+    '> TigerGraph developer documentation for Savanna (cloud-native graph database) and Cloud Classic. ' +
+      'Prefer the Markdown (`.md`) links below when loading pages into an LLM or coding agent.'
+  )
+  lines.push('')
+  lines.push(`- [HTML site](${siteUrl || '/'})`)
+  lines.push('')
+
+  const components = contentCatalog.getComponents().slice().sort((a, b) => {
+    // Prefer Savanna first, then alphabetical
+    if (a.name === 'savanna') return -1
+    if (b.name === 'savanna') return 1
+    return a.name.localeCompare(b.name)
+  })
+
+  for (const component of components) {
+    // Latest / only version for each component (both currently use version "main")
+    const version = component.latest || component.versions[0]
+    if (!version) continue
+
+    const navTrees = navigationCatalog.getNavigation(component.name, version.version) || []
+    if (!navTrees.length) continue
+
+    const versionLabel =
+      version.displayVersion && version.displayVersion !== 'default'
+        ? ` (${version.displayVersion})`
+        : version.version && version.version !== 'main'
+          ? ` (${version.version})`
+          : ''
+
+    lines.push(`## ${version.title}${versionLabel}`)
+    lines.push('')
+
+    for (const tree of navTrees) {
+      renderNavItems(tree.items || [tree], siteUrl, lines, 0)
+    }
+
+    lines.push('')
+  }
+
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`
+}
+
+module.exports.register = function () {
+  let snapshot
+
+  this.on('navigationBuilt', ({ playbook, contentCatalog, navigationCatalog }) => {
+    snapshot = { playbook, contentCatalog, navigationCatalog }
+  })
+
+  this.on('beforePublish', ({ siteCatalog }) => {
+    if (!snapshot) return
+
+    const contents = Buffer.from(
+      buildLlmsTxt(snapshot.playbook, snapshot.contentCatalog, snapshot.navigationCatalog)
+    )
+
+    siteCatalog.addFile({
+      contents,
+      mediaType: 'text/plain',
+      out: { path: 'llms.txt' },
+      path: 'llms.txt',
+      pub: { url: '/llms.txt' },
+      src: { stem: 'llms' },
+    })
+  })
+}