mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-15 23:52:23 -06:00
11 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Matt Wang
|
66b84a03e7
|
Fixes erroneous parentheses in site_nav conditional (#1366)
Ref: https://github.com/just-the-docs/just-the-docs/pull/1360#issuecomment-1751358990. I'm sorry for not catching this earlier; I'm surprised that this slipped my mind (maybe I'm juggling too many templating languages). Though, also, I'm surprised that this doesn't flag as a compiler error? |
||
CarbonNeuron
|
33ba8d8eaa
|
Add configuration options for opening external links in new tab (#1360)
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> |
||
Peter Mosses
|
2ccc451c2a
|
Fix: improve build time (#1358)
* 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> |
||
|
Peter Mosses
|
9d0ce1c22a
|
Fix the navigation panel (#1244)
* 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> |
||
|
Matt Wang
|
525742ee05
|
Fix missing closing </button> tag in sidebar.html (#1304)
Ref: https://github.com/just-the-docs/just-the-docs/pull/1259#issuecomment-1655899503. |
||
|
Matt Wang
|
0ca69334b0
|
Fix ARIA labels for all anchors with href="#"; adds aria-pressed information for toggles (#1262)
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 |
||
Joel Hawksley
|
cffe2f1b29
|
Add ARIA roles and labels to search, header, logo, mobile menu button, and main content (#1259)
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> |
||
|
Peter Mosses
|
8e38759613
|
Fix liquid variable leakage in navigation components (#1243)
* 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 |
||
|
Matt Wang
|
5e5e2438d2
|
Fix mermaid v10, bundle all mermaid code in component (#1190)
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> |
||
Eric Knibbe
|
49d004f271
|
Fixes minor spacing and comment nits (#1128)
This PR simply fixes a few spacing and comment nits I found. |
||
|
Matt Wang
|
2495d3e6bb
|
refactor: modularize site components (#1058)
Hi everyone, this is a large refactoring PR that looks to **modularize site components** following the discussion in #959. At the top-level, it: - moves icons, the sidebar, header (navbar, search, aux links), footer, and mermaid components of the `default` layout into their own `_includes` - creates a new `minimal` layout that does not render the header or sidebar as a proof-of-concept for the composability of components - documents all existing and new layouts (including vendor code) in the "Customization" section An important goal of this PR is for it to be **just code motion and flexibility**: there should be **zero impact** on the average end user that only consumes the `default` theme. The next few sections go in-depth on each of the listed changes. ### new components The `default` layout contains a "list" of all relevant components. Importantly, some of these components have sub-components: - the header is split into the search bar, custom code, and aux links - the icons include imports different icon components, some of which are conditionally imported by feature guards There are also candidates for future splits and joins: - the sidebar could be split into navigation, collections, external link, and header/footer code - the "search footer" could be joined with other search code, which would make it easier to "include search" in one go; *however, this is a markup change* - @kevinlin1 has pointed out that there is some leakage between the sidebar (which computes parents/grandparents) and the breadcrumbs (which needs them to render). He's graciously added a bandaid fix to `minimal` (which does not render the sidebar). However, in the long term, we should either: - calculate this in a parent and pass the information to both components - change how this works entirely (which may happen with multi-level navigation) @pdmosses has done a great job outlining this and more in his [Modular Layouts test site](https://pdmosses.github.io/modular-layouts/docs/main/). ### minimal layout Based on @kevinlin1's use-case in just-the-class (see: his [Winter 2023 CSE 373 site](https://courses.cs.washington.edu/courses/cse373/23wi/)), we've created a first-class `minimal` layout that does not render the sidebar or header. In a [comment](https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057015039), Kevin has indicated that we can re-add the search bar in the minimal layout; however, it seems like this would be a code change. I think we should punt this to a future issue/PR. @pdmosses has also discussed the confusion of `minimal` as a layout and its meaning in inheritance. I've added a note in documentation to clarify the (lack of) inheritance relationship. ### documentation I've written documentation in the "Customization" page / [Custom layouts and includes](https://deploy-preview-1058--just-the-docs.netlify.app/docs/customization/#custom-layouts-and-includes) section explaining: - generally, that we use includes/layouts (and pointing to docs) - the `default` layout and its constituent components (with a warning about name collisions) - creating alternative layouts with `minimal` as an example - the inheritance chain of layouts and the vendor layouts that we consume I've also created (and linked to) a [minimal layout test](https://deploy-preview-1058--just-the-docs.netlify.app/docs/minimal-test/) that is currently a copy of the markdown kitchen sink but with the minimal layout. I think there's room to improve this in the future. ### future work I think there's a lot we can do. Let me break this into various sections. Potential follow-ups before `v0.4.0`: - re-including search in `minimal` (anticipating a minor code change) - fixing the leakage of parent/grandparent information between the sidebar and breadcrumbs (anticipating no end-user code change, but good to evaluate separately and discuss) - heavily document this in the migration guide (#1059) and in our RC4 release docs - improve semantic markup for components (ex `main`, `nav`) Related work in later minor versions: - split up components into smaller components - allow users to easily customize new layouts using frontmatter (see @kevinlin1's [comment in #959](https://github.com/just-the-docs/just-the-docs/issues/959#issuecomment-1249755249)) Related work for `v1.0` (i.e. a major breaking change): - rename and better categorize existing includes - standardizing the "custom" includes - moving other components to the `components/` folder (ex `head`, `nav`) - potentially: less confusing naming for various components - potentially separate the search and header as components, so that they are completely independent Tangentially related work: - more flexible grid (see @JPrevost's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1363314610)) - a formal [feature model](https://en.wikipedia.org/wiki/Feature_model) of JTD, documenting feature dependence (see @pdmosses's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1365414023)) - better annotate new features (motivated by writing these docs) - we should add "New" to new features :) - we should note when a feature was introduced (I think this is a core part of most software documentation) - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge --- Closes #959. |