Dokka Style Improvements Discussion

[solonovamax]

I believe that there are some improvements that could be made to the presentation of the documentation for dokka, so this is a master issue to discuss some of those changes that I would like to see.
If it is decided that any should be added, then I can make a PR with them.

I made a PR with some of these changes a while back, however I think it's probably best to discuss them further, as well as any other possible changes.

I currently have a dokka plugin which applies these changes, however I think these are all very good candidates to be merged into dokka directly.

Here are some of the changes I'd like to propose:

Highlight Entire Sidebar Row on Hover

Currently, when you hover over a row in the sidebar, then it will only highlight part of the row:

However, I believe that it looks better if the entire row is highlighted when hovered:

CSS Changes

diff --git a/a/ui-kit.css b/b/ui-kit.css
index 502c45a..5e00d12 100644
--- a/a/ui-kit.css
+++ b/b/ui-kit.css
@@ -2062,16 +2062,6 @@ button.platform-tag:focus-visible {
     filter: invert(0);
   }
 }
-@media (hover: hover) {
-  .toc--button:hover {
-    background-color: rgba(0, 0, 0, 0.08);
-    background-color: var(--toc-hover-color);
-  }
-}
-.toc--button:active {
-  background-color: rgba(0, 0, 0, 0.08);
-  background-color: var(--toc-hover-color);
-}
 
 .toc--button.focus-visible {
   outline: var(--focus-outline);
@@ -2092,11 +2082,6 @@ button.platform-tag:focus-visible {
   width: 100%;
 }
 
-.toc--link:hover {
-  background-color: rgba(0, 0, 0, 0.08);
-  background-color: var(--toc-hover-color);
-}
-
 .toc--link.focus-visible {
   outline: var(--focus-outline);
   outline-offset: -4px;
@@ -2107,6 +2092,10 @@ button.platform-tag:focus-visible {
   outline-offset: -4px;
 }
 
+.toc--row:hover {
+    background-color: var(--toc-hover-color);
+}
+
 .toc--part[data-nesting-level="0"] .toc--row > .toc--link:first-child {
   padding-left: 40px;
   padding-left: calc(40px + var(--size-m1) * 0);
@@ -2367,7 +2356,7 @@ button.platform-tag:focus-visible {
   color: var(--color-text-dt);
 }
 
-.toc--part[data-active] > .toc--row .toc--button:hover, .toc--part[data-active] > .toc--row .toc--link:hover {
+.toc--part[data-active] > .toc--row:hover {
   background-color: #578af7;
 }
 

Thin Scrollbar

Currently, I find the scrollbar a bit invasive. (and also, the css to modify the scrollbar currently does not work, as if scrollbar-color is set, then additional customization to the scrollbar does not seem to apply)

Before:

After:

CSS Changes

diff --git a/a/style.css b/b/style.css
index 7be5503..0a6637a 100644
--- a/a/style.css
+++ b/b/style.css
@@ -15,8 +15,8 @@
     --breadcrumb-margin: 24px;
     --hover-link-color: #5B5DEF;
 
-    --color-scrollbar: rgba(39, 40, 44, 0.40);
-    --color-scrollbar-track: var(--default-gray);
+    --color-scrollbar: rgb(39, 40, 44);
+    --color-scrollbar-active: rgb(96, 96, 96);
     --default-white: #fff;
     --background-color: var(--default-white);
     --dark-mode-and-search-icon-color: var(--default-white);
@@ -47,29 +47,33 @@
 html {
     height: 100%;
     -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
-    scrollbar-color: rgba(39, 40, 44, 0.40) #F4F4F4;
-    scrollbar-color: var(--color-scrollbar) var(--color-scrollbar-track);
     text-rendering: optimizeLegibility;
     -webkit-font-smoothing: antialiased;
     color: var(--default-font-color);
 }
 
 html ::-webkit-scrollbar {
-    width: 8px;
-    height: 8px;
+    width: 12px;
+    height: 12px;
 }
 
-html ::-webkit-scrollbar-track {
-    background-color: var(--color-scrollbar-track);
+html ::-webkit-scrollbar-track, html ::-webkit-scrollbar-corner {
+    background-color: transparent;
 }
 
 html ::-webkit-scrollbar-thumb {
     width: 8px;
-    border-radius: 6px;
-    background: rgba(39, 40, 44, 0.40);
+    border-radius: 8px;
+    border: 3px solid transparent;
+    background-clip: content-box;
+    background: rgb(39, 40, 44);
     background: var(--color-scrollbar);
 }
 
+html ::-webkit-scrollbar-thumb:active {
+    background-color: var(--color-scrollbar-active);
+}
+
 html, body {
     margin: 0;
     padding: 0;
@@ -208,6 +212,8 @@ td:first-child {
 
 /* ---dark theme --- */
 .theme-dark {
+    --color-scrollbar: rgb(144, 144, 144);
+
     --background-color: #262628;
     --color-dark: #3d3d41;
     --default-font-color: rgba(255, 255, 255, 0.96);

Purple Sidebar Highlight

I think purple fits the "kotlin" theme a bit better than blue. But, even better than purple would be if it could be customized by the user.
Here's an example of what it would look like in purple:

If you do not wish to make this directly configureable in the gradle plugin, then it would be nice if it could at the very least be made easier to change using a named css variable for this colour as well as the hovered colour.
Currently, it does have a css variable, however it is named --color-key-blue, and it would be sub-par to override that as it is used in other places (the hover colour does not have a css variable).
Something along the lines of --highlight-color and --highlight-color-hovered would be great.

Add color-scheme CSS Property

Currently, when set to dark mode, the color-scheme: dark css property is missing. This causes things like checkboxes to render weird.

Very simple fix is to just add

:root.theme-dark {
    color-scheme: dark;
}

Better Block Quotes

Currently, I find that block quotes don't look the best. They are hard to distinguish from the rest of the text, and the bar to the right is hard to see & doesn't look the best.

Here are 2 improvements (both can be used at the same time), which make it look slightly better:

Distinguished Block Quote Text

Makes block quote text easier to distinguish from the rest of the content.

Before:

After:

CSS Changes

diff --git a/a/style.css b/b/style.css
index 7be5503..fdcef16 100644
--- a/a/style.css
+++ b/b/style.css
@@ -127,11 +127,10 @@ blockquote {
     margin: 0;
     padding-left: 1ch;
     font-style: italic;
-    color: var(--average-color);
+    color: color-mix(in hsl, var(--default-font-color) 60%, var(--background-color));
 }
 
 .theme-dark blockquote {
-    color: var(--default-font-color);
     border-left-color: var(--code-background);
 }
 

Distinguished Block Quote Text

Makes block quote text easier to distinguish from the rest of the content.

Before:

After:

CSS Changes

diff --git a/a/style.css b/b/style.css
index 7be5503..c6dc190 100644
--- a/a/style.css
+++ b/b/style.css
@@ -123,16 +123,24 @@ u {
 }
 
 blockquote {
-    border-left: 1ch solid var(--default-gray);
     margin: 0;
     padding-left: 1ch;
+    position: relative;
     font-style: italic;
     color: var(--average-color);
 }
 
+blockquote::before {
+    position: absolute;
+    background: var(--hover-link-color);
+    border-radius: 8px;
+    content: '';
+    inset: 0 auto 0 0;
+    width: 4px;
+}
+
 .theme-dark blockquote {
     color: var(--default-font-color);
-    border-left-color: var(--code-background);
 }
 
 pre {

Section Tab Border

Rounds off the corners on the section tab border.

Before:

After:

CSS Changes

diff --git a/a/ui-kit.css b/b/ui-kit.css
index 502c45a..ca0197e 100644
--- a/a/ui-kit.css
+++ b/b/ui-kit.css
@@ -1849,13 +1849,13 @@ button.platform-tag:focus-visible {
 .platform-hinted > .platform-bookmarks-row > .platform-bookmark, .section-tab {
   background-color: transparent;
   border: 0;
-  border-bottom: 1px solid var(--inactive-tab-border-color);
   color: var(--inactive-section-color);
   cursor: pointer;
   font-size: var(--default-font-size);
   margin: 0 8px;
   outline: none;
   padding: 11px 3px;
+  position: relative;
 }
 
 .platform-hinted > .platform-bookmarks-row {
@@ -1873,15 +1873,25 @@ button.platform-tag:focus-visible {
 }
 
 .section-tab:hover {
-  border-bottom: 2px solid var(--default-font-color);
   color: var(--default-font-color);
 }
 
+.section-tab:hover::before {
+  height: 4px;
+  background: var(--default-font-color);
+  bottom: -2.5px;
+}
+
 .section-tab[data-active=""] {
-  border-bottom: 2px solid var(--active-tab-border-color);
   color: var(--active-section-color);
 }
 
+.section-tab[data-active=""]::before {
+  background: var(--active-tab-border-color);
+  height: 4px;
+  bottom: -2.5px;
+}
+
 .tabs-section-body > div {
   margin-top: 12px;
 }
@@ -1906,15 +1916,25 @@ button.platform-tag:focus-visible {
 }
 
 .platform-hinted > .platform-bookmarks-row > .platform-bookmark:hover {
-  border-bottom: 2px solid var(--default-font-color);
   color: var(--default-font-color);
 }
 
+.platform-hinted > .platform-bookmarks-row > .platform-bookmark:hover::before {
+  height: 4px;
+  background: var(--default-font-color);
+  bottom: -2.5px;
+}
+
 .platform-hinted > .platform-bookmarks-row > .platform-bookmark[data-active=""] {
-  border-bottom: 2px solid var(--active-tab-border-color);
   color: var(--active-section-color);
 }
 
+.platform-hinted > .platform-bookmarks-row > .platform-bookmark[data-active=""]::before {
+  background: var(--active-tab-border-color);
+  height: 4px;
+  bottom: -2.5px;
+}
+
 .js .platform-hinted > .content:not([data-active]), .js .tabs-section-body [data-togglable]:not([data-active]), .main-content[data-page-type=package] .tabs-section-body h2, .no-js .platform-bookmarks-row, .no-js .tabs-section {
   display: none;
 }

More Compact Sidebar

I find the current sidebar to have way too much padding. I believe that a more compact sidebar would be much nicer.

Before:

After:

CSS Changes

diff --git a/a/ui-kit.css b/b/ui-kit.css
index 502c45a..3cdab36 100644
--- a/a/ui-kit.css
+++ b/b/ui-kit.css
@@ -1986,7 +1986,7 @@ button.platform-tag:focus-visible {
   --hover-transition:background-color 200ms ease-in-out;
   --rotate-transition:transform 200ms ease-in-out;
   --toc-hover-color:var(--color-b08);
-  --toc-font:400 13px/24px var(--font-family-default);
+  --toc-font:400 12px/16px var(--font-family-default);
   --toc-color:var(--color-text);
 }
 
@@ -2015,7 +2015,6 @@ button.platform-tag:focus-visible {
 .toc--row {
   align-items: center;
   display: flex;
-  min-height: 40px;
   position: relative;
   -webkit-user-select: none;
   -moz-user-select: none;
@@ -2087,7 +2086,6 @@ button.platform-tag:focus-visible {
   box-sizing: border-box;
   color: inherit;
   height: calc(100% - 16px);
-  min-height: 40px;
   padding: 8px 4px 8px 0;
   width: 100%;
 }
@@ -2109,167 +2107,167 @@ button.platform-tag:focus-visible {
 
 .toc--part[data-nesting-level="0"] .toc--row > .toc--link:first-child {
   padding-left: 40px;
-  padding-left: calc(40px + var(--size-m1) * 0);
+  padding-left: calc(40px + var(--size-s2) * 0);
 }
 
 .toc--part[data-nesting-level="0"] .toc--button + .toc--link {
   margin-left: 40px;
-  margin-left: calc(40px + var(--size-m1) * 0);
+  margin-left: calc(40px + var(--size-s2) * 0);
 }
 
 .toc--part[data-nesting-level="0"] .toc--button {
   width: 40px;
-  width: calc(40px + var(--size-m1) * 0);
+  width: calc(40px + var(--size-s2) * 0);
 }
 
 .toc--part[data-nesting-level="1"] .toc--row > .toc--link:first-child {
   padding-left: 64px;
-  padding-left: calc(40px + var(--size-m1) * 1);
+  padding-left: calc(40px + var(--size-s2) * 1);
 }
 
 .toc--part[data-nesting-level="1"] .toc--button + .toc--link {
   margin-left: 64px;
-  margin-left: calc(40px + var(--size-m1) * 1);
+  margin-left: calc(40px + var(--size-s2) * 1);
 }
 
 .toc--part[data-nesting-level="1"] .toc--button {
   width: 64px;
-  width: calc(40px + var(--size-m1) * 1);
+  width: calc(40px + var(--size-s2) * 1);
 }
 
 .toc--part[data-nesting-level="2"] .toc--row > .toc--link:first-child {
   padding-left: 88px;
-  padding-left: calc(40px + var(--size-m1) * 2);
+  padding-left: calc(40px + var(--size-s2) * 2);
 }
 
 .toc--part[data-nesting-level="2"] .toc--button + .toc--link {
   margin-left: 88px;
-  margin-left: calc(40px + var(--size-m1) * 2);
+  margin-left: calc(40px + var(--size-s2) * 2);
 }
 
 .toc--part[data-nesting-level="2"] .toc--button {
   width: 88px;
-  width: calc(40px + var(--size-m1) * 2);
+  width: calc(40px + var(--size-s2) * 2);
 }
 
 .toc--part[data-nesting-level="3"] .toc--row > .toc--link:first-child {
   padding-left: 112px;
-  padding-left: calc(40px + var(--size-m1) * 3);
+  padding-left: calc(40px + var(--size-s2) * 3);
 }
 
 .toc--part[data-nesting-level="3"] .toc--button + .toc--link {
   margin-left: 112px;
-  margin-left: calc(40px + var(--size-m1) * 3);
+  margin-left: calc(40px + var(--size-s2) * 3);
 }
 
 .toc--part[data-nesting-level="3"] .toc--button {
   width: 112px;
-  width: calc(40px + var(--size-m1) * 3);
+  width: calc(40px + var(--size-s2) * 3);
 }
 
 .toc--part[data-nesting-level="4"] .toc--row > .toc--link:first-child {
   padding-left: 136px;
-  padding-left: calc(40px + var(--size-m1) * 4);
+  padding-left: calc(40px + var(--size-s2) * 4);
 }
 
 .toc--part[data-nesting-level="4"] .toc--button + .toc--link {
   margin-left: 136px;
-  margin-left: calc(40px + var(--size-m1) * 4);
+  margin-left: calc(40px + var(--size-s2) * 4);
 }
 
 .toc--part[data-nesting-level="4"] .toc--button {
   width: 136px;
-  width: calc(40px + var(--size-m1) * 4);
+  width: calc(40px + var(--size-s2) * 4);
 }
 
 .toc--part[data-nesting-level="5"] .toc--row > .toc--link:first-child {
   padding-left: 160px;
-  padding-left: calc(40px + var(--size-m1) * 5);
+  padding-left: calc(40px + var(--size-s2) * 5);
 }
 
 .toc--part[data-nesting-level="5"] .toc--button + .toc--link {
   margin-left: 160px;
-  margin-left: calc(40px + var(--size-m1) * 5);
+  margin-left: calc(40px + var(--size-s2) * 5);
 }
 
 .toc--part[data-nesting-level="5"] .toc--button {
   width: 160px;
-  width: calc(40px + var(--size-m1) * 5);
+  width: calc(40px + var(--size-s2) * 5);
 }
 
 .toc--part[data-nesting-level="6"] .toc--row > .toc--link:first-child {
   padding-left: 184px;
-  padding-left: calc(40px + var(--size-m1) * 6);
+  padding-left: calc(40px + var(--size-s2) * 6);
 }
 
 .toc--part[data-nesting-level="6"] .toc--button + .toc--link {
   margin-left: 184px;
-  margin-left: calc(40px + var(--size-m1) * 6);
+  margin-left: calc(40px + var(--size-s2) * 6);
 }
 
 .toc--part[data-nesting-level="6"] .toc--button {
   width: 184px;
-  width: calc(40px + var(--size-m1) * 6);
+  width: calc(40px + var(--size-s2) * 6);
 }
 
 .toc--part[data-nesting-level="7"] .toc--row > .toc--link:first-child {
   padding-left: 208px;
-  padding-left: calc(40px + var(--size-m1) * 7);
+  padding-left: calc(40px + var(--size-s2) * 7);
 }
 
 .toc--part[data-nesting-level="7"] .toc--button + .toc--link {
   margin-left: 208px;
-  margin-left: calc(40px + var(--size-m1) * 7);
+  margin-left: calc(40px + var(--size-s2) * 7);
 }
 
 .toc--part[data-nesting-level="7"] .toc--button {
   width: 208px;
-  width: calc(40px + var(--size-m1) * 7);
+  width: calc(40px + var(--size-s2) * 7);
 }
 
 .toc--part[data-nesting-level="8"] .toc--row > .toc--link:first-child {
   padding-left: 232px;
-  padding-left: calc(40px + var(--size-m1) * 8);
+  padding-left: calc(40px + var(--size-s2) * 8);
 }
 
 .toc--part[data-nesting-level="8"] .toc--button + .toc--link {
   margin-left: 232px;
-  margin-left: calc(40px + var(--size-m1) * 8);
+  margin-left: calc(40px + var(--size-s2) * 8);
 }
 
 .toc--part[data-nesting-level="8"] .toc--button {
   width: 232px;
-  width: calc(40px + var(--size-m1) * 8);
+  width: calc(40px + var(--size-s2) * 8);
 }
 
 .toc--part[data-nesting-level="9"] .toc--row > .toc--link:first-child {
   padding-left: 256px;
-  padding-left: calc(40px + var(--size-m1) * 9);
+  padding-left: calc(40px + var(--size-s2) * 9);
 }
 
 .toc--part[data-nesting-level="9"] .toc--button + .toc--link {
   margin-left: 256px;
-  margin-left: calc(40px + var(--size-m1) * 9);
+  margin-left: calc(40px + var(--size-s2) * 9);
 }
 
 .toc--part[data-nesting-level="9"] .toc--button {
   width: 256px;
-  width: calc(40px + var(--size-m1) * 9);
+  width: calc(40px + var(--size-s2) * 9);
 }
 
 .toc--part[data-nesting-level="10"] .toc--row > .toc--link:first-child {
   padding-left: 280px;
-  padding-left: calc(40px + var(--size-m1) * 10);
+  padding-left: calc(40px + var(--size-s2) * 10);
 }
 
 .toc--part[data-nesting-level="10"] .toc--button + .toc--link {
   margin-left: 280px;
-  margin-left: calc(40px + var(--size-m1) * 10);
+  margin-left: calc(40px + var(--size-s2) * 10);
 }
 
 .toc--part[data-nesting-level="10"] .toc--button {
   width: 280px;
-  width: calc(40px + var(--size-m1) * 10);
+  width: calc(40px + var(--size-s2) * 10);
 }
 
 .filtered > .toc--button, .toc .filtered > a {

Disable Codeblock Wrapping

Currently, codeblocks will wrap long lines, which I find to be unintuitive and not expected.

Before:

After:

Very simple change, which only requires the addition of the following:

.symbol:not(.token), code {
    overflow: scroll;
    white-space: pre;
}