v0.5.3

Fix font-size scaling for text-related CSS properties by using rem instead of fixed px values; deprecate $root-font-size (#1169 )
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)
2025-09-16 14:23:31 -06:00 · 2023-06-17 13:38:02 -07:00 · 2023-06-15 19:11:14 -07:00
10 changed files with 60 additions and 37 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,39 @@ Docs changes in `main` that are *not* in the latest release:
 - N/A
 ## Release v0.5.3
 Hi all, this is a minor patch release that only includes one change: changing all text-based CSS properties to use `rem` instead of hard-coded `px` values. This has two effects:
 1. All deprecation warnings are now fixed on build; you should now get a clean build with `jekyll build`.
 2. We have **deprecated the `$root-font-size` SCSS variable**. We will remove it in an upcoming release of the theme.
 If you use the stock Just the Docs theme, this release should have no impact on your final built site. If you change the `$root-font-size` SCSS variable, you might experience light layout shifts.
 ### Using Release `v0.5.3`
 Users who have not pinned the theme version will be **automatically upgraded to `v0.5.3` the next time they build their site**.
 To use this release explicitly as a remote theme:
 ```yml
 remote_theme: just-the-docs/just-the-docs@v0.5.3
 ```
 To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 ```ruby
 gem "just-the-docs", "0.5.3"
 ```
 To use and pin a previous version of the theme, replace the `0.5.3` with the desired release tag.
 ### Bugfixes
 - Fixed: font-size scaling for text-related CSS properties by using `rem` instead of fixed `px` values; deprecate `$root-font-size` by [@mattxwang] in [#1169]
 [#1169]: https://github.com/just-the-docs/just-the-docs/pull/1169
 ## Release v0.5.2
 Hi all, this is a minor patch release that mostly focuses on accessibility. Since we follow semantic versioning, this should be a smooth upgrade with no breaking changes.
--- a/_sass/base.scss
+++ b/_sass/base.scss
@@ -104,6 +104,6 @@ blockquote {
  // resets user-agent stylesheets for blockquotes
  margin-block-start: 0;
  margin-inline-start: 0;
-  padding-left: 15px;
+  padding-left: 1rem;
  border-left: 3px solid $border-color;
 }
--- a/_sass/print.scss
+++ b/_sass/print.scss
@@ -21,7 +21,7 @@
  }
  .site-title {
-    font-size: $root-font-size !important;
+    font-size: 1rem !important;
    font-weight: 700 !important;
  }
--- a/_sass/search.scss
+++ b/_sass/search.scss
@@ -42,7 +42,7 @@
  width: 100%;
  height: 100%;
  padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
-  font-size: 16px;
+  font-size: 1rem;
  color: $body-text-color;
  background-color: $search-background-color;
  border-top: 0;
@@ -53,7 +53,7 @@
  @include mq(md) {
    padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5};
-    font-size: 14px;
+    font-size: 0.875rem;
    background-color: $body-background-color;
    transition: padding-left linear #{$transition-duration * 0.5};
  }
--- a/_sass/support/_functions.scss
+++ b/_sass/support/_functions.scss
@@ -1,9 +0,0 @@
@function rem($size, $unit: "") {
  $rem-size: $size / $root-font-size;
  @if $unit == false {
    @return #{$rem-size};
  } @else {
    @return #{$rem-size}rem;
  }
 }
--- a/_sass/support/_variables.scss
+++ b/_sass/support/_variables.scss
@@ -3,7 +3,7 @@
 $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
  roboto, "Helvetica Neue", arial, sans-serif !default;
 $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
-$root-font-size: 16px !default; // Base font-size for rems
+$root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems
 $body-line-height: 1.4 !default;
 $content-line-height: 1.6 !default;
 $body-heading-line-height: 1.25 !default;
@@ -11,18 +11,18 @@ $body-heading-line-height: 1.25 !default;
 // Font size
 // `-sm` suffix is the size at the small (and above) media query
-$font-size-1: 9px !default;
+$font-size-1: 0.5625rem !default;
-$font-size-1-sm: 10px !default;
+$font-size-1-sm: 0.625rem !default;
-$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small
+$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small
-$font-size-3: 12px !default; // h5
+$font-size-3: 0.75rem !default; // h5
-$font-size-4: 14px !default;
+$font-size-4: 0.875rem !default;
-$font-size-5: 16px !default; // h3
+$font-size-5: 1rem !default; // h3
-$font-size-6: 18px !default; // h2
+$font-size-6: 1.125rem !default; // h2
-$font-size-7: 24px !default;
+$font-size-7: 1.5rem !default;
-$font-size-8: 32px !default; // h1
+$font-size-8: 2rem !default; // h1
-$font-size-9: 36px !default;
+$font-size-9: 2.25rem !default;
-$font-size-10: 42px !default;
+$font-size-10: 2.625rem !default;
-$font-size-10-sm: 48px !default;
+$font-size-10-sm: 3rem !default;
 // Colors
@@ -95,22 +95,22 @@ $border-color: $grey-lt-100 !default;
 $gutter-spacing: $sp-6 !default;
 $gutter-spacing-sm: $sp-4 !default;
-$nav-width: 264px !default;
+$nav-width: 16.5rem !default;
-$nav-width-md: 248px !default;
+$nav-width-md: 15.5rem !default;
 $nav-list-item-height: $sp-6 !default;
 $nav-list-item-height-sm: $sp-8 !default;
 $nav-list-expander-right: true;
-$content-width: 800px !default;
+$content-width: 50rem !default;
-$header-height: 60px !default;
+$header-height: 3.75rem !default;
 $search-results-width: $content-width - $nav-width !default;
 $transition-duration: 400ms;
 // Media queries in pixels
 $media-queries: (
-  xs: 320px,
+  xs: 20rem,
-  sm: 500px,
+  sm: 31.25rem,
  md: $content-width,
  lg: $content-width + $nav-width,
-  xl: 1400px,
+  xl: 87.5rem,
 ) !default;
--- a/_sass/support/mixins/_layout.scss
+++ b/_sass/support/mixins/_layout.scss
@@ -12,7 +12,7 @@
  // If the key exists in the map
  @if $value {
    // Prints a media query based on the value
-    @media (min-width: rem($value)) {
+    @media (min-width: $value) {
      @content;
    }
  } @else {
--- a/_sass/support/support.scss
+++ b/_sass/support/support.scss
@@ -1,3 +1,2 @@
@import "./variables";
@import "./functions";
@import "./mixins/mixins";
--- a/_sass/tables.scss
+++ b/_sass/tables.scss
@@ -21,7 +21,7 @@ th,
 td {
  @include fs-3;
-  min-width: 120px;
+  min-width: 7.5rem;
  padding: $sp-2 $sp-3;
  background-color: $table-background-color;
  border-bottom: $border rgba($border-color, 0.5);
--- a/just-the-docs.gemspec
+++ b/just-the-docs.gemspec
@@ -2,7 +2,7 @@
 Gem::Specification.new do |spec|
  spec.name          = "just-the-docs"
-  spec.version       = "0.5.2"
+  spec.version       = "0.5.3"
  spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
  spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]