mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-15 23:52:23 -06:00
d7e4a808b5
This PR is motivated from https://github.com/just-the-docs/just-the-docs/pull/1259#issuecomment-1655899503. It adds a new workflow (`CI / Validate HTML (3.1)`) that validates the output of `bundle exec jekyll build`. It does this with two separate tools: 1. The [`html5validator-action`](https://github.com/Cyb3r-Jak3/html5validator-action), which is a wrapper (Docker image + argument forwarding) around the [Nu HTML checker](https://github.com/validator/validator), which is what is used by the [W3C markup validation service](https://validator.w3.org/) 2. [`html-proofer`](https://github.com/gjtorikian/html-proofer), which performs auxiliary checks on the validity of script, image, and link *values*, but not the markup itself - note: prior versions of `html-proofer` did use nokogiri to also validate HTML, but the author has elected to remove that feature in versions 4+ I then fix a few issues that are flagged by these tools. I'll split this into, **changes affecting users**: - strictly incorrect: in `_layouts/minimal.html`, a `<div>` had duplicate `id`s. I've removed the incorrect one, which is related to... - semantically wrong (but not technically incorrect): in both `minimal` and `default` layouts, we had two `<div>` tags with `id="main-content-wrap"`. These don't do anything; the associated styling is with the *class* `main-content-wrap`. I've elected to remove these `id`s to avoid confusion and keep the layouts in sync; however, **this is technically a breaking change** - observe that `#main-content` is used for the "skip to main content" feature, which I missed in an earlier iteration of this PR **changes affecting only our documentation** - a broken link to mermaid docs (I've changed it to a valid one) - an incorrectly-specified `aux_link` to our own repository - various links that point to the bare URL `another-page`, which is clearly invalid; I've changed these to point to our homepage - an incorrect header link - various links to `http://example.com`, which I've changed to point to our homepage - an incorrect link to `@flyx`'s profile for the AsciiDoctor gist - a handful of (otherwise-valid) `http` links that should be `https`: the lunr docs, and patrick's personal website The commit history shows the Nu validator flagging issues in CI properly in commits [4128b23](4128b23ef2) and [3527220](35272203ba). ## relevant configuration - I exclude `github.com` URLs from external link checks with `html-proofer`. This is because GitHub does not like it when we ping too frequently, and rate limits us, which in turn provides many false positives. This is aligned with their documentation, which uses this ignore. - I've pinned the hash for the 3rd-party action that wraps the W3C markup validation service. This aligns with #1148, but means that we'll have to keep an eye on it for updates.
110 lines
3.0 KiB
YAML
110 lines
3.0 KiB
YAML
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
pull_request:
|
|
branches:
|
|
- main
|
|
|
|
name: CI
|
|
|
|
jobs:
|
|
jekyll-build:
|
|
name: Build (jekyll gem)
|
|
strategy:
|
|
fail-fast: false
|
|
matrix:
|
|
jekyll-version: [3.9, 4.3]
|
|
os: [ ubuntu-latest, macos-latest, windows-latest ]
|
|
ruby-version: [2.7, 3.1]
|
|
runs-on: ${{ matrix.os }}
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Setup Ruby ${{ matrix.ruby-version }}
|
|
uses: ruby/setup-ruby@v1
|
|
with:
|
|
ruby-version: ${{ matrix.ruby-version }}
|
|
bundler-cache: false
|
|
- name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
|
|
run: bundle install
|
|
env:
|
|
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
|
- name: Init Search
|
|
run: bundle exec rake search:init
|
|
env:
|
|
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
|
- name: Build Site
|
|
run: bundle exec jekyll build
|
|
env:
|
|
BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
|
|
|
|
github-pages-build:
|
|
name: Build (github-pages gem)
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Setup Ruby
|
|
uses: ruby/setup-ruby@v1
|
|
with:
|
|
ruby-version: '3.1'
|
|
bundler-cache: false
|
|
- name: Bundle Install
|
|
run: bundle install
|
|
env:
|
|
BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
|
|
- name: Build Site
|
|
run: bundle exec jekyll build
|
|
env:
|
|
BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
|
|
|
|
validate:
|
|
name: Validate HTML
|
|
strategy:
|
|
fail-fast: false
|
|
matrix:
|
|
ruby-version: [3.1]
|
|
runs-on: ubuntu-latest
|
|
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Setup Ruby ${{ matrix.ruby-version }}
|
|
uses: ruby/setup-ruby@v1
|
|
with:
|
|
ruby-version: ${{ matrix.ruby-version }}
|
|
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
|
|
cache-version: 0 # Increment this number if you need to re-download cached gems
|
|
- name: Cache HTMLProofer
|
|
id: cache-htmlproofer
|
|
uses: actions/cache@v2
|
|
with:
|
|
path: tmp/.htmlproofer
|
|
key: ${{ runner.os }}-htmlproofer
|
|
- name: Build Site
|
|
run: bundle exec jekyll build
|
|
- name: Test with Nu Validator
|
|
uses: Cyb3r-Jak3/html5validator-action@c7bb77a0fe3b0458583de50fd0f4dd819569b8a9
|
|
with:
|
|
root: _site
|
|
blacklist: line-numbers
|
|
- name: Test with html-proofer
|
|
run: bundle exec htmlproofer _site --ignore-urls "/github.com/"
|
|
env:
|
|
NOKOGIRI_USE_SYSTEM_LIBRARIES: true
|
|
|
|
assets:
|
|
name: Test CSS and JS
|
|
runs-on: ubuntu-latest
|
|
|
|
strategy:
|
|
matrix:
|
|
node-version: [18.x]
|
|
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Use Node.js ${{ matrix.node-version }}
|
|
uses: actions/setup-node@v1
|
|
with:
|
|
node-version: ${{ matrix.node-version }}
|
|
- run: npm install
|
|
- run: npm test
|