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>
Previously, the color scheme information was not passed on to the
browser. This could result in scrollbars being light, when the dark
theme is in use.
Now, `:root { color-scheme: $color-scheme; }` is specified.
This will ensure the color theme is enforced.
Ref: https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme
Closes#1285.
(missed this in code review, which is also my bad! this is because the `:not` selector changes specificity, which in turn changes the cascade)
This is the minimum code change that fixes the issue discussed in #1271 and #1272. In short, Mermaid has its own `.label` that it uses for styling + JS behaviour. To fix this, I add a relatively simple `:not()` that prevents usage with `g`, which is invalid in non-SVG HTML anyways. There should be minimal performance impact.
To test, observe:
- on `main`, selecting the "A" label in https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks has the class `.label`; dev tools will indicate that JtD's `.label` styling is applied
- but, on this branch, dev tools will indicate that the `.label` styling is not applied; observe otherwise that the page behaves the same
Closes#1272.
This PR replaces all uses of `px` in relation to font size (opposed to borders, spacing, etc.) with the equivalent `rem` value when the body font size is `16px`. The intention is to better scale the website when the user changes the font size for `<body>` (often done for accessibility reasons).
This PR is technically a **breaking change**, though it's a minor one (see subheading below). I'm putting this up so that we can discuss it as a community.
(technically closes#1088 and fixes#1073, but let's see if we end up merging this)
## mechanics
To do this, I systematically went through every `px` value for all `.scss` files. Then, I deleted the `rem` function, the `_functions.scss` file (that was the only function there), and removed the import from `support.scss`. A nice side effect of this is that we no longer perform any SASS division.
The only remaining uses of `px` are for either:
- border-related properties
- shadow-related properties
- sizing for "non-text" elements (ex `hr`, `blockquote` decorative spacing)
- `$root-font-size` (see below)
The only pixel value change in this PR is the `padding-left` for `blockquote`, which I've changed from `15px` to `1rem` (which is `16px` in the "stock" theme).
## deprecating `$root-font-size`
There's a SCSS variable called `$root-font-size`. It is used in two places:
1. the `rem()` function
2. the `.site-title` when printing (i.e. a `@print` style)
The changes I listed above let us ignore the first case. The second case seems like it has the intention of matching the body font size, so I replaced it with `1rem`.
We can choose to leave the variable in (in case others use it in custom code - which I'm sure that some do) and leave a deprecation notice, or just remove it now. I'm leaning towards the former, which is less disruptive.
## how users would upgrade
This is a breaking change of *some* sorts, but the change is very straightforward for users:
1. If they do not change `$root-font-size`, they need to do nothing; this PR is a no-op.
2. if they do change `$root-font-size`
- they should instead set the `font-size` of `body` with the appropriate `px` value
- optionally, they can replace all custom code that uses `$root-font-size` with `1rem` (find-and-replace works here)
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
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>
Realized that the new syntax is only supported on [Safari 16.4](https://caniuse.com/css-media-range-syntax), which is gated by OS updates. Going to revert this change for the foreseeable future.
Closes#1239.
The scope of this PR has changed slightly - it now removes all styling of `::selection`, which reverts selected-element highlighting to browser defaults (typically a blue highlight with no text colour changes). It still inadvertently closes#1201.
I've included the original PR body below:
---
This resolves an issue on Firefox where selecting a code block produces white text on a white background, which is not legible. To test: visit https://deploy-preview-1208--just-the-docs.netlify.app/docs/index-test/, and highlight various code blocks in light/dark mode.
I did a bit more digging, and realized a handful of things:
- when I added the new `OneLightJekyll` theme, I inadvertently bundled in a `::selection` class; I've removed it.
- I'm not really sure why this is a part of the theme in the first place!
- this is technically the minimum change required to have no more issues
- however, at this point, Firefox now correctly uses the global `::selection`, which is white-on-purple; this is *different* from Chrome, which somehow overrides this for `pre` or `code`; I also (subjectively) think this is harder to read.
- the vast majority of websites default to the browser/user agent stylesheet for code highlighting; for example, [react.dev](https://react.dev)
- so, I've elected to instead default to the browser/user agent stylesheet; this has the nice side effect of making Chrome and Firefox consistent again
Questions for reviewers/community members:
- does this fix the problem for you? what about other browsers?
- do we like having the browser default for code selection, or should we stick to white-on-purple?
Closes#1201.
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.
This is an internal change that only affects developers of our theme. This PR:
- **upgrades `Stylelint` to `v15`!**
- among other things, this leads to the deprecation of many stylistic rules, which overlap with Prettier
- it also sees the addition of new rules that catch more errors, especially `declaration-property-value-no-unknown`!
- upgrades the accompanying standard config (the SCSS one extends the first-party one); this new config disables the deprecated rules that overlap with Prettier
- removes a now-unneeded plugin that disables overlapping rules
- moves the `stylelint` config object to `package.json` - now we have one less file (particularly important since people still clone this repo)
There were very few new changes; I combined one string that had a dangling `+` in an SCSS warning, and have temporarily disabled the `at-rule-empty-line-before` rule (which also picks up on SCSS `@includes`).
These changes accommodate for some difference in the HTML structure AsciiDoc produces for source code listings:
* proper padding for source code listings
* proper vertical margin after source code listings
* proper placement of the copy button if enabled
Closes#1163
When customizing `$code-background-color` in `dark.scss`, the result is a multi-color background. (see https://github.com/just-the-docs/just-the-docs/issues/1121#issuecomment-1374976843)
This makes OneDarkJekyll code block colors the same as the specified `$code-background-color`, and uses the `$default-body-color` as the line number text color, which can otherwise be invisible due to the default being black and is hard to see on a very dark code block background.
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>
This PR corrects the change to `/_sass/search.scss` made in 551398f. This change tried to set the `padding-**top**` property to **two** values rather than set the `padding` property to these values (to represent the vertical and horizontal padding values).
I just reviewed 551398f and believe that this should be the other half of the fix proposed by just-the-docs/just-the-docs#1104.
This PR fixes three bugs:
# first bug
When revising my last PR #1086 I realised a slight bug in the code-copy PR #945 , my change to the css ignored a case. This PR is a hotfix and
Before PR #945:
After PR #945:
Fix:
# second bug
> @simonebortolin @mattxwang I'm trying to write some regression tests for this feature.
>
> If I use GitHub's copy button to copy the following plain text, it preserves all the spaces:
>
> ```
> 1 leading space
> 2 leading spaces and 2 trailing spaces
> 3 internal spaces
> 4 trailing spaces
> ```
>
> Using the new copy button with the same text in this PR branch of JTD gives this:
>
> ```
> 1 leading space
> 2 leading spaces and 2 trailing spaces
> 3 internal spaces
> 4 trailing spaces
> ```
>
> It appears that the leading space from line 1 has been removed, and inserted on all the other lines. Moreover, the 4 trailing spaces have been removed.
>
> BTW, #924 didn't give a precise requirements spec, but mentioned the Microsoft docs UI; @mattxwang mentioned also the GitHub UI. It would be helpful to add a functional spec of what the JTD copy button is supposed to do, as a basis for regression tests.
>
> I'm not aiming at a rigorous test for the UI. Personally (using Safari at the default mag) I find the clipboard icon too small: it just looks like a box, and I can hardly see that there is a clip at the top. But I don't have a suggestion for a better icon.
# third bug
When I re-read the code after the second bug, I noticed a bug that it does not always select the text field to be copied correctly (in case there are also line numbers) is copied:
```
1
2
3
4
# Ruby code with syntax highlighting and fixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
```
instead of
```
# Ruby code with syntax highlighting and fixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
```
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR corrects the change to `/_sass/labels.scss` made in 551398f92fc125f4692e49d636d2625ca2bf3819. This change tried to set the `padding-**top**` property to **two** values rather than set the `padding` property to these values (to represent the vertical and horizontal padding values).
Context: #1074, #1076. I think the problem is likely with `@use "sass:math";`; the stock pages image doesn't contain an up-to-date enough version of SASS. I've instead replaced just that instance with a runtime `calc()` operation, which *should* get optimized away by the compiler (see: [SASS docs](https://sass-lang.com/documentation/breaking-changes/slash-div#transition-period)).
---
Original PR body:
> @pdmosses noticed that we have deprecation warnings on some of our SASS code. After testing locally, all of them have to do with using / as division in SASS, which is [deprecated](https://sass-lang.com/documentation/breaking-changes/slash-div) (since there's some lexical ambiguity).
>
> SASS has a nifty [migrator tool](https://github.com/sass/migrator). I used the migrator piecewise on each deprecation warning (since the global usage fails on some liquid code). Upon manual inspection, I think there are no false positives. Running bundle exec jekyll serve after a fresh install and bundle update no longer emits any warnings.
@pdmosses noticed that we have deprecation warnings on some of our SASS code. After testing locally, all of them have to do with using `/` as division in SASS, which is [deprecated](https://sass-lang.com/documentation/breaking-changes/slash-div) (since there's some lexical ambiguity).
SASS has a nifty [migrator tool](https://github.com/sass/migrator). I used the migrator piecewise on each deprecation warning (since the global usage fails on some liquid code). Upon manual inspection, I think there are no false positives. Running `bundle exec jekyll serve` after a fresh install and `bundle update` no longer emits any warnings.
Closes#1073; blocked by #1072 (CI failure).
* Add toc heading custom include
Closes#961.
* Revert "Add toc heading custom include"
This reverts commit 49813c341973e313db0a21f075a60ebf2120989e.
* Update code highlighting with line numbers
- Add the example of code highlighting with line numbers explained in the [Jekyll docs](https://jekyllrb.com/docs/liquid/tags/#line-numbers).
- Fix the styling of narrow code with line numbers, which floats to the centre without this CSS adjustment. (The line numbers column expands as needed with larger numbers of lines, despite using `width`; using `min-width` doesn't work.)
To apply HTML compression, I removed `vendor` from `exclude`; that change is left to a different PR.
The jekyll-asciidoc plugin will take AsciiDoc markup like this:
.A method that returns the string "Hello, world"
[example]
[source,ruby]
----
def hello
"Hello, world"
end
----
And produce HTML like this (syntax highlighting disabled):
<div class="listingblock">
<div class="title">A method that returns the string "Hello, world"</div>
<div class="content">
<pre class="highlight"><code class="language-ruby" data-lang="ruby">def hello
"Hello, world"
end</code></pre>
</div>
</div>
Previously, because we were applying code block styling to the whole
listingblock, the title would be rendered as normal body text, inside
the code block, which did not look good. With this change, it will
instead be rendered similarly to a Just The Docs rendered example —
the title will appear where the rendered example usually would.
Co-authored-by: Matt Wang <matt@matthewwang.me>
This is a catch-all PR that modernizes and updates our Stylelint config, and resolves all open issues. This is a pretty big change - so I want to update all of our related dependencies in lockstep.
In particular, this PR
- [x] updates stylelint to `v14`
- [x] adds in the standard stylelint config for SCSS (`stylelint-config-standard-scss`)
- [x] swaps out `stylelint-config-prettier` for `stylelint-config-prettier-scss`
- [x] ~~properly update `@primer`-related plugins:~~ completely remove `primer` from our configuration
- [x] autofix, manually resolve, or disable all newly-introduced lint errors; **I've avoided manually resolving errors that would be a behavioural change**
- [x] re-runs `npm run format`
See the "next steps" section on some extra thoughts on disabling errors.
(implicitly, I'm also using node 16/the new package-lock format).
### disabling rules and next steps
I've introduced several new disabled rules. Let me quickly explain what's going on; there are two categories of rules I've disabled:
1. rules that were temporary disables; they were frequent enough that I couldn't manually resolve them, but should be simple. **I plan on opening issues to re-enable each of these rules**, just after this PR
- `declaration-block-no-redundant-longhand-properties`: this is just tedious and error-prone
- `no-descending-specificity`: this one is tricky since it could have impacts on the cascade (though that seems unlikely)
- `scss/no-global-function-names`: I think we need to [import map and then use `map.get`](https://stackoverflow.com/questions/64210390/sass-map-get-doesnt-work-map-get-does-what-gives), but I'll leave this as out of scope for now
2. rules that are long-term disables; due to the SASS-based nature of our theme, I think we'll keep these in limbo
- `alpha-value-notation` causes problems with SASS using the `modern` syntax - literals like `50%` are not properly interpolated, and they cause formatting issues on the site
- `color-function-notation` also causes problems with SASS, but in this case the `modern` syntax breaks SASS compilation; we're not alone (see this [SO post](https://stackoverflow.com/questions/71805735/error-function-rgb-is-missing-argument-green-in-sass)).
In addition, we have many inline `stylelint-disable` comments. I'd open a separate issue to audit them, especially since I think some disables are unnecessary.
### on Primer
**note: there hasn't been much other discussion, so I'm going to remove primer's stylelint config.**
If I do add `@primer/stylelint-config`, I get *a ton* of errors about now using `@primer`'s in-built SCSS variables. I imagine that we probably won't want to use these presets (though I could be wrong). In that case, I think we could either:
1. disable all of those rules
4. not use `@primer/stylelint-config`, since we're not actually using primer, and shift back to the standard SCSS config provided by Stylelint
~~Any thoughts here? I also don't have the original context as to why we do use the primer rules, perhaps @pmarsceill can chime in?~~
I have a site whose content is written in AsciiDoc, using the [jekyll-asciidoc][] plugin.
Just the Docs works great, but there are just two minor styling glitches I've noticed:
The first is that Just the Docs' CSS doesn't understand the code block markup jekyll-asciidoc produces. It's not too different though, so it's very easily fixed.
The second is that jekyll-asciidoc generates `div.sect(𝑛 − 1)` elements around headings of type `h𝑛`, that enclose all the heading and all the content after it until the next heading of greater or equal rank.
This means that headings are _always_ first children in AsciiDoc output, which meant the wrong margins were applied to most headings. To fix this, we need to only reduce the margin of first-child headings nested directly below the .main-content element, and headings nested directly below AsciiDoc `.sect𝑛` elements that are themselves first children.
With these two small changes, my site looks perfect, and the styles look exactly the same as on Just the Docs' own documentation.
[jekyll-asciidoc]: https://github.com/asciidoctor/jekyll-asciidoc
Fix#517
Users expect nested task lists to have the same indentation as other lists.
Fix the styling in `_sass/content.scss` to do that.
Add examples in `docs/index-test.md` to test.
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>
