Fix incorrect HTML in theme & docs; validate HTML in CI (#1305)

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.

.github/workflows/ci.yml

@@ -57,6 +57,40 @@ jobs:
       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

Gemfile

@@ -6,3 +6,5 @@ gem "jekyll-github-metadata", ">= 2.15"
 gem "jekyll-include-cache", group: :jekyll_plugins
 
 gem "webrick", "~> 1.7"
+
+gem "html-proofer", "~> 5.0", :group => :development

_config.yml

@@ -102,7 +102,7 @@ heading_anchors: true
 # Aux links for the upper right navigation
 aux_links:
   "Just the Docs on GitHub":
-    - "//github.com/just-the-docs/just-the-docs"
+    - "https://github.com/just-the-docs/just-the-docs"
 
 # Makes Aux links open in a new tab. Default is false
 aux_links_new_tab: false

_layouts/default.html

@@ -12,7 +12,7 @@ layout: table_wrappers
   {% include components/sidebar.html %}
   <div class="main" id="top">
     {% include components/header.html %}
-    <div id="main-content-wrap" class="main-content-wrap">
+    <div class="main-content-wrap">
       {% include components/breadcrumbs.html %}
       <div id="main-content" class="main-content">
         <main>

_layouts/minimal.html

@@ -9,7 +9,7 @@ layout: table_wrappers
 <body>
   <a class="skip-to-main" href="#main-content">Skip to main content</a>
   {% include icons/icons.html %}
-  <div id="main-content-wrap" class="main-content-wrap" id="top">
+  <div class="main-content-wrap" id="top">
     {% include components/breadcrumbs.html %}
     <div id="main-content" class="main-content" role="main">
       {% if site.heading_anchors != false %}

docs/index-test.md

@@ -22,7 +22,7 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 
 There should be whitespace between paragraphs.
 
@@ -55,7 +55,7 @@ GitHubPages::Dependencies.gems.each do |gem, version|
 end
 ```
 
-#### [](#header-4)Header 4 `with code not transformed`
+#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed`
 
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.

docs/search.md

@@ -15,7 +15,7 @@ nav_order: 7
 
 ---
 
-Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
+Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
 All search results are shown in an auto-complete style interface (there is no search results page).
 By default, all generated HTML pages are indexed using the following data points:
 

docs/ui-components/buttons.md

@@ -21,22 +21,22 @@ nav_order: 2
 ### Links that look like buttons
 
 <div class="code-example" markdown="1">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
-[Link button](http://example.com/){: .btn .btn-purple }
-[Link button](http://example.com/){: .btn .btn-blue }
-[Link button](http://example.com/){: .btn .btn-green }
+[Link button](https://just-the-docs.com){: .btn .btn-purple }
+[Link button](https://just-the-docs.com){: .btn .btn-blue }
+[Link button](https://just-the-docs.com){: .btn .btn-green }
 
-[Link button](http://example.com/){: .btn .btn-outline }
+[Link button](https://just-the-docs.com){: .btn .btn-outline }
 ```
 
 ### Button element
@@ -60,20 +60,20 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
 
 <div class="code-example" markdown="1">
 <span class="fs-6">
-[Big ass button](http://example.com/){: .btn }
+[Big ass button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 </div>
 ```markdown
 <span class="fs-8">
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 </span>
 
 <span class="fs-3">
-[Tiny ass button](http://example.com/){: .btn }
+[Tiny ass button](https://just-the-docs.com){: .btn }
 </span>
 ```
 
@@ -82,16 +82,16 @@ Wrap the button in a container that uses the [font-size utility classes]({% link
 Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
 
 <div class="code-example" markdown="1">
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 </div>
 ```markdown
-[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 
-[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
-[Button](http://example.com/){: .btn .btn-blue }
+[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 }
+[Button](https://just-the-docs.com){: .btn .btn-blue }
 ```

docs/ui-components/code.md

@@ -68,22 +68,22 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
 
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 
 </div>
 {% highlight markdown %}
 <div class="code-example" markdown="1">
 
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 
 </div>
 ```markdown
-[Link button](http://example.com/){: .btn }
+[Link button](https://just-the-docs.com){: .btn }
 ```
 {% endhighlight %}
 
@@ -115,7 +115,7 @@ Additional configuration options are loaded through `_includes/mermaid_config.js
 
 This loads the default settings.
 
-The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
+The contents of this object should follow [mermaid's configuration API](https://mermaid.js.org/config/configuration.html). For example, to override the theme, change `_includes/mermaid_config.js` to:
 
 ```js
 // _includes/mermaid_config.js
@@ -185,7 +185,7 @@ graph TD;
 ++++
 {% endhighlight %}
 
-Alternatively, community member [@flyx](https://.github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://.github.com/flyx)!
+Alternatively, community member [@flyx](https://github.com/flyx) has contributed a Ruby extension that does not require extra markup. The extension is available [as a GitHub Gist](https://gist.github.com/flyx/9fff080cf4edc95d495bc661a002232c). Thank you to [@flyx](https://github.com/flyx)!
 
 The [asciidoctor-diagram](https://docs.asciidoctor.org/diagram-extension/latest/) extension which also supports mermaid is not recommended for use with Just the Docs, since it requires separate configuration e.g. for theming, and is known to not be trivial to set up.
 

docs/ui-components/line-nos.md

@@ -115,6 +115,9 @@ end
 {% include fix_linenos.html code=code %}
 {% assign code = nil %}
 
+{: .warning }
+The following generates **incorrect** and **invalid** HTML. It should not be used as a positive example; the improper layout (with the broken HTML tags) is intentional.
+
 ❌ With the compression options used for the theme docs, the following example illustrates
 the **incorrect** formatting arising from the incompatibility of HTML compression
 and the non-conforming HTML produced by Jekyll for line numbers:

docs/ui-components/typography.md

@@ -97,12 +97,12 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
 <div class="code-example" markdown="1">
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 </div>
 ```markdown
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 
-[Link to another page](another-page).
+[Link to another page]({{site.baseurl}}/).
 ```
 
 ---

index.md

@@ -49,7 +49,7 @@ See the theme [README][Just the Docs README] for how to use the theme as a gem w
 
 ## About the project
 
-Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](http://patrickmarsceill.com).
+Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](https://patrickmarsceill.com).
 
 ### License