Tone down admonition coloring and adjust border-width of elements (#2499

)

This patch tones down the admonitions by removing the background color
in the admonition header and the lighter background color in the body.
Instead the text in the admonition header is colored, and the colored
border thickness increased slightly.

The border width of code blocks and docstrings have been increased to
match the new border width of admonitions. Code blocks and docstrings
now also have a (non-zero) border radius to match admonitions (which
already were rounded before this patch).

CHANGELOG.md

@@ -3,6 +3,15 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Changed
+
+* Coloring of admonitions have been toned down in order to make them slightly less
+  eye-catching. ([#2499])
+* Thickness and rounding of docstrings and code blocks have been adjusted to match
+  admonitions. ([#2499])
+
 ## Version [v1.4.1] - 2024-05-02
 
 ### Fixed
@@ -1833,6 +1842,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2480]: https://github.com/JuliaDocs/Documenter.jl/issues/2480
 [#2482]: https://github.com/JuliaDocs/Documenter.jl/issues/2482
 [#2497]: https://github.com/JuliaDocs/Documenter.jl/issues/2497
+[#2499]: https://github.com/JuliaDocs/Documenter.jl/issues/2499
 [JuliaLang/julia#36953]: https://github.com/JuliaLang/julia/issues/36953
 [JuliaLang/julia#38054]: https://github.com/JuliaLang/julia/issues/38054
 [JuliaLang/julia#39841]: https://github.com/JuliaLang/julia/issues/39841

assets/html/scss/documenter-dark.scss

@@ -26,22 +26,25 @@ $cyan: #3489da;
 $blue: #3c5dcd;
 $purple: #9558b2;
 
-$info: #024c7d;
-$success: #008438;
-$warning: #ad8100;
-$danger: #9e1b0d;
-$compat: #137886;
+// Admonition colors
+$info: $blue;
+$success: $green;
+$warning: $yellow;
+$danger: $red;
+$compat: $cyan;
+$admonition-default: $grey-lighter;
 
 $admonition-background: (
   'default': $background, 'info': $background, 'success': $background, 'warning': $background,
   'danger': $background, 'compat': $background
 );
-$admonition-header-background: ('default': $grey);
 // These would normally get initialized in _admonition.scss. However, since we are not
 // loading it on the top level, we need to set them here too to avoid deprecation warnings.
 // https://github.com/JuliaDocs/Documenter.jl/issues/1766
+$admonition-header-background: ();
 $admonition-header-color: ();
 $admonition-body-color: ();
+$admonition-border-color: ();
 
 $body-size: 16px;
 $documenter-sidebar-background: $grey-darker;

assets/html/scss/documenter-light.scss

@@ -1,11 +1,23 @@
 @charset "UTF-8";
 
-// TODO: use default colors
-$info: #209cee;
-$success: #22c35b;
-$warning: #ffdd57;
-$danger: #da0b00;
-$compat: #1db5c9;
+// TODO: Adjust these colors to increase contrast a bit and use the without
+//       adjustments as admonition colors below.
+$red: #cb3c33 !default;
+$orange: #d56c00 !default;
+$yellow: #f4c72f !default;
+$green: #259a12 !default;
+$turquoise: #00a1b7 !default;
+$cyan: #3489da !default;
+$blue: #3c5dcd !default;
+$purple: #9558b2 !default;
+
+// TODO: Remove adjustments when colors above are adjusted.
+$info: $blue;
+$success: $green;
+$warning: adjust-color($yellow, $hue: 2, $saturation: 10, $lightness: -24);
+$danger: $red;
+$compat: $cyan;
+$admonition-default: hsl(0, 0%, 29%);
 
 // slightly increase contrast over default l: 48%
 $grey: hsl(0, 0%, 42%);
@@ -44,4 +56,4 @@ code.language-julia-repl > span.hljs-meta {
 
 .gap-4 {
   gap: 1rem;
-}
+}

assets/html/scss/documenter/_overrides.scss

@@ -35,7 +35,6 @@ $breadcrumb-item-disabled-color: $text-strong !default;
 
 $content-pre-padding: 0 !default;
 
-$admonition-background: ('default': $grey-light, 'warning': #fff3c5) !default;
 
 $documenter-docstring-shadow: 2px 2px 3px rgba($black, 0.1) !default;
 $documenter-docstring-header-background: $background !default;

assets/html/scss/documenter/_patches.scss

@@ -1,7 +1,8 @@
 // We need to override some .content behavior
 .content {
   pre {
-    border: 1px solid $border;
+    border: $documenter-codeblock-border-width solid $border;
+    border-radius: $documenter-codeblock-border-radius;
   }
   // Bold code spans
   code {

assets/html/scss/documenter/_variables.scss

@@ -27,6 +27,17 @@ $code-padding: 0.1em;
 
 $documenter-docstring-background: transparent !default;
 
+// Shared configuration for docstrings/code snippets/admonitions etc.
+$documenter-element-border-width: 2px;
+$documenter-element-border-radius: 4px;
+
+$documenter-docstring-border-width: $documenter-element-border-width;
+$documenter-docstring-border-radius: $documenter-element-border-radius;
+$documenter-codeblock-border-width: $documenter-element-border-width;
+$documenter-codeblock-border-radius: $documenter-element-border-radius;
+$documenter-admonition-border-width: $documenter-element-border-width;
+$documenter-admonition-border-radius: $documenter-element-border-radius;
+
 $documenter-is-dark-theme: false !default;
 
 // Helper functions

assets/html/scss/documenter/components/_admonition.scss

@@ -1,27 +1,31 @@
 // This is a heavily customized version of Bulma's message component
 // Original copyright (c) 2019 Jeremy Thomas, The MIT License (MIT)
 $admonition-colors: (
-  'default': $grey-darker, 'info': $info, 'success': $success, 'warning': $warning,
+  'default': $admonition-default, 'info': $info, 'success': $success, 'warning': $warning,
   'danger': $danger, 'compat': $compat,
 ) !default;
 
 $admonition-background: () !default;
 $admonition-body-color: () !default;
 $admonition-header-background: () !default;
 $admonition-header-color: () !default;
+$admonition-border-color: () !default;
 @each $name, $color in $admonition-colors {
-  $bg: lighten-color($color, 5);
+  // $bg: lighten-color($color, 5);
   @if not map-has-key($admonition-header-background, $name) {
-    $admonition-header-background: map-merge($admonition-header-background, ($name: $color)) !global;
+    $admonition-header-background: map-merge($admonition-header-background, ($name: transparent)) !global;
   }
   @if not map-has-key($admonition-header-color, $name) {
-    $admonition-header-color: map-merge($admonition-header-color, ($name: findColorInvert($color))) !global;
+    $admonition-header-color: map-merge($admonition-header-color, ($name: $color)) !global;
+  }
+  @if not map-has-key($admonition-border-color, $name) {
+    $admonition-border-color: map-merge($admonition-border-color, ($name: $color)) !global;
   }
   @if not map-has-key($admonition-background, $name) {
-    $admonition-background: map-merge($admonition-background, ($name: $bg)) !global;
+    $admonition-background: map-merge($admonition-background, ($name: $background)) !global;
   }
   @if not map-has-key($admonition-body-color, $name) {
-    $admonition-body-color: map-merge($admonition-body-color, ($name: findColorInvert($bg))) !global;
+    $admonition-body-color: map-merge($admonition-body-color, ($name: findColorInvert($background))) !global;
   }
 }
 
@@ -30,9 +34,9 @@ $admonition-header-color: () !default;
 
   background-color: map-get($admonition-background, 'default');
   border-style: solid;
-  border-width: 1px;
-  border-color: map-get($admonition-header-background, 'default');
-  border-radius: $message-radius;
+  border-width: $documenter-admonition-border-width;
+  border-color: map-get($admonition-border-color, 'default');
+  border-radius: $documenter-admonition-border-radius;
   font-size: $size-normal;
 
   strong {
@@ -60,7 +64,7 @@ $admonition-header-color: () !default;
 
     &.is-#{$name} {
       background-color: map-get($admonition-background, $name);
-      border-color: map-get($admonition-header-background, $name);
+      border-color: map-get($admonition-border-color, $name);
 
       > .admonition-header {
         background-color: map-get($admonition-header-background, $name);

assets/html/scss/documenter/components/_docstring.scss

@@ -2,7 +2,8 @@
 .docstring {
   margin-bottom: 1em;
   background-color: $documenter-docstring-background;
-  border: 1px solid $border;
+  border: $documenter-docstring-border-width solid $border;
+  border-radius: $documenter-docstring-border-radius;
   box-shadow: $documenter-docstring-shadow;
   max-width: 100%;