Closes#1392.
Unfortunately, this PR has not actually diagnosed the root problem with the `scrollBy` calculation/method and Safari. However, by using the [`scrollIntoView`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) function (which essentially does what the calculation was meant to do), this problem is "magically" solved! As a side effect, I think this makes the code easier to maintain (I myself was thinking: why is there a magic `3` multiplier?).
~~I will point out that this does change *how much is scrolled*; following the spec for the method, the sidebar is now scrolled so that the active navigation link is top-aligned with the scroll container (which in this case, is the navigation sidebar's "cutoff"). I personally am fine with this change, but happy to fiddle around (e.g. we could vertically align to the `center` via [`scrollIntoViewOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#parameters), though I'm not sure if this causes compatability problems).~~
I will point out that this does change *how much is scrolled*; we are now using the `center` option to `scrollBy`, which centers the target link. As Peter has commented in the PR thread, this seems to be the best compromise for maintaining the spirit of the previous calculation.
### testing
Peter did a great job writing a reproducible bug report in #1392. To test this,
1. first, follow the instructions verbatim on `main`. observe that the bug appears on Safari on macOS, but not Firefox and Chrome
2. then, apply this change (e.g. check out the branch)
3. next, replay the instructions - observing that
1. the bug is fixed on Safari
2. there is no change to the behaviour on Firefox and Chrome (other than the "start" of the scroll")
### compatability
On [Can I use](https://caniuse.com/scrollintoview), `scrollIntoView` has 98.15% adoption (the only "major" holdout being Opera Mini); and, the partial support from IE is about an option that we don't use. So, I'm pretty confident that we should be able to roll out this change without our users being locked out by a new-ish method.
Added link and short blurb about document collections to the navigation structure page, for quicker reference and suggestion during reading documentation.
Allows easier reference when trying to create page groups / categories without using a blank Parent page. Avoids automatically folded Parent page when Child pages are the necessary ones.
Rectify and simplify CSS rules used in the head element. The rules now avoid the invalid use of nested `:not()` pseudo-classes.
- Update CHANGELOG.md
- Remove ignore statements re CSS parse errors
- Add rules for excluded pages and simplify
- Add `activation_no_nav_link` with the rules for excluded pages
- Insert `activation_no_nav_link` when no other rules are generated
- Replace `:nth-child(1)` by `:first-child`
- Correct `:nth-child(n + {{ activation_index | plus: 1 }})` to `:not(:first-child)`
- Eliminate `activation_collection_index`
- Generate `.nav-category-list` selectors only for sites with collections
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR fixed the typos in CHANGELOG and MIGRATION files
```pseudo
Simlar > Similar
avaialble > available
vulnerablities > vulnerabilities
concering > concerning
```
* Defer removal of href
The `href` with the URL of the current page is inspected by `navLink()`, so it should not be removed until after the calls of `navLink()` in `scrollNav()` and `activateNav()`.
As `scrollNav()` follows `activateNav()`, the removal of `href` needs to be left to `scrollNav()`.
* Update CHANGELOG.md
This PR touches the "Navigation Structure" docs page, by:
- fixing the header hierarchy; we no longer jump from `h2` -> `h4`
- this does technically result in a styling change, which I'm personally fine with. However, if we want to keep the old one, I can also do that!
- makes each header text unique, by annotating the "Example" with what the example is for
- adding a "New" label for the feature introduced in #1360
The main goal of this PR is to improve the accessibility of this docs page: the current generated markup will cause minor problems for screenreader users. If we like this change, I can then roll this out to the rest of the docs pages.
I've whipped up a solution that solves #1103. I've added a config option `nav_external_links_new_tab`, which is off by default. When turned on, it'll pop external nav links into a new tab. The idea was borrowed from how [aux_nav.html](https://github.com/just-the-docs/just-the-docs/blob/main/_includes/components/aux_nav.html) does it with `aux_links_new_tab`.
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Remove "passive" toggle
PR #1244 introduced the "passive" toggle, but just-the-docs.js subsequently disabled the only styling that used it, so it became redundant.
This removes it.
* Reduce build time for page-dependent CSS
Fix#1323
- Remove `_includes/head_nav.html`.
- Generate page-independent SCSS in `assets/css/just-the-docs-head-nav.css`.
- Link to `/assets/css/just-the-docs-head-nav.css` in `head.html`.
- Disable the above stylesheet in `assets/js/just-the-docs.js`.
- Generate page-dependent CSS in `_includes/css/activation.scss.liquid` and include in `head.html`.
* No override svg rotate
* Disable both stylesheets safely
* Move the site nav to a new include
- Fix the complete site nav
- Move the site nav to `_includes/site_nav.html`
- Cache the site nav
- Uncache `nav.html`
* Move nav and site_nav to _includes/components
* Replace id prefix
* Update breadcrumbs.html
Replace several filters by a single loop through all the pages,
but breaking as soon as possible.
Profiling indicates that this saves up to 50% of the breadcrumbs build time for the filters.
* Update just-the-docs-head-nav.css
Adjust the number of lines to keep
* Update head.html
Remove superflous type.
* Update activation.scss.liquid
Remove a superfluous closing brace.
Adjust layout.
* Use `scssify` to remove nesting
Preliminary profiling indicates that using `scssify` on the small number of nested CSS rules produced by `activation.scss.liquid` is quick enough.
* Update head.scss
Manual attempt at prettier (pending installation in Atom).
* Avoid generation of nested CSS
Local profiling indicated that using `scssify` on each page takes about 1% of the build time.
- Update `_includes/css/activation.scss.liquid` to generate non-nested CSS.
- Remove use of `scssify` from `_includes/head.html`.
* Ignore false positives from validator
Ignores: `:1.810-1.823: error: CSS: Parse Error.` and `:1.811-1.824: error: CSS: Parse Error.`; had to shift things around since the local config overrides the CI flag.
* Inline `_sass/head.css`
* Update CHANGELOG.md
---------
Co-authored-by: Matthew Wang <matt@matthewwang.me>
* Remove href from link to active page
* Update CHANGELOG.md
Co-authored-by: Matt Wang <matt@matthewwang.me>
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Remove "passive" toggle
PR #1244 introduced the "passive" toggle, but just-the-docs.js subsequently disabled the only styling that used it, so it became redundant.
This removes it.
* Update CHANGELOG.md
* Update CHANGELOG.md
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Update CHANGELOG.md
Co-authored-by: Matt Wang <matt@matthewwang.me>
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR moves over the changes from https://github.com/just-the-docs/just-the-docs/pull/1112, namely making the `.gitignore` more descriptive and bringing it to parity with the recommendations from Jekyll.
---------
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Fix#1331
Pages excluded from the navigation do not have a second (page-specific) stylesheet in the head. When JS is enabled, an error arises when such a page is loaded, due to `initNav()` trying to disable a non-existent stylesheet.
This PR stops JS trying to disable the second stylesheet when it doesn't exist.
Note that issue #1331 was reported in connection with optimising the build of the endoflife.date site by following [my suggestion](https://github.com/just-the-docs/just-the-docs/pull/1244#issuecomment-1660246728) in #1244, but the bug also appears on the theme website at https://just-the-docs.com/404.html.
Ruby 3.2 has stabilized (and the bug with Liquid has been patched). I think this is a good time for us to bump all of our versions, especially with the discussion in #1307.
Separately, I've:
- changed the core test matrix to be across `3.0`, `3.1`, and `3.2`. Ruby 2 has been EOL for ~ 4 months, while 3.0 is around for about 7 more months.
- standardized the formatting of our CI ruby versions to be strings; this is because the number `3.0` gets YAML-casted to `3`
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.
