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>
* 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>
* 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>
This PR replaces the default light code highlighting theme with Atom's One Light theme colors. This should provide more visual similarity with our dark theme, and as a byproduct, fix some of the contrast issues from our current light theme.
In addition (different from the original purpose of this PR), this also moves theme variables from `variables.scss` to `light.scss`, which always gets loaded anyways.
To test, compare the [deploy preview's kitchen sink Python code](https://deploy-preview-1166--just-the-docs.netlify.app/docs/index-test/#more-code) to the current [`main` branch's code](https://just-the-docs.github.io/just-the-docs/docs/index-test/#more-code); you can also use the "Preview dark color scheme" button to see OneDarkJekyll in action.
Users can opt-in to the old theme with `legacy_light`. I've documented this in the "customization" page.
Closes#679.
## implementation
Feel free to skip this part.
To do this, I:
- forked [mgyongyosi/OneDarkJekyll](https://github.com/mgyongyosi/OneDarkJekyll) to our own organization, [OneLightJekyll](https://github.com/just-the-docs/OneLightJekyll)
- updated the code to be slightly more robust (e.g. not require installing to global path)
- replaced the `colors.less` with the one pulled from Atom's [one-light-syntax](https://github.com/atom/atom/tree/master/packages/one-light-syntax)
- updated the license notice to also include GitHub's work in Atom
- regenerated the file
- plopped it in our current theme code
## next steps
This is related to #1100. I wanted to make this PR easier to review, so I won't implement that just yet; once we merge this, I can push that PR through. It's also related to #1173; in a comment below, I've also outlined some potential future work.
After we merge this, I'll trigger a release soon. I think this next minor bump can be focused on color schemes, e.g. dark theme, theme switching, and some bugfixes.
In #1058, I noted:
> Tangentially related work:
> ...
> - 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
>
This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later.
This PR is me doing that. I:
- have added a headings-level "New" label to every new heading introduced since `v0.3`
- added, when possible, inline YAML comments when new configuration options have been introduced
I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation.
I may have also missed any new features, so some double-checking would be helpful!
This is an alternative PR that resolves#1011. Unlike #1013, this PR defines a *new* SASS file, `_sass/custom/setup.scss`, specifically designed for new custom variables (and other SASS-only constructs). It's imported after our `support` SASS files are (functions, variables), but otherwise is imported before all other files (ex, when CSS is emitted).
So, custom callout colors can now be defined in this file. I also move the custom callout colors present in `custom.scss` to the right location.
I've added some docs that briefly explain how to use the feature. Feedback is welcome!
---
As an aside, I chose not to add a `_includes/css` file that imports this, and then import that file. I think that's only necessary if we're trying to render liquid somehow in the SASS file; since we're not trying to do that for `setup.scss`, I've opted to not include it. If we think this is relevant, I can re-add it.
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
In touching up the migration guide, I noticed that many of our documentation site links are broken! For example, on the homepage, this link:
<img width="782" alt="screenshot of homepage; code snippet is in next block" src="https://user-images.githubusercontent.com/14893287/210462690-31aa7bf5-dd79-4e8f-a3c5-1213e73771c4.png">
which has the following href
```code
<a href="/just-the-docs/just-the-docs/CHANGELOG/">the CHANGELOG</a>
```
duplicates the `baseurl` twice. There are 14 such broken links across the site. Each link duplicates the `baseurl` and `link` tags, which has since been resolved with links being relative by default (there's a set of PRs that document this - I can't find the exact paper trail right now).
To resolve this, I:
- find and replace site-wide `{{ site.baseurl }}{% link` with `{% link`
- tested each link, which now works properly locally *and* on the deploy preview
I'm surprised we didn't catch this earlier! I also could be missing something else, in which case feedback on this PR is certainly welcome.
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.
Avoid the need to add a link to favicon,ico when editing `_includes/head_custom.html`, and avoid creating an invalid favicon link
- Remove the content of `_includes/head_custom.html`
- Add code to `_includes/head.html` to create a link to an existing favicon,ico
- Add an explanation of favicon_ico to docs/configuration.md
- Remove the example of `includes/head_custom.html` and add an explanation of what the `<head>` element automatically includes
Fix two bugs in customization docs
- custom favicon docs were not wrapped in `{% raw %}` tags
- the "new" annotation for color schemes had an extra whitespace, and so the CSS class was not applied
* Removes `favicon.html`, shifts content to `head_custom.html`
* explicit callout for custom favicon in customization docs
* Cleaner and more consistent documentation (review from @pdmosses)
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
* Fix default highlighting in custom schemes
Fix#982
The variable settings for highlighting in the default `light` scheme are currently (v0.4.0.rc2`) in `_sass/color_schemes/light.scss`.
This PR ensures that custom schemes are based on the `light` scheme.
It also adds a note explaining the default to the customization docs,
and gives an example of how to define a custom scheme based on the `dark` scheme
* Prettier
* Deleted test file
Co-authored-by: Matt Wang <matt@matthewwang.me>
Looking at how the variables are defined in _variables.scss, with various dependencies between them aimed at ensuring a consistent color scheme, one might expect that redefining a given variable would affect the remaining styles that depend on it.
This is not the case, however, due to the order in which the files are processed. This PR edits the documentation to mention the non-propagating behavior of redefined variables, to better guide users that wish to customize the site using custom themes, and call their attention to the need to redefine the dependency relations as well.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
These docs outline some of the custom includes that are provided by the theme and can be modified by the user.
Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
This commit makes the dark mode preview feel a little more interactive
and it also pulls some duplicated code into one file so that people like
me aren't stumped when they are looking at the wrong page!
