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>
* 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>
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>
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>
This PR does two things:
1. fixes using mermaid version `>= 10` from the CDN, by importing the ESM module instead
2. moves script loading code from `head.html` to the mermaid include
I've also added some light documentation to clarify how using mermaid with local paths should work (users should specify a version, and they should only use fully-minified bundles with no local references).
The nice thing about this approach is that it's a breaking change for nobody, and only adds functionality (v10 support). Eventually, we should remove support for mermaid <10, which should make this much easier!
Closes#1206.
## Context
In v10, Mermaid has implemented a few (admittedly, very frustrating to deal with) breaking changes:
1. they've removed CJS support, which is fine, *but*
2. that means that the `dist` they publish to JSDelivr now has a **different URL**: for versions `10.0.0` - `10.0.2`, **they do not have a minified bundle -- you have to load the ESM version with relative imports**
3. and, separately the `init` function has been deprecated
2 is really the issue, and so I've had to go into the code to now load mermaid by ESM by default when the user is on mermaid > v10.
I've tested this with:
- CDN version < 10 (v9)
- CDN version 10
- local path with version < 10 (v9)
- local path with version 10 (new: also loaded as an ESM module)
Separately, I chose to put all the mermaid stuff in one include because:
- I think @pdmosses requested something like this - it's a bit confusing that some mermaid code is *not* in the include, and this makes modular components ... more modular
- from a developer perspective, it's more clear what's happening with mermaid
- mermaid is not render-blocking, so it shouldn't be in the `head` anyways
---------
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
In my other cleaning, I also noticed:
- the contributors pane on the homepage is broken
- the following link to a repo page in the search docs is broken
<img width="762" alt="Screenshot 2023-01-03 at 6 41 49 PM" src="https://user-images.githubusercontent.com/14893287/210474679-bcb9af23-0a4e-4999-a0ec-f06d967ea726.png">
In particular, the generated HTML is
```html
<a href="/blob/main/assets/js/zzzz-search-data.json">this content</a>
```
Looking at the source code for both features
```html
<ul class="list-style-none">
{% for contributor in site.github.contributors %}
<li class="d-inline-block mr-1">
<a href="{{ contributor.html_url }}"><img src="{{ contributor.avatar_url }}" width="32" height="32" alt="{{ contributor.login }}"></a>
</li>
{% endfor %}
</ul>
```
```md
[this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).
```
It's clear that `site.github` is not being populated. This is controlled by the GitHub Metadata/[`jekyll-github-metadata`](http://jekyll.github.io/github-metadata/) plugin.
I'm not when this stopped working. If I had to guess, I think this is packaged as part of the `github-pages` gem; so, when the site moved off of it a while back, we never noticed this regression. This is the type of thing that can hopefully be caught by regression tests in the future.
This PR re-adds the plugin. I've opted to only add it to the `Gemfile` but not the `gemspec` so that it only affects our site. In other words, JtD does not have `jekyll-github-metadata` as a runtime dependency (since none of our theme code relies on it). Happy to change that if we'd like.
---
In the future,
- short-term: I can write a filter that removes dependabot from our contributors
- longer-term: we could rewrite the "last edited on GitHub" feature to instead use `jekyll-github-metadata`. this would necessitate us to make it a runtime dependency, and it also wouldn't work as well for users of GitLab or other alternatives.
This is a small PR that:
- adds a `fixtures/Gemfile-github-pages`, the minimum gemfile necessary to build the site
- adds a new Actions workflow to build the site with that gemfile
In the future, this should prevent issues like #1074, where we push a change that passes the `jekyll` CI but fails to build on `github-pages` (and its dependencies - which in this case, was an older version of ruby sass).
(to be honest - not super happy with the code duplication, but I also think we'll have different build matrices for the different versions, so I'm fine with this for now)
Part of (but does not close) #1145.
Hi there!
Thank you for the great theme! I am a happy user and was delighted to see that mermaid support has landed.
In some cases the usage of jsDelivr might not be possible for technical or compliance reasons.
This commit adds a second way to include the mermaid lib by specifying a path in the mermaid config. This way a local version of the lib can be used.
It should be fully backwards compatible, not requiring any action by users that already include the lib from the CDN.
I already added some documentation, but I am also happy to extend this, if this change is generally well-received.
Cheers,
Christian
This is a follow-up from a private maintainer discussion (https://github.com/orgs/just-the-docs/teams/maintainers/discussions/11?from_comment=12). The cliff's notes for the public are: we believe we are not currently GDPR-compliant in how the docs site itself serves analytics.
For now, we'll disable analytics; we don't use them anyways. We will then:
- add analytics and the relevant banner to the regression test repository
- in the future, workshop a built-in solution for JtD users to be GDPR compliant
- optionally, clarify the role of users of this theme (their responsibility is to make their sites GDPR compliant)(
* Issue #1023 - note that GA4 properties are supported
* Issue #1023 - parameterize Google Analytics property script
* Issue #1023 - support a list of multiple Google Analytics tracking IDs in config
* Issue #1023 - update Google Analytics configuration doc
* Fix configuration of multiple Google Analytics properties and simplify type checking
* simplify unnecessary code repetition
* tweak Google Analytics config documentation wording
Fix#973
Update the array of excluded directories and files to be:
- those that Jekyll excludes by default (since our `exclude` replaces Jekyll's defaults in Jekyll 3) and
- the others that the theme previously excluded, but omitting `vendor` – also ones that are no longer in the repo.
Excluding `vendor` was preventing HTML compression of the theme docs, since the layout used for compression is in `_layouts/vendor/compress.html`.
The change from one-line to multi-line YAML layout for the array of excluded files enhances readability. The addition of explanatory comments supports maintenance.
To test the effect of this PR on the theme docs:
- Build and serve the theme docs.
- Check that the HTML files are now compressed.
- Check that the last example of code with line numbers has incorrect formatting.
(This PR cannot affect sites that use the theme as a gem or as a remote theme, since we don't include our `_config.yml`.)
This PR updates the home page and the CHANGELOG to refer to v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.
It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.
As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)
This PR has a bit of scope creep! This PR now:
- changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857
- changes the behaviour of mermaid configuration
- instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js`
- the include is loaded directly into the contents of `mermaid_initialize`
- by default, it is an empty object (i.e. `{}`), triggering the defaults
- updates docs
- adds an example to the markdown kitchen sink
It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward!
As is, this is invalid and will not cause the TOC to be rendered. The collapsing example is fine.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
This PR combines (and resolves conflicts between) #448, #463, #466, #494, #495, #496, #498, and #572.
The main aim is to facilitate use of several of the implemented features _together_, when using the fork as a remote theme. It should also simplify merging the included PRs into a future release.
The branch [combination-rec-nav](https://github.com/pdmosses/just-the-docs/tree/combination-rec-nav) adds [multi-level navigation](https://github.com/pmarsceill/just-the-docs/pull/462) and (NEW:) [sibling links](https://github.com/pmarsceill/just-the-docs/pull/394) to the branch used for this PR. It includes updated [documentation for the navigation structure](https://pdmosses.github.io/just-the-docs/docs/navigation-structure/), and reorganised and extended [navigation tests](https://pdmosses.github.io/just-the-docs/tests/navigation/). The documentation and the tests can be browsed at the (temporary) [website published from the combination-rec-nav branch](https://pdmosses.github.io/just-the-docs/).
_Caveat:_ The changes to v0.3.3 in this PR and #462 have not yet been reviewed or approved, and may need updating before merging into a release of the theme. If you use a branch from a PR as a remote theme, there is a risk of such updates affecting your website. Moreover, these branches are likely to be deleted after they have been merged. To avoid such problems, you could copy the branch that you want to use to your own fork of the theme.
Co-authored-by: Matt Wang <matt@matthewwang.me>
The values of `title` and `nav_order` can be numbers or strings.
Jekyll gives build failures when sorting on mixtures of different types,
so numbers and strings need to be sorted separately.
Here, numbers are sorted by their values, and come before all strings.
An omitted `nav_order` value is equivalent to the page's `title` value
(except that a numerical `title` value is treated as a string).
The case-sensitivity of string sorting is determined by `site.nav_sort`.
Pages with `nav_exclude: true` were included when sorting on `title` or `nav_order`. That could cause build failures when the type of value of the field differs from that on other pages, as reported in https://github.com/pmarsceill/just-the-docs/issues/406.
Pages with `nav_exclude: true` or no `title` are never displayed in the navigation, so removing them from `pages_list` cannot break existing sites. This change also allows the removal of some tests in the code. (The indentation of the code should now be adjusted, but that has been deferred, to restrict the size of the diff for review.)
For testing, the title of `404.html` has been changed to the number `404`, the page `docs/untitled-test.md` has been added, and `nav_sort_order` has been set to `case_sensitive`. Those updates give build failures with the current version of `_includes/nav.html`, but not after the suggested changes.
It will still be possible for build failures to occur due to sorting fields of *non-excluded* pages with differing types of values (e.g., `nav_order`a mixture of numbers and strings). To make the code completely safe will require relatively complicated changes,.
The additions to `_config.yml` go together with the changes to `code.scss`,
to facilitate adjusttments by users. See `docs/linenos-test` for the details.
The CSS code has been significantly refactored and simplified,
and seems to produce sensible results (at least on Safari and Firefox).
