Add HTML validator action (#579)

krassowski · web-flow · commit 485005dae979 · 2021-12-29T18:15:34.000-06:00
* Add HTML validator action (#1) * Add HTML validator action * Update root to `_site` * Update validate.yml * Update validate.yml * Update validate.yml * Add check-links * Update validate.yml * Add lighthouse and ignores for URLs * Add lighthouse config * Update validate.yml * Hash-pin `html5validator-action` * Try with nox * Set all thresholds to 0.95, correct noxfile * Update names as suggested in review * Add back the checkout step * Revert to building in jekyll container for speed Docker approach is way faster (1 minute vs 6.5 minutes) * Maybe we don't need to copy assets? * Fix some links, ignore netlify-preview from README.md * Fix link check, simplify naming * Add documentation, use absolute links in index * Fix wrong extension for img fallback * Two more places where absolute links needed * Fix jpg -> png in two more places
diff --git a/.github/workflows/lighthouserc.json b/.github/workflows/lighthouserc.json
@@ -0,0 +1,21 @@
+{
+  "ci": {
+    "collect": {
+      "staticDistDir": "./_site",
+      "autodiscoverUrlBlocklist": [
+        "conduct.html"
+      ],
+      "settings": {
+        "skipAudits": ["canonical"]
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.95 }],
+        "categories:accessibility": ["error", { "minScore": 0.95 }],
+        "categories:best-practices": ["error", { "minScore": 0.95 }],
+        "categories:seo": ["error", { "minScore": 0.95 }]
+      }
+    }
+  }
+}
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,108 @@
+name: Test
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Build Jekyll site for testing
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Build the site in the Jekyll/builder container
+      run: |
+        docker run \
+        -v ${{ github.workspace }}:/srv/jekyll -v ${{ github.workspace }}/_site:/srv/jekyll/_site \
+        jekyll/builder:latest /bin/bash -c "chmod -R 777 /srv/jekyll && jekyll build --future"
+
+    - name: List result of Jekyll build
+      run: |
+        ls _site/ -l
+        ls _site/assets -l
+
+    # - name: Copy assets
+    # run: cp -r assets _site/assets
+
+    - name: Publish built site
+      uses: actions/upload-artifact@v2
+      with:
+        name: Built site ${{ github.run_number }}
+        path: ./_site
+        if-no-files-found: error
+
+  validate:
+
+    runs-on: ubuntu-latest
+    name: Validate HTML
+    needs: [build]
+
+    steps:
+    - name: Fetch built site
+      uses: actions/download-artifact@v2
+      with:
+        name: Built site ${{ github.run_number }}
+        path: ./_site
+
+    # just to satisfy the `Cyb3r-Jak3/html5validator-action` action
+    - name: Create dummy git repository
+      run: git init
+
+    - name: HTML5 Validator
+      uses: Cyb3r-Jak3/html5validator-action@44696509d19bec6bd00e5ebf29bbeda320562aac
+      with:
+        root: _site/
+
+  check-links:
+
+    runs-on: ubuntu-latest
+    name: Check links
+    needs: [build]
+
+    steps:
+    - name: Fetch built site
+      uses: actions/download-artifact@v2
+      with:
+        name: Built site ${{ github.run_number }}
+        path: ./_site
+
+    - name: Install link check dependencies
+      run: pip install pytest-check-links
+
+    # TODO: we are not checking absolute links as pytest plugins does not support them
+    - name: Check links
+      run: |
+        pytest _site/ --check-links \
+           --check-links-ignore "https://.*linkedin.com/.*" \
+           --check-links-ignore "/" \
+           --check-links-ignore ".github/images/netlify-preview.png"
+
+  lighthouse:
+
+    runs-on: ubuntu-latest
+    name: Audit with Lighthouse
+    needs: [build]
+
+    steps:
+      - name: Fetch repository for `lighthouserc.json`
+        uses: actions/checkout@v2
+      - name: Fetch built site
+        uses: actions/download-artifact@v2
+        with:
+          name: Built site ${{ github.run_number }}
+          path: ./_site
+      - name: Audit with Lighthouse
+        uses: treosh/lighthouse-ci-action@v8
+        with:
+          configPath: ".github/workflows/lighthouserc.json"
+          temporaryPublicStorage: true
+          uploadArtifacts: true
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ To build and preview the site locally, follow these steps:
 3. **Run the `build` command**
    
    ```console
-   $ nox -s build
+   $ nox -s build-live
    ```
 
 
@@ -141,3 +141,16 @@ For images that are "above the fold" (that will be seen by users immediately aft
 ```html
 <img class="my-class" src="my/src.png" loading="eager" />
 ```
+
+### Automated quality checks
+
+A workflow on GitHub Actions is run at every push and for every pull request to ensure basic integrity of the website:
+- [validating](https://validator.w3.org/docs/help.html#validation_basics) the structure of the HTML using [Nu validator](https://validator.github.io/validator/) to ensure compliance with HTML standards
+- checking linked URLs for errors (including expired certificates)
+- running [Lighthouse](https://github.com/GoogleChrome/lighthouse) audits to ensure performance, accessibility, SEO optimization and best practices
+
+If pre-defined quality targets are not met, the jobs will fail.
+Click on "Details" link for the failing job to see what caused the failure.
+
+The detailed results will be available in the logs (which are only shown to users logged in on GitHub),
+including links to full Lighthouse reports on public temporary storage (the links will expire after 7 days).
diff --git a/binder.md b/binder.md
@@ -103,10 +103,10 @@ about the deployment. Here are a few useful resources in case you're interested:
   information about the BinderHub deployment at mybinder.org
 * [The mybinder.org billing repository](https://github.com/jupyterhub/binder-billing) has
   information about the cloud cost associated with running mybinder.org
-* [The mybinder.org site reliability guide](mybinder-sre.readthedocs.io/) is a resource
+* [The mybinder.org site reliability guide](https://mybinder-sre.readthedocs.io/en/latest/) is a resource
   for the operations team and the community to share best-practices and information about
   running the public BinderHub deployment at mybinder.org
-* [The mybinder.org incident reports page](mybinder-sre.readthedocs.io/en/latest/#incident-reports)
+* [The mybinder.org incident reports page](https://mybinder-sre.readthedocs.io/en/latest/#incident-reports)
   contains a list of incidents that have happened in the public deployment, as well as
   steps taken to resolve them.
 
@@ -123,7 +123,7 @@ to join our community and contribute code, time, comments, or appreciation.
   the current members of the JupyterHub and Binder teams.
 * [**The JupyterHub Contributing guide**](https://jupyterhub-team-compass.readthedocs.io/en/latest/contributing.html) is
   a great place to start learning how you can contribute to the Binder Project.
-* [**The Binder Gitter Channel**](https://gitter.im/binder) is where a lot of real-time
+* [**The Binder Gitter Channel**](https://gitter.im/jupyterhub/binder) is where a lot of real-time
   conversations happen in the Binder community.
 * [**The Binder Community Forum**](https://discourse.jupyter.org/c/binder) has a lot of
   community interaction and useful information about using, running, and contributing to Binder.
diff --git a/index.html b/index.html
@@ -38,10 +38,10 @@
     height: 627
   buttons:
   - class:
-    href: try
+    href: /try
     text: Try it in your browser
   - class: install-button
-    href: install
+    href: /install
     text: Install JupyterLab
 
 notebook:
@@ -54,10 +54,10 @@
     height: 627
   buttons:
   - class:
-    href: try
+    href: /try
     text: Try it in your browser
   - class: install-button
-    href: install
+    href: /install
     text: Install the Notebook
   features:
   - headline: Language of choice
@@ -112,7 +112,7 @@
       alt: icon to represent data
       src: assets/data.svg
   button:
-    href: hub
+    href: /hub
     text: Learn more about JupyterHub
 
 voila:
@@ -125,10 +125,10 @@
     height: 716
   buttons:
   - class:
-    href: try
+    href: /try
     text: Try it in your browser
   - class: install-button
-    href: install
+    href: /install
     text: Install Voilà
 
 open_standards:
@@ -287,7 +287,7 @@ <h4 class="jumbotron-text">{{ page.jumbotron.text }}</h4>
                     <div class="col-md-6">
                         <picture>
                             <source type="image/webp" srcset="{{ page.jupyterlab.image.src }}.webp">
-                            <img src="{{ page.jupyterlab.image.src }}.jpg"
+                            <img src="{{ page.jupyterlab.image.src }}.png"
                                  alt="{{ page.jupyterlab.image.alt }}"
                                  width={{ page.jupyterlab.image.width }}
                                  height={{ page.jupyterlab.image.height }}
@@ -319,7 +319,7 @@ <h4 class="nb-desc">{{ page.jupyterlab.description }}</h4>
                     <div class="col-md-6">
                         <picture>
                             <source type="image/webp" srcset="{{ page.notebook.image.src }}.webp">
-                            <img src="{{ page.notebook.image.src }}.jpg"
+                            <img src="{{ page.notebook.image.src }}.png"
                                  alt="{{ page.notebook.image.alt }}"
                                  width={{ page.notebook.image.width }}
                                  height={{ page.notebook.image.height }}
@@ -397,7 +397,7 @@ <h4>{{ feat.headline }}</h4>
                     <div class="col-md-6">
                         <picture>
                             <source type="image/webp" srcset="{{ page.voila.image.src }}.webp">
-                            <img src="{{ page.voila.image.src }}.jpg"
+                            <img src="{{ page.voila.image.src }}.png"
                                  alt="{{ page.voila.image.alt }}"
                                  width={{ img.width }}
                                  height={{ img.height }}
diff --git a/noxfile.py b/noxfile.py
@@ -12,7 +12,12 @@ def install_deps(session):
     session.run(*"bundle install".split())
     
 
+@nox.session(name="build-live", venv_backend='conda')
+def build_live(session):
+    install_deps(session)
+    session.run(*"bundle exec jekyll serve liveserve".split())
+
 @nox.session(venv_backend='conda')
 def build(session):
     install_deps(session)
-    session.run(*"bundle exec jekyll serve liveserve".split())
+    session.run(*"bundle exec jekyll build".split())
diff --git a/widgets.html b/widgets.html
@@ -323,7 +323,7 @@ <h3>Installation</h3>
             </span>
           </div>
           <p>
-          <a href="https://BeakerX.com">BeakerX</a> includes widgets
+          <a href="http://beakerx.com">BeakerX</a> includes widgets
           for interactive tables, plots, forms, Apache Spark, and more.
           The table widget automatically recognizes pandas dataframes
           and allows you to search, sort, drag, filter, format,
