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)
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.
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`).
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).
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?~~
