Fix#1587
As reported in issue #1587, the auto-generated child navigation (TOC) has a bug: it can be incorrectly omitted. This happens when the first page built is a parent page. The omission is caused by a side-effect of including the cached site-nav HTML: the code that generates the site-nav is executed the first time the cached HTML is included, and assignments in the executed code may overwrite the values of variables.
@kevinlin1 suggested a simple and safe way to fix this bug: move the inclusion of the site-nav in `components/children_nav.html` so that it is executed before all local assignments. This PR implements that suggestion, and applies the same fix to two other files.
### Testing
A test for this bug has been added to the [_Just the Docs Tests_ repo](https://github.com/just-the-docs/just-the-docs-tests). The first page rendered when building the website is `About this site` in the TESTS collection, and it is now the `parent` of the page [`Test TOC`](https://just-the-docs.github.io/just-the-docs-tests/tests/about/test-toc/), which should be listed in its auto-generated child navigation. (The test page uses `nav_exclude: true` to avoid the link to it appearing in the main navigation, but that doesn't affect the test of this PR.)
The following steps check that the bug appears when building _Just the Docs Tests_ with v0.10.0 of the theme:
1. Clone the [Just the Docs Tests repo](https://github.com/just-the-docs/just-the-docs-tests).
2. Build and serve the website locally using:
```sh
JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle install
JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle exec jekyll serve
```
3. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
4. Check that no auto-generated child navigation appears on the latter page.
The following steps check that the bug does not appear when building _Just the Docs Tests_ with this PR branch:
5. Build and serve the website locally using:
```sh
JTD_ORG=pdmosses JTD_REF=fix-toc bundle install
JTD_ORG=pdmosses JTD_REF=fix-toc bundle exec jekyll serve
```
6. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
7. Check that an auto-generated child navigation with a link to the `Test TOC` page appears on the latter page.
(It seems unnecessary to check that the reported bug does not appear on other pages, since subsequent includes of the cached site-nav cannot assign to any variables.)
This is the minimum necessary change to make `back_to_top` work when there is no custom footer, last edit timestamp, or GitHub edit link.
Two immediate thoughts. First, we have a pair of variables: `back_to_top` and `back_to_top_text`. In my opinion, this seems a bit unnecessary; we could just use a `back_to_top`, and treat any non-`nil`/`false` value as the text. We could make this backwards compatible (i.e. support but deprecate `back_to_top_text`). Any thoughts here?
Secondly, some of these conditions are weak:
a251382b7a/_includes/components/footer.html (L7-L9)
Here, this conditional *should* also check for `back_to_top_text`, and presumably, this should "bubble up" to the overall `if` statement on line 4 (similar things for the `gh_*` variables - the line 4 condition only checks for `gh_edit_link`). Is this a reasonable concern/take? If so, I can approach this some time (either in this PR, in another PR, etc.).
---
After we decide the correct behaviour of `back_to_top`, I'll add documentation to the "Configuration" section!
Separately, @pdmosses mentioned:
> The obvious fix is to always render the footer when `site.back_to_top` is set. However, it would improve the usability of the back-to-top feature if individual pages could override the site setting (to suppress the link on some short pages, or to show it on some long pages).
Happy to do that too - for organizational purposes, I'll punt that to another PR (that I can merge into the same release).
---
Fixes#1443.
This PR fixes some accessibility issues in our theme docs (i.e. not generated code) flagged by #1513. Here, I target changes that I say are not "systemic", i.e. issues that are easily resolvable by changing our copy and page structure (rather than issues that are created by how kramdown/rouge generates HTML, or reworking our color themes).
Here's a quick summary of the manual changes I made:
- ~~writing some JS to set `tabindex="0"` on all code blocks; I'd prefer a ruby-native solution, but that involves writing Ruby code, which is incompatible with the pages gem~~ I've moved this to #1533
- rewriting many headings named "Example" which were almost always h4s into more descriptive headings + the appropriate heading level, adding .text-delta to maintain the previous style when necessary
- removing some old heading ID hacks in `index-test` that are no longer necessary, since Jekyll does this automatically now
- fixing the table headings in `docs/utilities/layout.md`
- adding accessible titles + descriptions to the mermaid examples
- occasionally, slightly moving around copy to make it align with new headings
If you test with #1513 with the following rules disabled:
```rb
skipped_rules = [
'color-contrast', # requires theme auditing
# issues w/ autogenerated footnotes
'aria-allowed-role',
'landmark-no-duplicate-contentinfo',
'landmark-unique',
'aria-deprecated-role',
# issues w/ markdown checkboxes
'label'
]
```
You should get passing tests :) which is awesome!
## next steps
1. we need to do a pass over our docs copy - very inconsistent. This has been a pain point for me for a while now, just need to find time to sit down and do it. In particular, I'd love to standardize how we display example code (perhaps even hiding it with `<details>` and `<summary>`?), our headings language, what goes into the ToC, our overall writing style, etc.
2. ~~I don't love the JS hack for adding `tabindex="0"` to code blocks (so that they are keyboard-focusable). Ideally, we'd add a custom formatter to rouge to do this, but we can't execute arbitrary Ruby code when users use `github-pages`. I'll look into this some more - maybe rouge would be open to adding this as a feature.~~ see: #1533
4. There are some systemic issues that need a deeper look:
1. The most common issue is still color-contrast. Fixing this involves:
- looking at our whites/blacks/grays for core text and highlighting
- reevaluating our syntax highlighting themes
- fixing dark mode, once and for all :)
- also, picking accessible callout colours!
2. kramdown's autogenerated footnotes feature creates a bunch of errors that aXe flags: it seems like a deprecated aria role is being used, and perhaps some misuse of markup. Need to look into this more before I can make a solid attempt at resolving this issue.
3. We demonstrate the use of `- [ ]`, but this generates `<input type="checkbox">` values with no label. I'm not entirely sure what the best way to fix this problem is (without writing custom Ruby code). I'll have to think about this some more.
---------
Co-authored-by: Michael Ball <michael@mball.co>
Splitting this out of #1513 to make my life reviewing a bit easier! Note that this does *not* affect our downstream users, just the docs site for this project itself.
---------
Co-authored-by: Michael Ball <michael@mball.co>
* Remove `jekyll-default-layout` plugin
* Move docs/navigation-structure to docs/navigation
* Fix uses of line-nos in md files
* Update CHANGELOG.md
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
* Allow unlimited multi-level navigation
This PR supersedes #462.
The only user-level difference from #462 is that disambiguation of parent pages has to use either `grand_parent` or `ancestor` titles: the somewhat unnatural `section_id` and `in_section` fields are not supported.
The implementation has been significantly simplified by the changes introduced in v0.7.0 of the theme.
* Detect cyclic parenthood
A page should not have a parent or ancestor with the same title. If it does, the location of the repeated link is marked by ∞, to facilitate debugging the navigation (and an unbounded loop leading to a build exception is avoided).
* Add nav_error_report warning in main navigation
When activated by `nav_error_report: true` in `_config.yml`, displays warnings about pages with the same title as their parent page or an ancestral page.
* Cache site-nav with links to all pages
The extra cached site-nav is used for determining breadcrumbs and children navigation, which may involve pages that are excluded from the main navigation.
* Replace code for determining children by inclusion of components/nav/children.html
* Update CHANGELOG.md
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
Changes are in three categories:
- whitespace
- devendoring prefixes for properties that have entered the CSS spec - reasonable to autofix
- removing a duplicate `monospace` in `monospace, monospace` `font-family` decl in normalize.scss - not autofix
* Add nav_enabled variables for site/layout/page-level control
* _sass: Add a space around `+` operator
* assets: Do not compile based on site.nav_enabled
* _config.yml: nav_enabled can be selectively enabled
* CHANGELOG.md: Add nav_enabled feature and docs
* docs: Prefer em dash in describing minimal layout
* docs: Add section on Selectively hiding or showing the sidebar
* _layouts: Display sidebar based on variable importance
* docs: Update documentation on the minimal layout
* docs: Document site.nav_enabled configuration variable
---------
Co-authored-by: Matt Wang <matt@matthewwang.me>
Fix#1445
Front matter defaults with unrestricted `scope` (`path: ""`) can affect theme code files. [Jekyll](https://jekyllrb.com/docs/front-matter/#predefined-global-variables) supports using `null` to "produce a file without using a layout file".
This PR adds `layout: null` to `just-the-docs.js`, to avoid this file being affected by the following front matter defaults:
```yaml
defaults:
-
scope:
path: ""
values:
layout: "default"
```
We are running into an issue upgrading from 0.7 to 0.8, suggesting that `trim` is not a method.
```
1.963 Liquid Exception: Liquid error (/usr/gem/gems/just-the-docs-0.8.0/_includes/components/breadcrumbs.html line 59): undefined filter trim included in /_layouts/default.html
1.968 /usr/gem/gems/liquid-4.0.4/lib/liquid/strainer.rb:58:in `invoke': Liquid error (/usr/gem/gems/just-the-docs-0.8.0/_includes/components/breadcrumbs.html line 59): undefined filter trim included (Liquid::UndefinedFilter)
```
Looking at the liquid docs, we're probably looking for `strip` and not `trim`
https://shopify.github.io/liquid/filters/strip/https://github.com/Shopify/liquid/blob/main/History.md#300--2014-11-12, I don't see a trim so it may have been an extension? This does work normally on just-the-docs itself running from scratch, so it might also be a bug in our application (or combination of different versions in plugins).
Adds a keyboard shortcut to use Ctrl/Cmd and a configurable key to focus the search input. The key is configurable with `search.focus_shortcut_key`; enables it on the core docs site with `'k'` (default on many sites).
---------
Co-authored-by: Matt Wang <mxw@cs.washington.edu>
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.
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
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>
* 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>
