Skip to content

Commit

Permalink
Reorganize some Sass variables to make theming easier (#1258)
Browse files Browse the repository at this point in the history 
* Reorganize some SCSS variables to allow theming

Also, use DocumenterTools 0.1.5 for theme testing.

* Add CHANGELOG, bump version to 0.24.6
  • Loading branch information
@mortenpi
mortenpi authored Mar 12, 2020
1 parent 00a4593 commit b8ef3f7
Show file tree
Hide file tree
Showing 11 changed files with 69 additions and 148 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Documenter.jl changelog

## Version `v0.24.6`

* ![Enhancement][badge-enhancement] Reorganize some of the internal variables in Documenter's Sass sources, to make it easier to create custom themes on top of the Documenter base theme. ([#1258][github-1258])

## Version `v0.24.5`

* ![Enhancement][badge-enhancement] ![Bugfix][badge-bugfix] Documenter now correctly emulates the "REPL softscope" (Julia 1.5) in REPL-style doctest blocks and `@repl` blocks. ([#1232][github-1232])
Expand Down Expand Up @@ -513,6 +517,7 @@
[github-1222]: https://github.com/JuliaDocs/Documenter.jl/pull/1222
[github-1223]: https://github.com/JuliaDocs/Documenter.jl/pull/1223
[github-1232]: https://github.com/JuliaDocs/Documenter.jl/pull/1232
[github-1258]: https://github.com/JuliaDocs/Documenter.jl/pull/1258

[documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
[documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl
Expand Down
2 changes: 1 addition & 1 deletion Project.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name = "Documenter"
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
version = "0.24.5"
version = "0.24.6"

[deps]
Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
Expand Down
25 changes: 18 additions & 7 deletions assets/html/scss/documenter/_overrides.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,32 @@
// Hence the need to override this variable.
// $navbar-breakpoint: $tablet !default;

$documenter-sidebar-size: $size-normal !default;
$documenter-sidebar-submenu-size: 0.95*$documenter-sidebar-size !default;
$documenter-sidebar-menu-chevron-size: 0.75*$documenter-sidebar-size !default;
$documenter-sidebar-menu-active-size: 0.85*$documenter-sidebar-size !default;

$documenter-sidebar-title-width: 0.9 * $documenter-sidebar-width !default;
$documenter-sidebar-menu-padding: 1rem !default;
$documenter-sidebar-title-font-size: $size-large !default;

// The coloring of the sidebar works as follows:
// - by default, everything gets $documenter-sidebar-color/background
// - clickable menu items also get a :hover color with $documenter-sidebar-menu-hover-*
// - the in-page ("active") links get a different color/background with
// $documenter-sidebar-menu-active-*, and the clickable in-page links also get their
// own :hover colors with $documenter-sidebar-menu-active-hover-*
$documenter-sidebar-background: $background !default;
$documenter-sidebar-color: invert($documenter-sidebar-background) !default;

$documenter-sidebar-scrollbar-color: darken-color($documenter-sidebar-background, 1) !default;
$documenter-sidebar-scrollbar-color-hover: darken-color($documenter-sidebar-background, 2) !default;

$documenter-sidebar-menu-border: darken-color($border, 1) !default;

$documenter-sidebar-menu-hover-background: darken-color($documenter-sidebar-background, 0.5) !default;
$documenter-sidebar-menu-hover-color: $documenter-sidebar-color !default;
$documenter-sidebar-menu-active-background: lighten-color($documenter-sidebar-background, 0.5) !default;
$documenter-sidebar-menu-active-color: $documenter-sidebar-color !default;
$documenter-sidebar-menu-active-hover-background: darken-color($documenter-sidebar-background, 0.5) !default;
$documenter-sidebar-menu-active-hover-color: $documenter-sidebar-menu-active-color !default;

$documenter-sidebar-menu-hover-background: darken-color($documenter-sidebar-background, 0.5) !default;
$documenter-sidebar-scrollbar-color: darken-color($documenter-sidebar-background, 1) !default;
$documenter-sidebar-scrollbar-color-hover: darken-color($documenter-sidebar-background, 2) !default;

$breadcrumb-item-disabled-color: $text-strong !default;

Expand All @@ -28,3 +38,4 @@ $content-pre-padding: 0.7rem 0.5rem !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;
2 changes: 1 addition & 1 deletion assets/html/scss/documenter/_variables.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ $code: #000000 !default;
// The inline <code> tags get rendered on various different backgrounds. Therefore, in order
// to make sure it always renders nicely, we'll just use transparent black color to make the
// background of the <code> elements slightly darker.
$code-background: rgba(0, 0, 0, 0.05);
$code-background: rgba(0, 0, 0, 0.05) !default;
$code-padding: 0.1em;

$documenter-docstring-background: transparent !default;
Expand Down
2 changes: 1 addition & 1 deletion assets/html/scss/documenter/components/_admonition.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ $admonition-header-color: () !default;
padding: $message-body-padding;

pre {
background-color: $background;
background-color: $pre-background;
}

code {
Expand Down
2 changes: 1 addition & 1 deletion assets/html/scss/documenter/components/_docstring.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
align-items: stretch;
padding: $card-header-padding;

background-color: $background;
background-color: $documenter-docstring-header-background;
box-shadow: $card-header-shadow;
box-shadow: none;
border-bottom: 1px solid $border;
Expand Down
38 changes: 23 additions & 15 deletions assets/html/scss/documenter/layout/_sidebar.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
flex: 0 0 $documenter-sidebar-width;
z-index: 5; // make sure it's on top of the main body and top bar

font-size: $documenter-sidebar-size;

// This is mobile-first, so our default state is that the sidebar is hidden away left
// of the screen.
position: fixed;
Expand Down Expand Up @@ -83,29 +85,21 @@
// item
user-select: none;

font-size: $size-normal;
border-top: 1px solid $border;
// background-color: $background;

padding-bottom: 1.5rem;

// First level items
> li {
// padding-left: 0.5em;
> .tocitem {
font-weight: bold;
}
}

// Second and lower
> li li {
font-size: 0.95*$size-normal;
font-size: $documenter-sidebar-submenu-size;
margin-left: 1em;
border-left: 1px solid $border;

&.is-active {
// margin-left: 0;
}
}

/* Managing collapsible submenus */
Expand Down Expand Up @@ -133,7 +127,7 @@
text-rendering: auto;
line-height: 1;

font-size: 0.75*$size-normal;
font-size: $documenter-sidebar-menu-chevron-size;
margin-left: 1rem;
margin-top: auto;
margin-bottom: auto;
Expand All @@ -151,28 +145,42 @@
display: block;
padding: 0.5rem 0.5rem;

// We'll force all .tocitems to have the sidebar colors. This is to override any
// higher-level defaults, such as when the .tocitem is in an <a> tag. We'll also make
// sure that they do not display any :hover behaviour by default.
&, &:hover {
color: $documenter-sidebar-color;
background: $documenter-sidebar-background;
}
}

// If the .tocitem is in an <a> or <label> tags (latter used for collapsible submenus),
// we'll apply special :hover styling to highlight them to the user as they move the
// mouse over the menu.
a, label {
&.tocitem:hover {
color: $documenter-sidebar-menu-hover-color;
background-color: $documenter-sidebar-menu-hover-background;
}
}

// The in-page links for the current page are wrapped in a li.is-active element.
li.is-active {
border-top: 1px solid $documenter-sidebar-menu-border;
border-top: 1px solid $border;
border-bottom: 1px solid $border;
background-color: $documenter-sidebar-menu-active-background;

> .tocitem {
// The background color for li.is-active is different, so we also need to make sure
// that the .tocitems match. We'll disable :hover for them too.
.tocitem {
&, &:hover {
background-color: $documenter-sidebar-menu-active-background;
color: $documenter-sidebar-menu-active-color;
}
}
// The .tocitems of the in-page links should also have a :hover styling:
ul.internal .tocitem:hover {
background-color: $documenter-sidebar-menu-active-hover-background;
color: $documenter-sidebar-menu-active-hover-color;
}
}

// The main ul.docs-menu already has a border-top, so we do not want to duplicate it
Expand All @@ -186,7 +194,7 @@
margin: 0 0.5rem 0.5rem;
border-top: 1px solid $border;
li {
font-size: 0.85*$size-normal;
font-size: $documenter-sidebar-menu-active-size;
border-left: none;
margin-left: 0;
margin-top: 0.5rem;
Expand Down
13 changes: 9 additions & 4 deletions assets/html/themes/documenter-dark.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7401,6 +7401,7 @@ html.theme--documenter-dark {
padding: 0;
flex: 0 0 18rem;
z-index: 5;
font-size: 15px;
position: fixed;
left: -18rem;
width: 18rem;
Expand Down Expand Up @@ -7442,7 +7443,6 @@ html.theme--documenter-dark {
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu {
flex-grow: 1;
user-select: none;
font-size: 15px;
border-top: 1px solid #5e6d6f;
padding-bottom: 1.5rem;
/* Managing collapsible submenus */ }
Expand Down Expand Up @@ -7482,16 +7482,21 @@ html.theme--documenter-dark {
display: block;
padding: 0.5rem 0.5rem; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem, html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover {
color: #fff; }
color: #fff;
background: #282f2f; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover, html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover {
color: #fff;
background-color: #32393a; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active {
border-top: 1px solid #718385;
border-top: 1px solid #5e6d6f;
border-bottom: 1px solid #5e6d6f;
background-color: #1f2424; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active > .tocitem, html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active > .tocitem:hover {
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem, html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover {
background-color: #1f2424;
color: #fff; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover {
background-color: #32393a;
color: #fff; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu > li.is-active:first-child {
border-top: none; }
html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal {
Expand Down
13 changes: 9 additions & 4 deletions assets/html/themes/documenter-light.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7383,6 +7383,7 @@ html {
padding: 0;
flex: 0 0 18rem;
z-index: 5;
font-size: 1rem;
position: fixed;
left: -18rem;
width: 18rem;
Expand Down Expand Up @@ -7424,7 +7425,6 @@ html {
#documenter .docs-sidebar ul.docs-menu {
flex-grow: 1;
user-select: none;
font-size: 1rem;
border-top: 1px solid #dbdbdb;
padding-bottom: 1.5rem;
/* Managing collapsible submenus */ }
Expand Down Expand Up @@ -7464,16 +7464,21 @@ html {
display: block;
padding: 0.5rem 0.5rem; }
#documenter .docs-sidebar ul.docs-menu .tocitem, #documenter .docs-sidebar ul.docs-menu .tocitem:hover {
color: #0a0a0a; }
color: #0a0a0a;
background: whitesmoke; }
#documenter .docs-sidebar ul.docs-menu a.tocitem:hover, #documenter .docs-sidebar ul.docs-menu label.tocitem:hover {
color: #0a0a0a;
background-color: #ebebeb; }
#documenter .docs-sidebar ul.docs-menu li.is-active {
border-top: 1px solid #c7c7c7;
border-top: 1px solid #dbdbdb;
border-bottom: 1px solid #dbdbdb;
background-color: white; }
#documenter .docs-sidebar ul.docs-menu li.is-active > .tocitem, #documenter .docs-sidebar ul.docs-menu li.is-active > .tocitem:hover {
#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem, #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover {
background-color: white;
color: #0a0a0a; }
#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover {
background-color: #ebebeb;
color: #0a0a0a; }
#documenter .docs-sidebar ul.docs-menu > li.is-active:first-child {
border-top: none; }
#documenter .docs-sidebar ul.docs-menu ul.internal {
Expand Down
113 changes: 0 additions & 113 deletions test/themes/Manifest.toml
View file

This file was deleted.

Loading

2 comments on commit b8ef3f7

@mortenpi
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator register

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/10856

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if Julia TagBot is installed, or can be done manually through the github interface, or via:

git tag -a v0.24.6 -m "<description of version>" b8ef3f7bbd6715f940d14c153bcafe87b92cdcbd
git push origin v0.24.6

Please sign in to comment.