Update Antora UI extensions for local docs preview (#647)

Author: eric-schneider

docs/extensions/assets-processor.js

@@ -0,0 +1,24 @@
+"use strict";
+
+module.exports.register = (context) => {
+  const logger = context.getLogger("assets-processor-extension");
+
+  context.once("uiLoaded", ({ uiCatalog }) => {
+    const manifestContents = uiCatalog
+      .findByType("asset")
+      .find((file) => file.stem === "assets-manifest")
+      .contents?.toString();
+    if (!manifestContents) {
+      logger.error("Could not find assets-manifest.json in the UI bundle.");
+      return;
+    }
+    const manifest = JSON.parse(manifestContents);
+    // Add manifest to node global context so it can be accessed by the handlebars helper during createPageComposer
+    global.assetsManifest = manifest;
+  });
+
+  context.once("pagesComposed", () => {
+     // Clean up the global context
+     delete global.assetsManifest;
+  });
+};

docs/extensions/tailwind-processor.js

@@ -1,12 +1,25 @@
-'use strict'
+"use strict";
 
-const { execSync } = require('child_process')
+const { execSync } = require("child_process");
 
 module.exports.register = (context) => {
-  context.once('sitePublished', () => {
+  context.once("sitePublished", ({ playbook }) => {
     const logger = context.getLogger('tailwind-processor-extension')
-    logger.info('Building Tailwind')
-    execSync('npm run tailwindcss', { stdio: 'inherit' })
-    logger.info('Tailwind Build Successful')
-  })
-}
+    const outputDir = playbook?.output?.dir || "build/site";
+    logger.info("Building Tailwind");
+    var configPath = execSync(`find ${outputDir} -name tailwind.config.js`)
+      .toString()
+      .trim();
+    var cssPath = execSync(`find ${outputDir} -name site*.css`)
+      .toString()
+      .trim();
+    logger.info(
+      `npm run tailwindcss --tailwind-config-path=${configPath} --css-path=${cssPath}`
+    );
+    execSync(
+      `npm run tailwindcss --tailwind-config-path=${configPath} --css-path=${cssPath}`,
+      { stdio: "inherit" }
+    );
+    logger.info("Tailwind Build Successful");
+  });
+};

docs/extensions/unlisted-pages-extension.js

@@ -1,41 +1,41 @@
 module.exports.register = function ({ config }) {
-  const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config
-  const logger = this.getLogger('unlisted-pages-extension')
-  this
-    .on('navigationBuilt', ({ contentCatalog }) => {
-      contentCatalog.getComponents().forEach(({ versions }) => {
-        versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
-          const navEntriesByUrl = getNavEntriesByUrl(nav)
-          const unlistedPages = contentCatalog
-            .findBy({ component, version, family: 'page' })
-            .filter((page) => page.out)
-            .reduce((collector, page) => {
-              // Check if the 'unlisted-page' attribute is set to true
-              if (page.asciidoc.attributes['unlisted-page'] === 'true') {
-                  return collector; // Skip this page
-              }
-              if ((page.pub.url in navEntriesByUrl) || page.pub.url === defaultUrl) return collector
-              logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted page')
-              return collector.concat(page)
-            }, [])
-          if (unlistedPages.length && addToNavigation) {
-            nav.push({
-              content: unlistedPagesHeading,
-              items: unlistedPages.map((page) => {
-                return { content: page.asciidoc.navtitle, url: page.pub.url, urlType: 'internal' }
-              }),
-              root: true,
-            })
-          }
+    const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config
+    const logger = this.getLogger('unlisted-pages-extension')
+    this
+      .on('navigationBuilt', ({ contentCatalog }) => {
+        contentCatalog.getComponents().forEach(({ versions }) => {
+          versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
+            const navEntriesByUrl = getNavEntriesByUrl(nav)
+            const unlistedPages = contentCatalog
+              .findBy({ component, version, family: 'page' })
+              .filter((page) => page.out)
+              .reduce((collector, page) => {
+                // Check if the 'unlisted-page' attribute is set to true
+                if (page.asciidoc.attributes['unlisted-page'] === 'true') {
+                    return collector; // Skip this page
+                }
+                if ((page.pub.url in navEntriesByUrl) || page.pub.url === defaultUrl) return collector
+                logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted page')
+                return collector.concat(page)
+              }, [])
+            if (unlistedPages.length && addToNavigation) {
+              nav.push({
+                content: unlistedPagesHeading,
+                items: unlistedPages.map((page) => {
+                  return { content: page.asciidoc.navtitle, url: page.pub.url, urlType: 'internal' }
+                }),
+                root: true,
+              })
+            }
+          })
         })
       })
-    })
-}
+  }
 
-function getNavEntriesByUrl (items = [], accum = {}) {
-  items.forEach((item) => {
-    if (item.urlType === 'internal') accum[item.url.split('#')[0]] = item
-    getNavEntriesByUrl(item.items, accum)
-  })
-  return accum
-}
+  function getNavEntriesByUrl (items = [], accum = {}) {
+    items.forEach((item) => {
+      if (item.urlType === 'internal') accum[item.url.split('#')[0]] = item
+      getNavEntriesByUrl(item.items, accum)
+    })
+    return accum
+  }

docs/local-preview-playbook.yml

@@ -19,7 +19,9 @@ content:
 
 antora:
   extensions:
+  - '@antora/atlas-extension'
   - '@antora/collector-extension'
+  - extensions/assets-processor.js
   - extensions/tailwind-processor.js
   - id: unlisted-pages
     enabled: true
@@ -36,7 +38,8 @@ asciidoc:
   - asciidoctor-external-callout
   attributes:
     # BUILT-IN ATTRIBUTES
-    allow-uri-read: '' # this has no effect in antora, but does help development in Intellij
+    # allow-uri-read: '' # Quality-of-life benefit for IntelliJ users. CAUTION: Opens the door to malicious code insertion - must remain disabled in prod build environment.
+    # hide-uri-scheme: '' # Consider enabling this attribute to make raw http hyperlinks look cleaner.
     experimental: ''
     idprefix: ''
     idseparator: '-'
@@ -55,8 +58,20 @@ asciidoc:
     astra_db: 'Astra DB'
     astra_stream: 'Astra Streaming'
     astra_ui: 'Astra Portal'
+    astra_cli: 'Astra CLI'
+    astra-streaming-examples-repo: 'https://raw.githubusercontent.com/datastax/astra-streaming-examples/master'
+    luna-streaming-examples-repo: 'https://raw.githubusercontent.com/datastaxdevs/luna-streaming-examples/main'
     support_url: 'https://support.datastax.com'
     glossary-url: 'https://docs.datastax.com/en/glossary/docs/index.html#'
+    emoji-tada: "🎉"
+    emoji-rocket: "🚀"
+    emoji-smile: "&#128512"
+    dse: 'DataStax Enterprise (DSE)'
+    cassandra: 'Apache Cassandra(R)'
+    classic: 'classic'
+    classic_cap: 'Classic'
+    serverless: 'serverless'
+    serverless_cap: 'Serverless'
     # Antora Atlas
     primary-site-url: https://docs.datastax.com/en
     primary-site-manifest-url: https://docs.datastax.com/en/site-manifest.json

docs/package-lock.json

@@ -9,7 +9,7 @@
     "url": "https://github.com/datastax/ragstack-ai.git"
   },
   "scripts": {
-    "tailwindcss": "tailwindcss build -c ./build/site/_/js/tailwind.config.js -i ./build/site/_/css/site.css -o ./build/site/_/css/site.css --minify",
+    "tailwindcss": "tailwindcss build -c ${npm_config_tailwind_config_path} -i ${npm_config_css_path} -o ${npm_config_css_path} --minify",
     "build:local": "env FORCE_SHOW_EDIT_PAGE_LINK=true antora --clean --fetch --stacktrace local-preview-playbook.yml"
   },
   "dependencies": {
@@ -20,6 +20,7 @@
     "asciidoctor-external-callout": "~1.2.1",
     "asciidoctor-kroki": "~0.18.1",
     "csv-parser": "^3.0.0",
+    "lodash": "^4.17.21",
     "npm-run-all": "^4.1.5",
     "tailwindcss": "^3.3.5"
   }