Merge pull request #113 from makeabilitylab/feat/htmlproofer-gate

Add html-proofer link-check gate (+ complementary check_a11y) (#110)

Author: jonfroehlich

.github/workflows/content-lint.yml

@@ -27,3 +27,64 @@ jobs:
 
       - name: Check per-page SEO front matter (description:)
         run: python scripts/check_seo_frontmatter.py
+
+  media-a11y:
+    # Source-level a11y conventions that html-proofer does NOT cover: YouTube
+    # iframe title=, <video> aria-label, and lazy empty alt (alt=""). See
+    # scripts/check_a11y.py. Complements the link-check job below.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Check media a11y (iframe title, video aria-label, image alt)
+        run: python scripts/check_a11y.py --ci
+
+  link-check:
+    # Validate the BUILT site with html-proofer: broken internal links, broken
+    # anchors, missing image alt, and malformed HTML. External links are NOT
+    # checked here (slow/flaky); a separate non-blocking job can cover those.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.11"
+          bundler-cache: true
+          cache-version: 0
+
+      - name: Build site (production baseurl)
+        run: bundle exec jekyll build --baseurl "/physcomp"
+        env:
+          JEKYLL_ENV: production
+
+      - name: Install html-proofer
+        run: gem install html-proofer -v 5.0.9
+
+      - name: Proof built site (internal links, anchors, image alt, HTML)
+        # --swap-urls strips the /physcomp baseurl so absolute internal links
+        # resolve against _site/. External link checking is disabled (slow/flaky).
+        #
+        # --ignore-files: each entry is tracked debt, not a silent skip:
+        #   * signals .+/index.html + IntroTo*.html -> stale generated nbconvert
+        #                                              notebooks               (issue #115)
+        #   * /arduino/accel.html          -> WIP draft, missing screenshot    (issue #115)
+        #   * /esp32/capacitive-touch.html -> WIP lesson, missing diagrams      (issue #114)
+        # Remove an entry once its issue is resolved so the gate covers that page.
+        # Each --ignore-files pattern must be wrapped in /slashes/ to be treated
+        # as a regex (a bare string is an exact-path match); internal slashes are
+        # escaped as \/.
+        run: |
+          htmlproofer ./_site \
+            --disable-external \
+            --swap-urls "^/physcomp:" \
+            --no-enforce-https \
+            --ignore-files "/\/signals\/.+\/index\.html/,/\/signals\/IntroTo[A-Za-z]+\.html/,/\/arduino\/accel\.html/,/\/esp32\/capacitive-touch\.html/"

_config.yml

@@ -102,7 +102,7 @@ callouts:
 # Aux links for the upper right navigation
 aux_links:
   "Makeability Lab":
-    - "//makeabilitylab.cs.washington.edu"
+    - "https://makeabilitylab.cs.washington.edu"
 
 # Heading anchor links appear on hover over h1-h6 tags in page content
 # allowing users to deep link to a particular heading on a page.

advancedio/assets/videos/AdafruitSTEMMAQT_IMG_6163-TrimmedAndCropped720p.mp4

@@ -372,7 +372,7 @@ The Engineering Mindset YouTube channel did this for real with an oscilloscope,
 
 ### Activity 3: Sensor-driven servo gauge
 
-For our final activity, let's build a **physical gauge**—a servo-powered pointer that displays sensor data in the real world, like an analog speedometer or a VU meter needle. This is the physical output equivalent of the [OLED analog graph](oled.md#demo-3-basic-real-time-analog-graph) and the [NeoPixel level meter](addressable-leds.md#activity-4-led-level-meter). Where the OLED drew data on screen and the NeoPixels lit up LEDs proportionally, here we'll sweep a physical pointer across a scale.
+For our final activity, let's build a **physical gauge**—a servo-powered pointer that displays sensor data in the real world, like an analog speedometer or a VU meter needle. This is the physical output equivalent of the [OLED analog graph](oled.md#demo-3-basic-real-time-analog-graph) and the [NeoPixel level meter](addressable-leds.md). Where the OLED drew data on screen and the NeoPixels lit up LEDs proportionally, here we'll sweep a physical pointer across a scale.
 
 We'll read an analog sensor on `A0` and map it to the servo's range. To make it more interesting, we'll add two buttons: one to "freeze" the gauge at its current reading (like a max-hold feature on a multimeter), and one to reset it.
 

advancedio/servo.md

@@ -157,7 +157,7 @@ You can find our full implementation on GitHub as [MovingAverageFilter.ino](http
 
 #### Simple C++ class
 
-Signal filtering is a perfect opportunity to create a class to hide complexity, avoid code redundancy, and handle data processing. In our [Makeability Lab Arduino Library](https://github.com/makeabilitylab/arduino/tree/master/MakeabilityLab_Arduino_Library/src), we created the [`MovingAveragefilter.hpp`](https://github.com/makeabilitylab/arduino/blob/master/MakeabilityLab_Arduino_Library/src/MovingAverageFilter.hpp) class, which simplifies using a moving average filter. But you could make your own, of course, or use [other libraries](#arduino-filtering-libraries.)
+Signal filtering is a perfect opportunity to create a class to hide complexity, avoid code redundancy, and handle data processing. In our [Makeability Lab Arduino Library](https://github.com/makeabilitylab/arduino/tree/master/MakeabilityLab_Arduino_Library/src), we created the [`MovingAveragefilter.hpp`](https://github.com/makeabilitylab/arduino/blob/master/MakeabilityLab_Arduino_Library/src/MovingAverageFilter.hpp) class, which simplifies using a moving average filter. But you could make your own, of course, or use [other libraries](#arduino-filtering-libraries)
 
 Here's a demonstration of how to use [`MovingAveragefilter.hpp`](https://github.com/makeabilitylab/arduino/blob/master/MakeabilityLab_Arduino_Library/src/MovingAverageFilter.hpp):
 

advancedio/smoothing-input.md

@@ -608,7 +608,7 @@ In this lesson, you learned about vibration motors and how to safely control the
 
 ## Next Lesson
 
-In the [next lesson](../smoothing-input.md), we will switch from output to input and learn how to smooth noisy sensor data using digital signal processing techniques.
+In the [next lesson](smoothing-input.md), we will switch from output to input and learn how to smooth noisy sensor data using digital signal processing techniques.
 
 <nav class="lesson-nav" aria-label="Lesson navigation">
   <a href="servo.html" class="nav-prev">

advancedio/vibromotor.md

@@ -181,7 +181,7 @@ However, if you do this, what will the digital input pin read when the switch is
 **Figure.** Animation of what happens when you press a button with the simple circuit configuration.
 {: .fs-1 }
 
-In fact, try wiring up this configuration yourself and running the following program with the [Serial Monitor](../electronics/serial-print#step-3-open-serial-monitor-in-the-arduino-ide) open. What happens when you press the button? Try touching the button legs with your fingers but not actually pressing the button—what happens to the `digitalRead` value? Are you reliably tracking the button state?
+In fact, try wiring up this configuration yourself and running the following program with the [Serial Monitor](serial-print.md#step-3-open-serial-monitor-in-the-arduino-ide) open. What happens when you press the button? Try touching the button legs with your fingers but not actually pressing the button—what happens to the `digitalRead` value? Are you reliably tracking the button state?
 
 {% highlight cpp %}
 const int INPUT_BUTTON_PIN = 2;

arduino/buttons.md

@@ -10,7 +10,7 @@ usetocbot: true
 
 ## Speeding up the Arduino
 
-The Arduino `C` library attempts to provide an easy-to-understand and accessible API to program and use microcontrollers. However, this comes at a cost. There are a number of interesting online discussions and blog posts analyzing Arduino code and providing faster techniques for I/O. Importantly, as Willem Maes—a faculty of engineering in Belgium—notes in his [Speeding Up the Arduino]((http://www.optiloading.be/willem/Arduino/speeding.pdf)) document: 
+The Arduino `C` library attempts to provide an easy-to-understand and accessible API to program and use microcontrollers. However, this comes at a cost. There are a number of interesting online discussions and blog posts analyzing Arduino code and providing faster techniques for I/O. Importantly, as Willem Maes—a faculty of engineering in Belgium—notes in his [Speeding Up the Arduino](http://www.optiloading.be/willem/Arduino/speeding.pdf) document: 
 >the programmers who developed  Arduino weren't just lousy coders who couldn't write fast code, they consciously made the decision to add validations and safety checks since it benefits their target customers.
 
 ## How fast can we read data using analogRead and ATmega328? 

arduino/fast-analog-read.md

@@ -104,7 +104,7 @@ For more details, see the Interlink [FSR 402 datasheet]({{ site.baseurl }}/asset
 
 Let's make something!
 
-To begin, just like we did with the [buttons](buttons.md) and [potentiometers](potentiometers.md) lessons, we'll make a simple LED circuit without a microcontroller. In fact, this circuit will be the exact same as the "rheostat" potentiometer circuit [here](potentiometers.md#build-the-potentiometer-based-led-dimmer) (but we'll replace the rheostat with an FSR).
+To begin, just like we did with the [buttons](buttons.md) and [potentiometers](potentiometers.md) lessons, we'll make a simple LED circuit without a microcontroller. In fact, this circuit will be the exact same as the "rheostat" potentiometer circuit [here](potentiometers.md#step-1-build-the-potentiometer-based-led-dimmer) (but we'll replace the rheostat with an FSR).
 
 Below, we show two possible wiring diagrams: the first (preferred) shows the FSR circuit powered by a 9V battery while the second shows power derived from the 5V and GND pins on the Arduino. (Again, we prefer the former just to further emphasize that at this point, we're not using microcontrollers!)
 

arduino/force-sensitive-resistors.md

@@ -126,7 +126,7 @@ On the Arduino, the `unsigned long` data type is 32 bits (4 bytes), which ranges
 
 #### Blinking without delays logic
 
-We then use the same general logic as the "blinking without delays" [covered previously](led-blink#blink-without-using-delays) for each LED:
+We then use the same general logic as the "blinking without delays" [covered previously](led-blink.md#blink-without-using-delay) for each LED:
 
 {% highlight C %}
 unsigned long currentTimestampMs = millis();