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
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)
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 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
