docs: use shiki for syntax highlighting (#65)

* docs: document reference escaping, writing and version conversion

- references: local references are JSON pointers in a URI, so "/" and "~"
  in a key are escaped as "~1" and "~0", and the pointer is percent-decoded;
  add how references are written, including inlining references whose
  target the written document does not have.
- version conversion: list which references stay references and which are
  written inline, how V2 channel references map to V3 channel keys, and the
  operations and messages a downgrade drops.
- README: drop the JsonPointer.Net attribution, which is no longer a
  dependency, and fix the ReferenceResolutionSetting name and a server
  reference example.

* docs: highlight code with Shiki

Prism's C# grammar has no raw string literals, so the AsyncAPI documents
embedded in examples were highlighted as C# code, and as a regex-based
grammar it leaves identifiers and properties plain. Its themes also gave
types the same color as numbers and booleans.

Code blocks now use Shiki with Visual Studio Code's grammars and its
Light+ and Dark+ themes, through a swizzled CodeBlock/Content that keeps
the theme's line rendering, so line numbers, highlighted lines and the copy
button still work. Highlighting is synchronous, so pages render the same on
the server and in the browser. C#, JSON, YAML and shell are loaded; other
languages render as plain text.

Author: VisualBean

website/docusaurus.config.js

@@ -42,7 +42,9 @@ const config = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} ByteBardOrg.`,
     },
-    prism: {theme: prismThemes.github, darkTheme: prismThemes.dracula, additionalLanguages: ['csharp']},
+    // Code is highlighted with Shiki (src/theme/CodeBlock/Content); these Prism themes only color the code block
+    // around it, and match the background of Shiki's Visual Studio Code themes.
+    prism: {theme: prismThemes.vsLight, darkTheme: prismThemes.vsDark},
   },
 };
 

website/package-lock.json

@@ -16,7 +16,8 @@
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "shiki": "^4.5.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "^3.8.1",

website/package.json

@@ -153,3 +153,18 @@ html[data-theme='dark'] .navbar__items--right .navbar__link:hover {color: #a87ef
   html:not([data-theme='dark']) .navbar-sidebar .menu__link--active,
   html[data-theme='dark'] .navbar-sidebar .menu__link--active {color: #a87efc}
 }
+
+/* Code tokens carry both color modes' styles as CSS variables (src/theme/CodeBlock/Content/shiki.js). */
+.shiki-token {
+  color: var(--shiki-light);
+  font-style: var(--shiki-light-font-style);
+  font-weight: var(--shiki-light-font-weight);
+  text-decoration: var(--shiki-light-text-decoration);
+}
+
+html[data-theme='dark'] .shiki-token {
+  color: var(--shiki-dark);
+  font-style: var(--shiki-dark-font-style);
+  font-weight: var(--shiki-dark-font-weight);
+  text-decoration: var(--shiki-dark-text-decoration);
+}

website/src/css/custom.css

@@ -0,0 +1,74 @@
+/**
+ * Swizzled from @docusaurus/theme-classic to highlight code with Shiki instead of Prism. The Prism-shaped
+ * line and token props are kept, so the theme's Line component still renders line numbers and highlighted lines.
+ */
+import React, {useMemo} from 'react';
+import clsx from 'clsx';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Line from '@theme/CodeBlock/Line';
+import {highlight} from './shiki';
+import styles from './styles.module.css';
+
+const Pre = React.forwardRef((props, ref) => {
+  return (
+    <pre
+      ref={ref}
+      /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
+      tabIndex={0}
+      {...props}
+      className={clsx(props.className, styles.codeBlock, 'thin-scrollbar')}
+    />
+  );
+});
+
+function Code(props) {
+  const {metadata} = useCodeBlockContext();
+  return (
+    <code
+      {...props}
+      className={clsx(
+        props.className,
+        styles.codeBlockLines,
+        metadata.lineNumbersStart !== undefined && styles.codeBlockLinesWithNumbering,
+      )}
+      style={{
+        ...props.style,
+        counterReset: metadata.lineNumbersStart === undefined ? undefined : `line-count ${metadata.lineNumbersStart - 1}`,
+      }}
+    />
+  );
+}
+
+function getLineProps({className}) {
+  return {className: clsx('token-line', className)};
+}
+
+function getTokenProps({token}) {
+  return {className: 'token shiki-token', style: token.style, children: token.content};
+}
+
+export default function CodeBlockContent({className}) {
+  const {metadata, wordWrap} = useCodeBlockContext();
+  const {code, language, lineNumbersStart, lineClassNames} = metadata;
+  const lines = useMemo(
+    () => highlight(code, language).map((line) => line.map((token) => ({content: token.content, style: token.htmlStyle}))),
+    [code, language],
+  );
+
+  return (
+    <Pre ref={wordWrap.codeBlockRef} className={clsx(className, `language-${language}`)}>
+      <Code>
+        {lines.map((line, i) => (
+          <Line
+            key={i}
+            line={line}
+            getLineProps={getLineProps}
+            getTokenProps={getTokenProps}
+            classNames={lineClassNames[i]}
+            showLineNumbers={lineNumbersStart !== undefined}
+          />
+        ))}
+      </Code>
+    </Pre>
+  );
+}

website/src/theme/CodeBlock/Content/index.js

@@ -0,0 +1,28 @@
+import {createHighlighterCoreSync} from 'shiki/core';
+import {createJavaScriptRegexEngine} from 'shiki/engine/javascript';
+import csharp from '@shikijs/langs/csharp';
+import json from '@shikijs/langs/json';
+import shellscript from '@shikijs/langs/shellscript';
+import yaml from '@shikijs/langs/yaml';
+import darkPlus from '@shikijs/themes/dark-plus';
+import lightPlus from '@shikijs/themes/light-plus';
+
+// The Visual Studio Code themes, matching prismThemes.vsLight and prismThemes.vsDark in docusaurus.config.js,
+// which style the rest of the code block.
+const themes = {light: 'light-plus', dark: 'dark-plus'};
+
+// Synchronous, so code blocks render the same on the server and in the browser.
+const highlighter = createHighlighterCoreSync({
+  themes: [lightPlus, darkPlus],
+  langs: [csharp, json, shellscript, yaml],
+  engine: createJavaScriptRegexEngine(),
+});
+
+/**
+ * Tokenizes code into lines of tokens, each styled with both themes' colors as CSS variables
+ * (--shiki-light and --shiki-dark), which custom.css applies for the current color mode.
+ */
+export function highlight(code, language) {
+  const lang = highlighter.getLoadedLanguages().includes(language) ? language : 'text';
+  return highlighter.codeToTokens(code, {lang, themes, defaultColor: false}).tokens;
+}