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.
* Fix the nav html and cache it
- Remove `active` class from nav html
- Add js to insert `active` class on link to selected page
- Include attempt to generate page-specific css for same styling when js is off
* Refactor nav, breadcrumbs, children_nav
Fix#1118
Improve the modularity of building the nav-panel, breadcrumbs, and children-nav
by making them independent. This also significantly simplifies the Liquid code.
* Manual merge of fix-leakage
Also fix order of breadcrumbs
* Fix order of breadcrumbs
* Revert layout in HTML
Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.
* Update breadcrumbs.html
Revert inclusion of single breadcrumb for top-level pages.
* Update breadcrumbs.html
Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.
* Update children_nav.html
Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.
* Delete nav_init.html
* Update sidebar.html
Caches.
* Add a comment
* Update nav.html
- Comment on independence from page.
- Remove redundant comment.
- Remove superfluous conditionals.
* Update just-the-docs.gemspec
Revert jekyll version spec change.
* Update just-the-docs.gemspec
Revert runtime dependency on kramdown-parser-gfm.
* Revert inclusion of activation.scss.liquid
Inclusion makes HTML of all pages differ from 0.5.1
* Update default.html
Restore deleted "<!DOCTYPE html>"
* Update children_nav.html
Restore line break.
* Delete activation.scss.liquid
This was merely an example of page-specific CSS for use when JS off.
* Remove an unused include parameter
`nav.html` does not depend on `include.key`.
* Generate page-specific styling for nav links and lists in the side-nav
In this PR, the code in `includes/nav.html` is fixed, and none of its elements have class `active`. When JS is enabled, `activateNav()` adds the class `active` to all nav-list-items that enclose the nav-list-link to the current page, so the navigation works as usual. Unobtrusive JS requires the same behaviour when JS is disabled.
- Add `_includes/css/activation.scss.liquid` to compute the indices in the enclosing nav-lists of the nav-list-link to the current page, and generate page-specific styling.
- Insert Liquid code in `_includes/head.html` to include the CSS generated by `_includes/css/activation.scss.liquid` (which depends on `site.color_scheme`).
- Update the toggling in `initNav()` to allow also contraction of enclosing levels when JS is enabled.
Caveat: When JS is enabled, buttons can be used to switch the colour scheme dynamically. The page-specific styling of the site-nav is generated statically, and doesn't change, so the background-image of the nav-list-link to the current page is incorrect. (I guess that could be fixed by generating a style element for each available colour scheme, and using JS to reorder the stylesheets in the DOM.)
A further issue is that the `@import` rules used in `_includes/head.html` cause duplication. Replacing them by `@use` rules would avoid duplication, but that is out of scope for this PR.
* Fix activation for collections
- Adjust generated selectors to pages in collections.
- Expand all folded collections when JS is disabled.
This PR should now make unobtrusive use of JS:
- When JS is disabled, the navigation panel shows links to the top pages in all collections (in contrast to the current version of the theme).
- When JS is enabled, folded collections remain folded until their pages are selected.
* Respect `child_nav_order`
- Assumes reverse order when set to any truthy value.
* Suppress liquid line breaks
* Cache the search for favicon.ico
- Move the code for finding the favicon.ico file to `_includes/favicon.html`.
- Replace that code in `_includes.html` by a cached include of `favicon.html`.
* Add "jekyll-include-cache" in fixtures
Needed when CI ignores the gemspec.
* Add gem "jekyll-include-cache" in fixtures
Needed when CI ignores the gemspec.
* Update head.html
- Avoid duplication of color_scheme CSS in `style` element.
- Avoid generation of whitespace by Liquid code.
* Update sorted_pages.html
- Minor optimisation.
- Minor improvements to layout of Liquid code.
* Ensure split is not at start of rules generated by css/activation.scss.liquid
A custom color scheme might not import any highlighting style rules, so we should not assume that there is anything before the first occurrence of `.site-nav`.
* Update head.html
- Add implicit import of light color scheme.
- Revert to previous Liquid code for removing color scheme rules.
* Manual resolution of merge conflicts with v0.5.2
- Copied replacement of links on nav expanders by buttons.
- Removed (page-dependent) conditions associated with `active`.
* Manual resolution of merge conflict with v0.5.2
If previously "" (neither active nor passive), then `active && passive` is true, and the target is now "active".
If previously only "active", then the target is now just "passive".
If previously only "passive", then the target is now just "active".
The state "active passive" is never used.
The value of `active` is true just when the target is left "active".
* Update fixtures/Gemfile-github-pages
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Update head.html
The result of `activation.scss.liquid` is "" for pages with no `title` or with `nav_exclude`. This update stops `head.html` including a `style` element with an invalid body on such pages.
Note that when the result of `scssify` doesn't contain `.site-nav`, `split` produces a one-element array, so `shift` produces an empty array, and `join` then produces an empty string.
* Fix omitted `.site-nav`
Restore the previous prepending of `.site-nav`, which was dropped when suppressing the generation of an incorrect `<style>` element for pages excluded from the navigation.
* Add a footnote about `.site-nav`
* Make setTheme remove background images from nav links
With a fixed nav panel, a <style> in the <head> sets a background image to highlight the nav list link to the current page. The image color depends on site.color_scheme.
Ideally, setTheme(theme) would change the image color to match the theme/scheme. Here, for simplicity, we merely remove the image.
* Explain `nav_fold` in collections.
* Refactor
Attempt at cleaning up the duplicated nav links code and simplifying removal of the background image:
* Add function `navLink()`
* Replace `removeNavBackgroundImages()` by `removeNavBackgroundImage()`
* Replace var `siteNav` by `document.getElementById('site-nav')`
* Replace code in `scrollNav` and `activateNav` by `navLink()`
* Replace a (non-local!) reference to `siteNav` by `document`
* Disable the page-specific stylesheet when JS is enabled
The page-specific `<style>` in the `<head>` is needed only when JS is disabled. Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme).
The page-specific stylesheet is assumed to have index 1 in the list of stylesheets. It would be safer to select it by `id`, but adding an `id` can break existing sites.
* Avoid constraint on use of `.site-nav`, and refactor
Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored.
Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`.
Remove the footnote about `.site-nav` in `docs/customization.md`.
Test the styling with JS disabled, since the resulting style element is disabled by JS.
* Revert "Avoid constraint on use of `.site-nav`, and refactor"
This reverts commit 5284892a7486ef9d2af9929c8a509b89731bb233.
* Avoid constraint on use of `.site-nav`, and refactor
(This corrects a bug in the previous reverted commit for excluded pages such as 404.html.)
Avoid the constraint on use of `.site-nav` by determining how many occurrences are produced by `css/activation.scss.liquid` when custom color schemes are ignored.
Move the Liquid code used for generating the page-dependent style element to a new include `head_nav.html`, to simplify `head.html`.
Remove the footnote about `.site-nav` in `docs/customization.md`.
Test the styling with JS disabled, since the resulting style element is disabled by JS.
* Update comment
* Fix duplicate plugins setting
@mattxwang noticed that the second `plugins` setting was apparently overriding the first, leading to a missing plugin when using `fixtures/Gemfile-github-pages`.
* Avoid double inclusion of activation file
The previous changes to remove the constraint re ".site-nav" duplicated the inclusion of `css/activation.scss.liquid`.
That caused significant extra build time, which the current changes to `head_nav.html` avoid (without affecting the built site).
* Clarify collection configuration docs
* Update and clarify the CHANGELOG
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
Previously, the color scheme information was not passed on to the
browser. This could result in scrollbars being light, when the dark
theme is in use.
Now, `:root { color-scheme: $color-scheme; }` is specified.
This will ensure the color theme is enforced.
Ref: https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme
* Add example of using <details> tag in Markdown kitchen sink
I hoped you would consider adding this example of how to use the <details> tag in the Markdown kitchen sink. I found some useful information in https://github.com/just-the-docs/just-the-docs/issues/246 and, this an example would be handy on this page.
* removed style and called it "collapsed section" instead of dropdown
Also added a link to GitHub's description of how to write a collapsed section.
Closes#1285.
(missed this in code review, which is also my bad! this is because the `:not` selector changes specificity, which in turn changes the cascade)
This is the minimum code change that fixes the issue discussed in #1271 and #1272. In short, Mermaid has its own `.label` that it uses for styling + JS behaviour. To fix this, I add a relatively simple `:not()` that prevents usage with `g`, which is invalid in non-SVG HTML anyways. There should be minimal performance impact.
To test, observe:
- on `main`, selecting the "A" label in https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks has the class `.label`; dev tools will indicate that JtD's `.label` styling is applied
- but, on this branch, dev tools will indicate that the `.label` styling is not applied; observe otherwise that the page behaves the same
Closes#1272.
This PR replaces all uses of `px` in relation to font size (opposed to borders, spacing, etc.) with the equivalent `rem` value when the body font size is `16px`. The intention is to better scale the website when the user changes the font size for `<body>` (often done for accessibility reasons).
This PR is technically a **breaking change**, though it's a minor one (see subheading below). I'm putting this up so that we can discuss it as a community.
(technically closes#1088 and fixes#1073, but let's see if we end up merging this)
## mechanics
To do this, I systematically went through every `px` value for all `.scss` files. Then, I deleted the `rem` function, the `_functions.scss` file (that was the only function there), and removed the import from `support.scss`. A nice side effect of this is that we no longer perform any SASS division.
The only remaining uses of `px` are for either:
- border-related properties
- shadow-related properties
- sizing for "non-text" elements (ex `hr`, `blockquote` decorative spacing)
- `$root-font-size` (see below)
The only pixel value change in this PR is the `padding-left` for `blockquote`, which I've changed from `15px` to `1rem` (which is `16px` in the "stock" theme).
## deprecating `$root-font-size`
There's a SCSS variable called `$root-font-size`. It is used in two places:
1. the `rem()` function
2. the `.site-title` when printing (i.e. a `@print` style)
The changes I listed above let us ignore the first case. The second case seems like it has the intention of matching the body font size, so I replaced it with `1rem`.
We can choose to leave the variable in (in case others use it in custom code - which I'm sure that some do) and leave a deprecation notice, or just remove it now. I'm leaning towards the former, which is less disruptive.
## how users would upgrade
This is a breaking change of *some* sorts, but the change is very straightforward for users:
1. If they do not change `$root-font-size`, they need to do nothing; this PR is a no-op.
2. if they do change `$root-font-size`
- they should instead set the `font-size` of `body` with the appropriate `px` value
- optionally, they can replace all custom code that uses `$root-font-size` with `1rem` (find-and-replace works here)
This follows up from #1259 and closes#1261. Basically, this PR accomplishes the two items discussed in the issue:
1. for all anchors that are *actually* buttons (i.e., have `href="#"`), I've replaced them with a semantic `<button>`
- under the hood, I've made a `.btn-reset` class pulling out the reset from #1259, so there's no visual change
2. for anchors that are ["toggle buttons"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role#toggle_buttons) (the mobile menu nav, sidebar children/grandchildren toggles), I've added an `aria-pressed` property that is updated as the button is clicked
I've also slightly modified some of the `aria-label`s to make them more consistent. Observe that we *shouldn't* update these as the button is clicked; screen readers use the `aria-pressed` property to add an annotation to each button.
To test this,
- the sidebar children and grandchildren can be done on the deploy preview:
- open an arbitrary page; observe that the sidebar children/grandchildren dropdown ticks now have a proper `aria-label` and `aria-pressed`, as well as otherwise work as intended
- toggle one of the buttons; observe the `aria-pressed` role changing as this is done
- open a grandchild page; observe that the `aria-pressed` has a correct default wrt whether or not the page is active
- the mobile menu can be done on the deploy preview; on a smaller viewport, observe the correct `aria-pressed`
- two features require local changes to test:
- the `site.search.button` needs to be enabled in the `_config.yml`. To test this, locally clone the repo, change the flag, and observe that the button still works as intended + has no visual regressions.
- the collections feature is a bit more complicated. To test this, locally clone the repo, add an arbitrary collection and changes to `_config.yml`, and observe the same behaviour for the sidebar children/grandchildren above
This PR fixes several Axe errors I found while working on https://viewcomponent.org/. I did not see any visual regressions on my deploy, but I'd encourage testing with other sites.
---------
Co-authored-by: Lindsey Wild <35239154+lindseywild@users.noreply.github.com>
* Refactor nav, breadcrumbs, children_nav
Fix#1118
Improve the modularity of building the nav-panel, breadcrumbs, and children-nav
by making them independent. This also significantly simplifies the Liquid code.
* Fix order of breadcrumbs
* Update breadcrumbs.html
Revert inclusion of single breadcrumb for top-level pages.
* Update breadcrumbs.html
* Update children_nav.html
Revert to the previous layout in the HTML, to allow the use of `diff` to check the built site.
* Update minimal.html
Remove the previously required workaround involving `nav.html`.
* Add docs pages about layouts
The aim of the initial version of these docs pages is to illustrate the difference between the default and minimal layouts.
* Update CHANGELOG.md
Realized that the new syntax is only supported on [Safari 16.4](https://caniuse.com/css-media-range-syntax), which is gated by OS updates. Going to revert this change for the foreseeable future.
Closes#1239.
