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 06:13:32 -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-sm: 10px !default;
-$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small
-$font-size-3: 12px !default; // h5
-$font-size-4: 14px !default;
-$font-size-5: 16px !default; // h3
-$font-size-6: 18px !default; // h2
-$font-size-7: 24px !default;
-$font-size-8: 32px !default; // h1
-$font-size-9: 36px !default;
-$font-size-10: 42px !default;
-$font-size-10-sm: 48px !default;
+$font-size-1: 0.5625rem !default;
+$font-size-1-sm: 0.625rem !default;
+$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small
+$font-size-3: 0.75rem !default; // h5
+$font-size-4: 0.875rem !default;
+$font-size-5: 1rem !default; // h3
+$font-size-6: 1.125rem !default; // h2
+$font-size-7: 1.5rem !default;
+$font-size-8: 2rem !default; // h1
+$font-size-9: 2.25rem !default;
+$font-size-10: 2.625rem !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-md: 248px !default;
+$nav-width: 16.5rem !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;
-$header-height: 60px !default;
+$content-width: 50rem !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,
-  sm: 500px,
+  xs: 20rem,
+  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"]