Highlight CQL and other new languages, and refresh the highlighting theme

gulp.d/tasks/build.js

@@ -21,6 +21,21 @@ const postcssVar = require('postcss-custom-properties')
 const { Transform } = require('stream')
 const map = (transform) => new Transform({ objectMode: true, transform })
 const through = () => map((file, enc, next) => next(null, file))
+// Minifying drops some license notices (/*! ... */ comments), which the licenses of the bundled
+// libraries require us to keep, so record them first and put back any that are lost.
+const LICENSE_NOTICE_RX = /\/\*![\s\S]*?\*\//g
+const recordLicenseNotices = () =>
+  map((file, enc, next) => {
+    file.licenseNotices = [...new Set(file.contents.toString().match(LICENSE_NOTICE_RX))]
+    next(null, file)
+  })
+const restoreLicenseNotices = () =>
+  map((file, enc, next) => {
+    const code = file.contents.toString()
+    const lost = (file.licenseNotices || []).filter((notice) => !code.includes(notice))
+    if (lost.length) file.contents = Buffer.from(lost.join('\n') + '\n' + code)
+    next(null, file)
+  })
 const uglify = require('gulp-uglify')
 const vfs = require('vinyl-fs')
 const hash = require('gulp-hash')
@@ -84,9 +99,9 @@ module.exports = (src, dest, preview) => () => {
     vfs
       .src('js/vendor/*([^.])?(.bundle).js', { ...opts, read: false })
       .pipe(bundle(opts))
-      // .pipe(uglify({ output: { comments: /^! / } }))
-      .pipe(map((file) => file.relative === 'js/vendor/floatingui.js')
-        ? through() : uglify({ output: { comments: /^! / } }))
+      .pipe(recordLicenseNotices())
+      .pipe(gulpif((file) => file.relative !== 'js/vendor/floatingui.js', uglify({ output: { comments: /^! / } })))
+      .pipe(restoreLicenseNotices())
       .pipe(gulpif(
         !preview,
         hash({ template: '<%= name %>-<%= hash %><%= ext %>' })))

gulpfile.js

@@ -18,7 +18,9 @@ const task = require('./gulp.d/tasks')
 const glob = {
   all: [srcDir, previewSrcDir],
   css: `${srcDir}/css/**/*.css`,
-  js: ['gulpfile.js', 'gulp.d/**/*.js', `${srcDir}/{helpers,js}/**/*.js`],
+  // src/js/vendor/languages holds grammars maintained elsewhere (see its README); they keep
+  // their upstream formatting, so lint and format skip them.
+  js: ['gulpfile.js', 'gulp.d/**/*.js', `${srcDir}/{helpers,js}/**/*.js`, `!${srcDir}/js/vendor/languages/**`],
 }
 
 const cleanTask = createTask({

preview-src/asciidoc/code.adoc

@@ -81,6 +81,94 @@ public class CurrentDateTime {
 }
 ----
 
+=== Syntax highlighting samples
+
+These samples show how each kind of token is colored in the languages the docs use most, and in PowerShell.
+
+.CQL: schema and queries
+[source,cql]
+----
+CREATE TABLE IF NOT EXISTS store.orders (
+  order_id uuid,
+  placed_at timestamp,
+  status text,
+  items list<frozen<map<text, int>>>,
+  embedding vector<float, 3>,
+  PRIMARY KEY ((order_id), placed_at)
+) WITH CLUSTERING ORDER BY (placed_at DESC)
+  AND comment = 'Orders by customer'
+  AND default_time_to_live = 0;
+
+SELECT order_id, writetime(status), toJson(items) FROM store.orders
+WHERE order_id = 6ab09bec-e68e-48d9-a5f8-97e6fb4c9b47
+  AND placed_at >= ? -- a bind marker
+ORDER BY embedding ANN OF [0.1, 0.2, 0.3] LIMIT 5;
+----
+
+.CQL: syntax summary with placeholders
+[source,cql]
+----
+CREATE TABLE [ IF NOT EXISTS ] [<keyspace_name>.]<table_name>
+  ( <column_name> <cql_type> [ STATIC ] [ PRIMARY KEY ] [ , ... ] )
+  [ WITH <table_options> ] ;
+----
+
+.CQL: cqlsh session
+[source,cql]
+----
+cqlsh> CONSISTENCY LOCAL_QUORUM
+cqlsh> USE store;
+cqlsh:store> SELECT order_id, status FROM orders LIMIT 1;
+
+ order_id                             | status
+--------------------------------------+--------
+ 6ab09bec-e68e-48d9-a5f8-97e6fb4c9b47 |    NEW
+
+(1 rows)
+----
+
+.GraphQL
+[source,graphql]
+----
+query getOrder($id: Uuid!) {
+  orders(value: { order_id: $id }) @cql_column(name: "orders") {
+    values { order_id status }
+  }
+}
+----
+
+.YAML
+[source,yaml]
+----
+# Audit logging in cassandra.yaml
+audit_logging_options:
+  enabled: true
+  logger:
+    - class_name: BinAuditLogger
+  included_categories: QUERY, DDL, AUTH
+----
+
+.XML
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<dependency>
+  <groupId>org.apache.cassandra</groupId>
+  <artifactId>java-driver-core</artifactId>
+  <version>${driver.version}</version> <!-- the release you use -->
+</dependency>
+----
+
+.PowerShell
+[source,powershell]
+----
+# Install the Astra CLI on Windows
+$env:ASTRA_HOME = "C:\Tools\astra"
+New-Item -ItemType Directory -Force -Path $env:ASTRA_HOME | Out-Null
+Expand-Archive -Path "$env:TEMP\astra.zip" -DestinationPath $env:ASTRA_HOME -Force
+if (-not (Get-Command astra -ErrorAction SilentlyContinue)) { Write-Output "Add $env:ASTRA_HOME to PATH" }
+----
+
 === Line wrapping
 
 .Line wrapping is turned off by default

src/css/asciidoc/doc.css

@@ -764,7 +764,9 @@
     padding: var(--ds-space-2);
   }
 
-  .doc .language-console .hljs-meta {
+  /* Prompts (console $, cqlsh>) are not selected along with the commands after them. */
+  .doc .language-console .hljs-meta,
+  .doc .language-cql .hljs-meta {
     user-select: none;
   }
 

src/css/highlight.css

@@ -1,115 +1,100 @@
-.hljs-comment {
-  color: var(--ds-text-tertiary);
-}
+/* Syntax highlighting for code blocks, for highlight.js 9 class names and the highlight.js 11
+   sub-scopes that differ. Colors come from the --ds-code-* variables in vars/light.css and
+   vars/dark.css; each has at least 4.5:1 contrast (WCAG AA) on the code block background.
+   Punctuation, operators, parameters, and names stay in the text color. */
 
+.hljs-comment,
 .hljs-quote {
-  color: var(--ds-text-tertiary);
-}
-
-.hljs-variable {
-  color: var(--ds-failure-main);
+  color: var(--ds-code-comment);
+  font-style: italic;
 }
 
-.hljs-template-variable {
-  color: var(--ds-failure-main);
+/* Prompts, preprocessor lines, annotations, markup brackets, and list bullets. */
+.hljs-meta,
+.hljs-tag,
+.hljs-bullet {
+  color: var(--ds-code-meta);
 }
 
-.hljs-tag {
-  color: var(--ds-failure-main);
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-name,
+.hljs-doctag,
+.hljs-meta-keyword,
+.hljs-meta .hljs-keyword,
+.hljs-variable.language_ {
+  color: var(--ds-code-keyword);
 }
 
-.hljs-name {
-  color: var(--ds-failure-main);
+.hljs-type,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-title.class_ {
+  color: var(--ds-code-type);
 }
 
+/* Names being defined or called: functions, classes, headings. */
+.hljs-title,
+.hljs-section,
 .hljs-selector-id {
-  color: var(--ds-failure-main);
-}
-
-.hljs-selector-class {
-  color: var(--ds-cyan-main);
-}
-
-.hljs-regexp {
-  color: var(--ds-cyan-main);
-}
-
-.hljs-deletion {
-  color: var(--ds-failure-main);
-}
-
-.hljs-number {
-  color: var(--ds-orange-main);
-}
-
-.hljs-built_in {
-  color: var(--ds-teal-main);
-}
-
-.hljs-builtin-name {
-  color: var(--ds-orange-main);
+  color: var(--ds-code-title);
 }
 
-.hljs-literal {
-  color: var(--ds-orange-main);
-}
-
-.hljs-type {
-  color: var(--ds-orange-main);
-}
-
-.hljs-params {
-  color: var(--ds-orange-main);
-}
-
-.hljs-meta {
-  color: var(--ds-orange-main);
+.hljs-section {
+  font-weight: 600;
 }
 
+/* Keys and setting names: JSON and YAML keys, XML attributes, CSS properties, options. */
+.hljs-attr,
+.hljs-attribute,
+.hljs-property,
+.hljs-symbol,
+.hljs-selector-attr,
+.hljs-selector-class,
+.hljs-selector-pseudo,
 .hljs-link {
-  color: var(--ds-orange-main);
+  color: var(--ds-code-attr);
 }
 
-.hljs-attribute {
-  color: var(--ds-orange-main);
-}
-
-.hljs-string {
-  color: var(--ds-orange-main);
-}
-
-.hljs-symbol {
-  color: var(--ds-success-main);
-}
-
-.hljs-bullet {
-  color: var(--ds-success-main);
+.hljs-link {
+  text-decoration: underline;
 }
 
+.hljs-string,
+.hljs-regexp,
+.hljs-meta-string,
+.hljs-meta .hljs-string,
 .hljs-addition {
-  color: var(--ds-success-main);
+  color: var(--ds-code-string);
 }
 
-.hljs-title {
-  color: var(--ds-cyan-main);
+.hljs-number,
+.hljs-literal,
+.hljs-char.escape_,
+.hljs-variable.constant_ {
+  color: var(--ds-code-number);
 }
 
-.hljs-section {
-  color: var(--ds-cyan-main);
+/* Values supplied by the reader or the environment: variables, bind markers, and
+   placeholders such as <keyspace_name>, which are also italic, like variables in prose. */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-template-tag {
+  color: var(--ds-code-variable);
 }
 
-.hljs-keyword {
-  color: var(--ds-primary-main);
+.hljs-template-variable {
+  font-style: italic;
 }
 
-.hljs-selector-tag {
-  color: var(--ds-primary-main);
+.hljs-deletion {
+  color: var(--ds-code-deletion);
 }
 
 .hljs-emphasis {
   font-style: italic;
 }
 
 .hljs-strong {
-  font-weight: 500;
+  font-weight: 600;
 }

src/css/vars/dark.css

@@ -98,6 +98,19 @@
   --ds-warning-solid-bg: theme(colors.amber.500);
   --ds-warning-solid-color: theme(colors.black);
   --ds-warning-solid-hover-bg: theme(colors.amber.400);
+
+  /* Code syntax highlighting (see highlight.css). Each color has at least 4.5:1
+     contrast (WCAG AA) on --ds-background-level1, the code block background. */
+  --ds-code-comment: theme(colors.zinc.400);
+  --ds-code-meta: theme(colors.zinc.400);
+  --ds-code-keyword: theme(colors.purple.400);
+  --ds-code-type: theme(colors.lime.400);
+  --ds-code-title: theme(colors.pink.400);
+  --ds-code-attr: theme(colors.sky.400);
+  --ds-code-string: theme(colors.emerald.400);
+  --ds-code-number: theme(colors.orange.400);
+  --ds-code-variable: theme(colors.amber.400);
+  --ds-code-deletion: theme(colors.red.400);
 }
 
 @mixin dark-inverse {

src/css/vars/light.css

@@ -98,6 +98,19 @@
   --ds-warning-solid-bg: theme(colors.amber.600);
   --ds-warning-solid-color: theme(colors.white);
   --ds-warning-solid-hover-bg: theme(colors.amber.700);
+
+  /* Code syntax highlighting (see highlight.css). Each color has at least 4.5:1
+     contrast (WCAG AA) on --ds-background-level1, the code block background. */
+  --ds-code-comment: theme(colors.zinc.500);
+  --ds-code-meta: theme(colors.zinc.500);
+  --ds-code-keyword: theme(colors.purple.700);
+  --ds-code-type: theme(colors.lime.700);
+  --ds-code-title: theme(colors.pink.700);
+  --ds-code-attr: theme(colors.sky.700);
+  --ds-code-string: theme(colors.emerald.700);
+  --ds-code-number: theme(colors.orange.700);
+  --ds-code-variable: theme(colors.amber.700);
+  --ds-code-deletion: theme(colors.red.700);
 }
 
 @mixin light-inverse {

src/js/vendor/floatingui.bundle.js

@@ -1,3 +1,6 @@
+/*! Floating UI | MIT | Copyright (c) 2021-present Floating UI contributors | https://github.com/floating-ui/floating-ui
+ * @floating-ui/dom 1.6.12, @floating-ui/core 1.6.8, @floating-ui/utils 0.2.8
+ */
 /**
  * Dropdown Example
  *