fix(website): finish the monorepo website with publish-only deploys, demo playback and checked anchors

.github/workflows/build.yml

@@ -180,25 +180,18 @@ jobs:
         with:
           node-version: 'lts/*'
           cache: 'npm'
-      - id: workspaces
-        if: steps.dist-cache.outputs.cache-hit != 'true'
-        run: |
-          args=""
-          for ws in packages/alphatab packages/alphatex packages/transpiler packages/tooling packages/lsp packages/monaco packages/webpack packages/vite packages/react; do
-            if [ -f "$ws/package.json" ]; then args="$args -w $ws"; fi
-          done
-          echo "args=$args" >> "$GITHUB_OUTPUT"
       - if: steps.dist-cache.outputs.cache-hit != 'true'
-        run: npm ci $WORKSPACES --include-workspace-root
-        env:
-          WORKSPACES: ${{ steps.workspaces.outputs.args }}
+        run: >
+          npm ci --include-workspace-root
+          -w packages/alphatab -w packages/alphatex -w packages/transpiler -w packages/tooling
+          -w packages/lsp -w packages/monaco -w packages/webpack -w packages/vite -w packages/react
       - if: steps.dist-cache.outputs.cache-hit != 'true'
         run: npm run build-web
       - if: steps.dist-cache.outputs.cache-hit != 'true'
         run: npm run build-language-server
       - if: steps.dist-cache.outputs.cache-hit != 'true'
         run: npm run build-monaco
-      - if: steps.dist-cache.outputs.cache-hit != 'true' && hashFiles('packages/react/package.json') != ''
+      - if: steps.dist-cache.outputs.cache-hit != 'true'
         run: npm run build -w packages/react
       - if: steps.dist-cache.outputs.cache-hit != 'true'
         run: node scripts/check-published-types.mts
@@ -266,14 +259,7 @@ jobs:
           path: ~/.npm
           key: npm-website-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
           restore-keys: npm-website-${{ runner.os }}-
-      - id: workspaces
-        run: |
-          args="-w website"
-          if [ -f packages/ui/package.json ]; then args="$args -w packages/ui"; fi
-          echo "args=$args" >> "$GITHUB_OUTPUT"
-      - run: npm ci $WORKSPACES --include-workspace-root
-        env:
-          WORKSPACES: ${{ steps.workspaces.outputs.args }}
+      - run: npm ci --include-workspace-root -w website -w packages/ui
       - uses: actions/download-artifact@v8
         with:
           name: web-dist

.github/workflows/~publish_website.yml

@@ -90,21 +90,12 @@ jobs:
           path: ~/.npm
           key: npm-website-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
           restore-keys: npm-website-${{ runner.os }}-
-      - id: workspaces
-        run: |
-          args="-w website"
-          if [ -f packages/ui/package.json ]; then args="$args -w packages/ui"; fi
-          # building react from source needs the alphaTab sources and the shared build tooling
-          if [ -f packages/react/package.json ]; then
-            args="$args -w packages/react -w packages/alphatab -w packages/transpiler -w packages/tooling"
-          fi
-          echo "args=$args" >> "$GITHUB_OUTPUT"
-      - run: npm ci $WORKSPACES --include-workspace-root
-        env:
-          WORKSPACES: ${{ steps.workspaces.outputs.args }}
+      # building react from source needs the alphaTab sources and the shared build tooling
+      - run: >
+          npm ci --include-workspace-root -w website -w packages/ui
+          -w packages/react -w packages/alphatab -w packages/transpiler -w packages/tooling
 
-      - if: hashFiles('packages/react/package.json') != ''
-        run: |
+      - run: |
           npm run generate-typescript
           npm run build -w packages/react
 
@@ -150,7 +141,7 @@ jobs:
 
   deploy:
     needs: build
-    if: ${{ !cancelled() && needs.build.result == 'success' && !inputs.dry_run && vars.WEBSITE_DEPLOY_ENABLED == 'true' }}
+    if: ${{ !cancelled() && needs.build.result == 'success' && !inputs.dry_run }}
     runs-on: ubuntu-latest
     environment:
       name: website

website/docs/alphatex/syntax.mdx

@@ -12,6 +12,7 @@ keywords:
   - fret notation
 ---
 
+import Link from '@docusaurus/Link';
 import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
 
 This page describes the alphaTex source syntax and defines the vocabulary the rest of the reference uses. Every other page links back to the anchors here on first use of a term. Save alphaTex source with the file extension `.atex`.
@@ -55,10 +56,10 @@ Examples:
 
 ## Argument lists {#argument-lists}
 
-<a id="argument-list"></a>
+<Link id="argument-list" />
 An **argument list** is the group of values you pass into a metadata tag or a property. Wrap multiple values in parentheses. Omit the parentheses when you pass a single value.
 
-<a id="argument"></a><a id="parameter"></a>
+<Link id="argument" /><Link id="parameter" />
 Each entry inside the list is called an **argument**. The reference tables describe the matching **parameters** — the positional slots that the language accepts for a given construct.
 
 An argument can be:
@@ -83,7 +84,7 @@ Argument entries are separated by whitespace. Commas are not used.
 
 ## Properties {#properties}
 
-<a id="property"></a>
+<Link id="property" />
 A **property** is a `name arguments` pair inside curly braces. Properties attach to beats, notes, and metadata tags to add effects, visibility flags, and other optional aspects.
 
 Property names are case-insensitive. The argument list of a property follows the rules in [Argument lists](#argument-lists).
@@ -96,7 +97,7 @@ C4 { b (0 4) v txt "Bend with Vibrato" }
 
 ## Metadata tags {#metadata-tags}
 
-<a id="metadata-tag"></a>
+<Link id="metadata-tag" />
 A **metadata tag** is a backslash-prefixed construct of the form `\name arguments {properties}`. The argument list and the property block are both optional; individual tags decide which arguments and properties they accept.
 
 Metadata tag names are case-insensitive.
@@ -145,7 +146,7 @@ A property attached to a single note, controlling effects specific to that note.
 
 Every reference entry lists one or more **signatures**. A signature is one accepted parameter list for the construct — the parameters it names, their types, and their order. When you write a metadata tag or a property, your argument list must match exactly one of its signatures.
 
-<a id="overload"></a>
+<Link id="overload" />
 A construct with more than one signature is **overloaded**. `\title`, for example, accepts a single string in one signature and a title-plus-template-plus-alignment triple in another. The reference page for each construct shows every signature it accepts.
 
 ## Case sensitivity {#case-sensitivity}

website/docs/guides/exporter.mdx

@@ -66,7 +66,7 @@ using(var fs = new System.IO.FileStream(fileName, System.IO.FileMode.Create))
 Starting with 1.7.0 alphaTab can also export the data model to its own music notation language [alphaTex](/docs/alphatex/introduction).
 The exporter supports all features which the importer can also handle. If you find something, please open a feature request. 
 
-Via the exporter settings [`settings.exporter`](/docs/reference/settings.mdx#Exporter) the format of the exported code can be adjusted.
+Via the exporter settings [`settings.exporter`](/docs/reference/settings.mdx#exporter) the format of the exported code can be adjusted.
 Especially the `comments` can be quite useful for alphaTex beginners to learn about the syntax.
 
 While you can use the standard `export` to export the code into a byte array, you can also use `exportToString` to get the alphaTex code

website/docs/releases/release1_7.mdx

@@ -195,7 +195,7 @@ The details are now documented in the new [language documentation](/docs/alphate
 Two key changes in the language, compared to 1.6, are:
 
 * The documents do not need to be separated with dots into 3 sections anymore. See [Document Structure](/docs/alphatex/document-structure).
-* Metadata tags and properties now follow more a function call approach where values are passed as arguments into them. Single values do not need parenthesis but multiple values should be wrapped. [See Parameters](/docs/alphatex/syntax#parameters--argument-lists).
+* Metadata tags and properties now follow more a function call approach where values are passed as arguments into them. Single values do not need parenthesis but multiple values should be wrapped. [See Parameters](/docs/alphatex/syntax#argument-lists).
 
 #### alphaTex: Language Server and Monaco Integration
 https://github.com/CoderLine/alphaTab/pull/2379

website/docusaurus.config.mts

@@ -208,6 +208,7 @@ async function createConfig(): Promise<Config> {
   organizationName: "CoderLine",
   projectName: "alphaTab",
   onBrokenLinks: "throw",
+  onBrokenAnchors: "throw",
   future: {
     v4: {
       removeLegacyPostBuildHeadAttribute: true,

website/scripts/generate-common.mts

@@ -84,6 +84,11 @@ export type ReferencePage = {
   url: string
 };
 
+
+function categoryAnchor(category: string) {
+  return category.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
 export class ReferenceTableData {
   public readonly categories = new Map<string, ReferencePage[]>();
 
@@ -108,6 +113,7 @@ export async function writeReferenceTable(
 
   await table.writeLine(`import { CodeBadge } from "@site/src/components/CodeBadge";`);
   await table.writeLine(`import { Signature } from "@site/src/components/Signature";`);
+  await table.writeLine(`import Link from "@docusaurus/Link";`);
   await table.writeLine();
   await table.writeLine(`<table className="table table-striped table-condensed reference-table">`);
   await table.writeLine(`  <thead>`);
@@ -125,7 +131,7 @@ export async function writeReferenceTable(
 
 
   for (const [category, pages] of categoriesSorted) {
-    await table.writeLine(`    <tr><th colSpan="4">${category}</th></tr>`);
+    await table.writeLine(`    <tr><th colSpan="4"><Link id="${categoryAnchor(category)}" />${category}</th></tr>`);
 
     const sorted = pages
       .sort((a, b) => {

website/scripts/generate-typedocs.mts

@@ -301,7 +301,7 @@ async function writeEnumMembers(
     await fileStream.write(`    <tr>\n`);
 
     await fileStream.write(
-      `      <td id="${member.name.getText().toLowerCase()}">\`${member.name.getText()}\`</td>\n`
+      `      <td><Link id="${member.name.getText().toLowerCase()}" />\`${member.name.getText()}\`</td>\n`
     );
 
     const numericValue = context.checker.getConstantValue(member);

website/src/components/AlphaTabPetaluma/index.tsx

@@ -35,7 +35,6 @@ export const AlphaTabPetaluma: React.FC<AlphaTabPetalumaProps> = ({
 }) => {
   const tex = typeof children === "string" ? children : undefined;
   const site = useSiteAlphaTabSettings({
-    player: true,
     settings: {
       core: {
         // Plain object form is accepted by settings.fillFromJson at runtime;

website/src/components/AlphaTexExporterSample/index.tsx

@@ -75,7 +75,7 @@ const AlphaTexExporterInner: FC = () => {
 };
 
 export const AlphaTexExporterSample: FC = () => {
-    const site = useSiteAlphaTabSettings({ player: true });
+    const site = useSiteAlphaTabSettings();
     return (
         <AlphaTabProvider
             file="/files/Bach_Prelude_BWV999.gp"

website/src/components/AlphaTexLivePreview/index.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useRef, useState } from "react";
 import CodeBlock from "@theme/CodeBlock";
 import { AlphaTabHost, AlphaTabProvider } from "@coderline/alphatab-react";
 import { useSiteAlphaTabSettings } from "@site/src/alphatab-settings";
+import { DemoPlayButton } from "@site/src/components/DemoPlayButton";
 import * as Riffs from "@site/src/tex-riffs";
 import styles from "./styles.module.scss";
 
@@ -61,6 +62,7 @@ document.getElementById('tex-input').addEventListener('input', (e) => {
           spellCheck={false}
           onChange={(e) => onChange(e.target.value)}
         />
+        <DemoPlayButton />
         <AlphaTabHost />
       </AlphaTabProvider>
       {showCode ? <CodeBlock language="js">{code}</CodeBlock> : null}

website/src/components/BarRangeDemo/index.tsx

@@ -40,7 +40,7 @@ export const BarRangeDemo: React.FC<BarRangeDemoProps> = ({
     () => ({ display: { startBar, barCount } }),
     [startBar, barCount],
   );
-  const site = useSiteAlphaTabSettings({ player: true, settings: rangeSettings });
+  const site = useSiteAlphaTabSettings({ settings: rangeSettings });
 
   const useTex = !file;
   const texContent = useTex ? tex ?? DEFAULT_TEX : undefined;

website/src/components/BoundsLookupViewer/index.tsx

@@ -197,7 +197,7 @@ export const BoundsLookupViewer: React.FC<BoundsLookupViewerProps> = ({
   };
 
   const tex = typeof children === "string" ? children : undefined;
-  const site = useSiteAlphaTabSettings({ player: true, settings: NOTE_BOUNDS_SETTINGS });
+  const site = useSiteAlphaTabSettings({ settings: NOTE_BOUNDS_SETTINGS });
 
   return (
     <>

website/src/components/BracketModeSwitch/index.tsx

@@ -37,7 +37,7 @@ export const BracketModeSwitch: React.FC<BracketModeSwitchProps> = ({
   showCode = true,
 }) => {
   const [mode, setMode] = useState<ModeName>("GroupStaves");
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const code = `api.scoreLoaded.on((score) => {
   score.stylesheet.bracketExtendMode =

website/src/components/BytesLoadDemo/index.tsx

@@ -125,7 +125,7 @@ export const BytesLoadDemo: React.FC<BytesLoadDemoProps> = ({
 }) => {
   const [byteCount, setByteCount] = useState<number | null>(null);
   const [format, setFormat] = useState<string>("");
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const code = `const bytes = new Uint8Array(
   await fetch('/scores/song.gp').then((r) => r.arrayBuffer())

website/src/components/ChordDiagramLayoutSwitch/index.tsx

@@ -37,7 +37,7 @@ export const ChordDiagramLayoutSwitch: React.FC<
   ChordDiagramLayoutSwitchProps
 > = ({ showCode = true }) => {
   const [placement, setPlacement] = useState<Placement>("Top");
-  const site = useSiteAlphaTabSettings({ player: true, settings: BAR_COUNT_SETTINGS });
+  const site = useSiteAlphaTabSettings({ settings: BAR_COUNT_SETTINGS });
 
   const code = `api.scoreLoaded.on((score) => {
   score.stylesheet.globalDisplayChordDiagramsOnTop = ${placement === "Top"};

website/src/components/ColoringExample/index.tsx

@@ -85,7 +85,7 @@ function ApplyColors() {
 export const ColoringExample: React.FC<ColoringExampleProps> = ({
   showCode = true,
 }) => {
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const codeLines = `
   const api = new alphaTab.AlphaTabApi(...);

website/src/components/CoveragePaletteDemo/index.tsx

@@ -38,7 +38,7 @@ export const CoveragePaletteDemo: React.FC<CoveragePaletteDemoProps> = ({
     () => ({ display: { resources: palette } }),
     [palette],
   );
-  const site = useSiteAlphaTabSettings({ player: true, settings: paletteSettings });
+  const site = useSiteAlphaTabSettings({ settings: paletteSettings });
 
   const set = (key: Field, value: string) => {
     setPalette((p) => ({ ...p, [key]: value }));

website/src/components/DemoPlayButton/index.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import * as alphaTab from "@coderline/alphatab";
+import { useAlphaTabApi, useAlphaTabEventValue } from "@coderline/alphatab-react";
+import { IconPause, IconPlay } from "@coderline/alphatab-ui";
+import styles from "./styles.module.scss";
+
+const isPlayingState = (state: alphaTab.synth.PlayerState) => state === alphaTab.synth.PlayerState.Playing;
+
+/** Play/pause for the score of the surrounding `AlphaTabProvider`; disabled until the player is ready. */
+export const DemoPlayButton: React.FC<{ className?: string }> = ({ className }) => {
+  const api = useAlphaTabApi();
+  const ready = useAlphaTabEventValue("playerReady", () => true, (a) => a.isReadyForPlayback) ?? false;
+  const isPlaying =
+    useAlphaTabEventValue("playerStateChanged", (e) => isPlayingState(e.state), (a) => isPlayingState(a.playerState)) ??
+    false;
+
+  return (
+    <button
+      type="button"
+      className={`button button--primary button--sm ${styles.play} ${className ?? ""}`}
+      onClick={() => api?.playPause()}
+      disabled={!ready}
+      aria-busy={!ready}
+      aria-label={!ready ? "Preparing playback" : isPlaying ? "Pause" : "Play"}
+    >
+      {isPlaying ? <IconPause aria-hidden="true" /> : <IconPlay aria-hidden="true" />}
+    </button>
+  );
+};

website/src/components/DemoPlayButton/styles.module.scss

@@ -0,0 +1,5 @@
+.play {
+  align-self: flex-start;
+  display: inline-flex;
+  align-items: center;
+}

website/src/components/DirectImporterDemo/index.tsx

@@ -79,7 +79,7 @@ export const DirectImporterDemo: React.FC<DirectImporterDemoProps> = ({
   showCode = true,
 }) => {
   const [info, setInfo] = useState<InspectedScore | null>(null);
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const code = `import * as alphaTab from '@coderline/alphatab';
 

website/src/components/FormattingTemplateSample/index.tsx

@@ -58,7 +58,7 @@ const FormattingTemplateInner: React.FC = () => {
 };
 
 export const FormattingTemplateSample: React.FC = () => {
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const codeLines = `
   function adjustStyle(score: alphaTab.model.Score) {

website/src/components/Gp7ExporterDemo/index.tsx

@@ -105,7 +105,7 @@ const Gp7ExporterControls: React.FC = () => {
 export const Gp7ExporterDemo: React.FC<Gp7ExporterDemoProps> = ({
   showCode = true,
 }) => {
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
   return (
     <div>
       <AlphaTabProvider

website/src/components/GpVersionSwitcher/index.tsx

@@ -87,7 +87,7 @@ export const GpVersionSwitcher: React.FC<GpVersionSwitcherProps> = ({
   showCode = true,
 }) => {
   const [active, setActive] = useState<Variant>(INITIAL_VARIANT);
-  const site = useSiteAlphaTabSettings({ player: true });
+  const site = useSiteAlphaTabSettings();
 
   const code = `const api = new alphaTab.AlphaTabApi(container, {
   core: { file: '/scores/song.gp' }, // GP7/8 ZIP archive