Minor LaTex + Front Page Tweaks

.github/workflows/a11y.yml

@@ -0,0 +1,85 @@
+name: Accessibility Audit
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  check-a11y:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # - name: Run Accessibility Checks
+      #   uses: berkeley-cdss/myst-a11y@v1
+      # using: "composite"
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      # - name: Set up Python
+      #   uses: actions/setup-python@v4
+      #   with:
+      #     python-version: '3.11'
+      #     cache: 'pip'
+
+      - name: Install Dependencies
+        shell: bash
+        run: |
+          # Global tools needed for the action logic
+          npm install -g mystmd @axe-core/cli http-server wait-on
+          npx browser-driver-manager install chrome
+
+          # Handle dependencies being aware of environment
+          echo "Detected root package.json. Installing from root to support workspaces..."
+          # Install from root to ensure monorepo binaries are available
+          npm install
+
+          cd .
+
+          if [ -f "package.json" ]; then
+            echo "Detected package.json in . . Installing..."
+            npm install --prefer-offline
+          fi
+
+      - name: Build and Run Axe
+        shell: bash
+        run: |
+          cd .
+
+          # Ensure the build uses local node_modules if they exist
+          export PATH="$PATH:$(pwd)/node_modules/.bin:$(cd .. && pwd)/node_modules/.bin"
+
+          # Compile SCSS
+          npm run styles:build
+
+          # Run the build
+          myst build --html
+
+          mkdir -p staging
+          cp -r _build/html/* staging/
+
+          npx http-server staging -p 8080 -s &
+          npx wait-on http://localhost:8080/
+
+          cd _build/html
+          URLS=$(find . -name "*.html" -not -path "*/build/*" | sed 's|^\./||' | sed "s|^|http://localhost:8080/|" | tr '\n' ' ')
+
+          # Define the base command as an array
+          AXE_ARGS=("--tags" "wcag2a,wcag2aa,wcag21a,wcag21aa" "--save" "axe-report.json" "--exit")
+
+          # Add the exclude if it exists
+          if [ -n "" ]; then
+            AXE_ARGS+=("--exclude" "")
+          fi
+
+          # Execute without eval
+          npx axe $URLS "${AXE_ARGS[@]}"
+
+      - name: Upload Accessibility Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: axe-report
+          path: |
+            **/axe-report.json

.gitignore

@@ -21,14 +21,6 @@ output/
 # Commited for now, just to speed up publishing time.
 # _freeze
 
-# Quarto
-/env/
-_book
-.quarto/
-.quarto
-.jupyter_cache
-*.quarto_ipynb
-*_files/
 
 # The final Snap! manual compiled.
 snap-manual.tex
@@ -107,4 +99,5 @@ conversion/chapters/*
 _index_entries.txt
 index-list.quarto_ipynb
 
-/.quarto/
+# Claude and AI toools
+.claude/worktrees/

00-acknowledgements.md

@@ -1,5 +1,4 @@
 ---
-title: false
 ---
 
 :::{index}
@@ -35,21 +34,18 @@ single: Sussman, Gerald J.
 Xerox PARC
 :::
 
-:::{raw:latex}
-\chapter*{Acknowledgements}
-:::
-
-(sec-acknowledgements)=
++++{"no-pdf": true}
 # Acknowledgements
++++
 
+(sec-acknowledgements)=
 We have been extremely lucky in our mentors.
 Jens cut his teeth in the company of the Smalltalk pioneers: Alan Kay, Dan Ingalls,
 and the rest of the gang who invented personal computing and object oriented
 programming in the great days of Xerox PARC. He
 worked with John Maloney, of the MIT Scratch Team, who developed the Morphic graphics framework that's still at the heart of Snap<em>!</em>.
 
 <!-- The LaTeX styling on Snap! is broken w/ bold and italics.  -->
-
 <strong><em>The brilliant design of Scratch, from the Lifelong Kindergarten
 Group at the MIT Media Lab, is crucial to Snap!. Our earlier version, BYOB, was a direct modification of the Scratch source code. Snap! is a complete rewrite, but its code structure and its user interface remain deeply indebted to Scratch. And the Scratch Team, who could have seen us as rivals, have been entirely supportive and welcoming to us.</em></strong>
 

_latex-template/template.tex

@@ -12,7 +12,11 @@
 % improve assistive-tech behaviour without breaking the build.
 \DocumentMetadata{
   pdfversion = 2.0,
-  lang       = en-US,
+  lang = en-US,
+  tagging = on,
+  tagging-setup={math/setup={mathml-SE,mathml-AF},table/header-rows={1}},
+  % set the pdf standard that this document should comply with/be tested against
+  pdfstandard={ua-2}
 }
 
 % Body font size 11pt; TOC and footnotes drop to 10pt below.
@@ -232,6 +236,10 @@
 }
 \newcommand{\snapgridsep}{\hfill\ignorespaces}
 
+% TODO: Should this be shared somewhere with the web version?
+\newcommand{\snapversion}{12.0}
+
+% JupyterBook imports and packages
 [- IMPORTS -]
 
 \hypersetup{
@@ -310,7 +318,7 @@
     % Version on the blue panel.
     \node[anchor=north east, text=white, font=\fontsize{60}{60}\selectfont]
       at ([xshift=-1.5cm, yshift=-3cm]current page.north east)
-      {8.0};
+      {\snapversion};
 
     % Orange banner with the manual title (about 35% from top of
     % page). The title is bold small-caps (with the ! kept italic

_support/plugins/img-role.mjs

@@ -12,18 +12,20 @@ const imgRole = {
     width: { type: String, doc: 'CSS width, e.g. 200px or 50%.' },
     height: { type: String, doc: 'CSS height.' },
     title: { type: String, doc: 'Tooltip / title attribute.' },
+    role: { type: String, doc: 'Role for accessibility.', required: false },
   },
   run(data) {
-    const { alt, class: className, width, height, title } = data.options ?? {};
+    const { alt, class: className, width, height, title, role } = data.options ?? {};
     return [
       {
         type: 'image',
         url: data.body.trim(),
-        alt,
+        alt: alt,
         class: `image-inline ${className ? className : ''}`,
         width,
         height,
         title,
+        role: role || undefined,
       },
     ];
   },

_support/styles/snap-manual.scss

@@ -42,18 +42,47 @@
 // (bg-white/80, backdrop-blur, shadow) on a `.myst-top-nav` div; we override
 // them here rather than forking the theme. !important is needed to defeat
 // the Tailwind utility classes also targeting these elements.
-.myst-top-nav {
-  background-color: var(--berkeley-blue) !important;
-  backdrop-filter: none !important;
-  box-shadow: none !important;
-
-  // Force light foreground on top of berkeley-blue, regardless of the
-  // theme-supplied text-stone-* / dark:text-white utilities on children.
-  &, a, button, svg {
-    color: #FFF !important;
+.myst-top-nav.bg-white\/80,
+.myst-top-nav.dark\:bg-stone-900\/80:is(.dark *) {
+  background-color: var(--berkeley-blue);
+  backdrop-filter: none;
+  box-shadow: none;
+}
+
+// Light mode search bar and light mode toggle.
+.myst-top-nav.bg-white\/80 {
+  &, a, button, svg path {
+    color: #FFF;
+    border-color: #FFF;
+
+    // // Reset the color of the placeholder text in the search input
+    // & span, & path {
+    //   color: rgb(75 85 99/var(--tw-text-opacity,1));;
+    // }
+  }
+
+  & button.myst-search-bar {
+    // Reset the color of the placeholder text in the search input
+    & span, & path {
+      color: rgb(75 85 99/var(--tw-text-opacity,1));
+    }
   }
 }
 
+// Dark mode search bar and dark mode toggle.
+.myst-top-nav.dark\:bg-stone-900\/80:is(.dark *) {
+  &, a, button.myst-search-bar, svg {
+    color: #FFF;
+  }
+  & button.myst-search-bar {
+  // Reset the color of the placeholder text in the search input
+  & span, & path {
+    color: #FFF;
+  }
+  }
+}
+
+
 /* Designed to be the last element in a section / nav
 / Makes a little "puzzle piece" connector. */
 .trapezoid {
@@ -93,6 +122,13 @@ html.dark .menu-text code {
   background-color: unset;
 }
 
+.myst-home-link-logo.dark\:bg-white.dark\:rounded {
+  background-color: unset;
+}
+
+a.button {
+  background-color: var(--berkeley-medium);
+}
 
 // TODO: make latex env
 .image-1-5x {

index.md

@@ -2,22 +2,20 @@
 ---
 
 # Snap! Reference Manual
-<!--
-  Title intentionally omitted. The PDF cover page already carries
-  "Snap! Reference Manual"; emitting a frontmatter title here (or
-  the previous \chapter*{...} raw LaTeX call) caused a near-blank
-  duplicate-title page after the acknowledgements.
--->
-:::{raw:latex}
-\chapter*{The Snap\textit{!} Reference Manual}
-:::
+<!-- Editors Note: This page serves as the title and cover page when
+viewed on the web. It comes *after* the acknowledgements when in the PDF file,
+akin to a book. -->
+
++++{"no-pdf": true}
+{img alt="Snap! Manul Cover Image"}`images/cover-image.png`
++++
 
 ::: {.callout-note}
 ## This a work in progress!
 
-Welcome to the "new" Snap<em>!</em> manual. However, there are still many images and pages that need proper formatting and updates for version 11.
+Welcome to the "new" Snap<em>!</em> manual. However, there are still many images and pages that need proper formatting and updates for version 12.
 
-You may wish to [read a very nicely typeset version][pdf] of the manual.
+**You may wish to <u>[read a very nicely typeset version][pdf]</u> of the manual.**
 
 [pdf]: https://snap.berkeley.edu/snap/help/SnapManual.pdf
 :::
@@ -72,9 +70,8 @@ The "Manual + Blocks Reference" version includes both the manual and the blocks
 
 ### Reference the Snap<em>!</em> Manual
 
-![[DOI: 10.5281/zenodo.16892852](https://doi.org/10.5281/zenodo.16892852)](images/other/zenodo.17241865.svg)
-
-If you're writing a paper or book and want to reference the manual, please use the following citation:
+<!-- TODO: Convert to PNG for PDF -->
+[{inline alt="DOI: 10.5281/zenodo.16892852"}`images/other/zenodo.17241865.svg`](https://doi.org/10.5281/zenodo.16892852) If you're writing a paper or book and want to reference the manual, please use the following citation:
 
 ```
 @book{harvey_2025_17241865,
@@ -90,6 +87,8 @@ If you're writing a paper or book and want to reference the manual, please use t
 }
 ```
 
+<!-- TODO: Berkeley and SAP Logos -->
+
 ### License
 
-This work is licensed under <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International</a> {inline alt=""}`images/other/cc.svg` {inline alt=""}`images/other/by.svg` {inline alt=""}`images/other/nc.svg` {inline alt=""}`images/other/sa.svg`
+This work is licensed under <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International</a> {inline alt="cc"}`images/other/cc.svg` {inline alt="by"}`images/other/by.svg` {inline alt="nc"}`images/other/nc.svg` {inline alt="sa"}`images/other/sa.svg`