From d7e4a808b5dc0171107e83458cd9627158312fdd Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Sat, 19 Aug 2023 21:17:26 -0400 Subject: [PATCH] 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 `
` 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 `
` 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](https://github.com/just-the-docs/just-the-docs/pull/1305/commits/4128b23ef2e6568fab8df353f820a62ec721a146) and [3527220](https://github.com/just-the-docs/just-the-docs/pull/1305/commits/35272203ba2f485e0d56d2cc78cebe0a31d6f359). ## 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 | 34 ++++++++++++++++++++++++ Gemfile | 2 ++ _config.yml | 2 +- _layouts/default.html | 2 +- _layouts/minimal.html | 2 +- docs/index-test.md | 4 +-- docs/search.md | 2 +- docs/ui-components/buttons.md | 44 ++++++++++++++++---------------- docs/ui-components/code.md | 12 ++++----- docs/ui-components/line-nos.md | 3 +++ docs/ui-components/typography.md | 4 +-- index.md | 2 +- 12 files changed, 76 insertions(+), 37 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cef61b5..b0205db 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/Gemfile b/Gemfile index 15334e3..67dcc53 100644 --- a/Gemfile +++ b/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 diff --git a/_config.yml b/_config.yml index 09790ea..4ee6056 100644 --- a/_config.yml +++ b/_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 diff --git a/_layouts/default.html b/_layouts/default.html index 59919dd..923c1c1 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -12,7 +12,7 @@ layout: table_wrappers {% include components/sidebar.html %}
{% include components/header.html %} -
+
{% include components/breadcrumbs.html %}
diff --git a/_layouts/minimal.html b/_layouts/minimal.html index 854dbd0..b12c5db 100644 --- a/_layouts/minimal.html +++ b/_layouts/minimal.html @@ -9,7 +9,7 @@ layout: table_wrappers Skip to main content {% include icons/icons.html %} -
+
{% include components/breadcrumbs.html %}
{% if site.heading_anchors != false %} diff --git a/docs/index-test.md b/docs/index-test.md index 83fbe67..522a118 100644 --- a/docs/index-test.md +++ b/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. diff --git a/docs/search.md b/docs/search.md index 78175f3..09a1ec5 100644 --- a/docs/search.md +++ b/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: diff --git a/docs/ui-components/buttons.md b/docs/ui-components/buttons.md index d3d4ccd..61fb1a2 100644 --- a/docs/ui-components/buttons.md +++ b/docs/ui-components/buttons.md @@ -21,22 +21,22 @@ nav_order: 2 ### Links that look like buttons
-[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 }
```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
-[Big ass button](http://example.com/){: .btn } +[Big ass button](https://just-the-docs.com){: .btn } -[Tiny ass button](http://example.com/){: .btn } +[Tiny ass button](https://just-the-docs.com){: .btn }
```markdown -[Link button](http://example.com/){: .btn } +[Link button](https://just-the-docs.com){: .btn } -[Tiny ass button](http://example.com/){: .btn } +[Tiny ass button](https://just-the-docs.com){: .btn } ``` @@ -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.
-[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 }
```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 } ``` diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md index bbe1899..b7b99ad 100644 --- a/docs/ui-components/code.md +++ b/docs/ui-components/code.md @@ -68,22 +68,22 @@ To demonstrate front end code, sometimes it's useful to show a rendered example
-[Link button](http://example.com/){: .btn } +[Link button](https://just-the-docs.com){: .btn }
```markdown -[Link button](http://example.com/){: .btn } +[Link button](https://just-the-docs.com){: .btn } ```
{% highlight markdown %}
-[Link button](http://example.com/){: .btn } +[Link button](https://just-the-docs.com){: .btn }
```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. diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md index 62870c1..b946eac 100644 --- a/docs/ui-components/line-nos.md +++ b/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: diff --git a/docs/ui-components/typography.md b/docs/ui-components/typography.md index 2aa4018..230bf58 100644 --- a/docs/ui-components/typography.md +++ b/docs/ui-components/typography.md @@ -97,12 +97,12 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
Text can be **bold**, _italic_, or ~~strikethrough~~. -[Link to another page](another-page). +[Link to another page]({{site.baseurl}}/).
```markdown Text can be **bold**, _italic_, or ~~strikethrough~~. -[Link to another page](another-page). +[Link to another page]({{site.baseurl}}/). ``` --- diff --git a/index.md b/index.md index e77551e..98c62f1 100644 --- a/index.md +++ b/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