Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Allow CSS variables to manipulate theme #190

Merged
merged 29 commits into from
Oct 20, 2020
Merged

ENH: Allow CSS variables to manipulate theme #190

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
1aaaefd
Add variables to manipulate theme
hoetmaaiers May 29, 2020
c239050
Move custom font import to theme
hoetmaaiers May 29, 2020
c4148c4
Move custom font import outside :root scope
hoetmaaiers May 29, 2020
aa92528
Add container-max-widths
hoetmaaiers May 29, 2020
c3f3f84
Add theming documentation
hoetmaaiers Jun 22, 2020
f116d60
Apply theming via theme.css & custom.css
hoetmaaiers Jun 22, 2020
185c2cf
Theme link color in sidebar and toc
hoetmaaiers Jun 22, 2020
7f4892d
Define all theme colors in "red, green, blue" style.
hoetmaaiers Jun 22, 2020
e15dffe
Merge branch 'master' into feature/style-by-variable
hoetmaaiers Jul 7, 2020
8ddd977
Merge remote-tracking branch 'upstream/master' into feature/style-by-…
jorisvandenbossche Aug 22, 2020
222e14e
fix admonition left border
jorisvandenbossche Aug 22, 2020
e32c826
add variables for navbar links
jorisvandenbossche Aug 22, 2020
a156644
fix active link selector in sidebar
jorisvandenbossche Aug 28, 2020
f8d70e3
fix use of rgba around color variables
jorisvandenbossche Aug 28, 2020
c7a5e65
fix em + use lighter grey for sidebar
jorisvandenbossche Aug 28, 2020
811e134
add back CleanWebpackPlugin plugin, but exclude theme.css
jorisvandenbossche Aug 28, 2020
d2b7d88
Merge remote-tracking branch 'upstream/master' into feature/style-by-…
jorisvandenbossche Sep 23, 2020
d04e6c5
Merge remote-tracking branch 'upstream/master' into feature/style-by-…
jorisvandenbossche Sep 23, 2020
0f25c1b
revert some unrelated changes
jorisvandenbossche Sep 23, 2020
8cac2e9
remove custom.css file included in package
jorisvandenbossche Sep 26, 2020
30eba8a
revert test bright blue primary color
jorisvandenbossche Sep 26, 2020
b3c61a7
clean-up custom.css in webpack
jorisvandenbossche Sep 26, 2020
a04d97c
fixup
jorisvandenbossche Sep 26, 2020
146129e
Merge remote-tracking branch 'upstream/master' into feature/style-by-…
jorisvandenbossche Oct 20, 2020
3ab8f06
rebuild after merge
jorisvandenbossche Oct 20, 2020
130af5b
revert change in line-height + whitespace in template
jorisvandenbossche Oct 20, 2020
8edd3ab
correct docs
jorisvandenbossche Oct 20, 2020
facbf8e
fix deprecated box
jorisvandenbossche Oct 20, 2020
6d7c351
fix rst
jorisvandenbossche Oct 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion pydata_sphinx_theme/layout.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@

{%- block css %}
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/all.min.css" integrity="sha384-KA6wR/X5RY4zFAHpv/CnoG2UW1uogYfdnP67Uv7eULvTveboZJg0qUpmJZb5VqzN" crossorigin="anonymous">
<link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet">
<link href="{{ pathto('_static/css/index.css', 1) }}" rel="stylesheet">
{{- css() }}
{%- endblock %}
Expand Down Expand Up @@ -89,4 +90,4 @@

{%- block footer %}
{%- include "footer.html" %}
{%- endblock %}
{%- endblock %}
4 changes: 2 additions & 2 deletions pydata_sphinx_theme/static/css/index.css
View file
Open in desktop

Large diffs are not rendered by default.

85 changes: 85 additions & 0 deletions pydata_sphinx_theme/static/css/theme.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
:root {
/*****************************************************************************
* Bootstrap variables are availlable:
* https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables
**/

/*****************************************************************************
* Custom font
**/
@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,100;0,300;0,400;0,700;0,900;1,100;1,300;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,300;0,400;0,600;0,700;0,800;1,300;1,400;1,600;1,700;1,800&display=swap');

/*****************************************************************************
* Font size
**/
--fs-base: 15px; /* base font size - applied at body / html level */

/* heading font sizes */
--fs-h1: 36px;
Copy link
Member

Choose a reason for hiding this comment

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

Should we make those relative (em) sizes?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

we could make those relative, but since we allow this to be defined in a 'setting', defining via em is harder to think about. Since 1em == --fs-base. Since mostly no inheritance happend on heading level, defining in pixels or ems is little difference I think.

--fs-h2: 32px;
--fs-h3: 26px;
--fs-h4: 21px;
--fs-h5: 28px;
Copy link
Member

Choose a reason for hiding this comment

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

this seems a typo? (28 doesn't really fit between 21 and 18 ;))

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

yes indeed!

--fs-h6: 18px;

/* smaller then heading font sizes*/
--fs-milli: 12px;

/*****************************************************************************
* Font family
**/
--ff-base: 'Lato', sans-serif;
--ff-heading: 'Open Sans', sans-serif;

/*****************************************************************************
* Color
**/
--color-primary: #130654;
--color-text-base: #333;
--color-h1: var(--color-primary);
--color-h2: var(--color-primary);
--color-h3: var(--color-text-base);
--color-h4: var(--color-text-base);
--color-h5: var(--color-text-base);
--color-h6: var(--color-text-base);
--color-paragraph: var(--color-text-base);
--color-link: #005b81;
--color-link-hover: #e32e00;
--color-headerlink: #c60f0f;
--color-headerlink-hover: white;
--color-preformatted-text: #222;
--color-preformatted-background: #fafafa;

/* admonition colors */
--color-admonition-base: var(--blue);
--color-admonition-attention: var(--orange);
--color-admonition-attention-light: #ffedcc;
Copy link
Member

Choose a reason for hiding this comment

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

I am not sure we need to necessarily add variables for all of those admonition types (we can always add later if there is demand for it). Maybe we could keep it on the 4 colors we use now.

What I was originally thinking for those admonitions is to reuse the bootstrap success, danger, warning, info variables.
The problem though is that we also need the "-light" version, and that doesn't seem fully straightforward. Eg I found https://codyhouse.co/blog/post/how-to-combine-sass-color-functions-and-css-variables, that has a way to allow something like lightness(var(--color-primary), 1.2)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Limit the admonition types is fine for me, semantics in css are not that important I think.

Regarding the *-light variant, this possible for sure, it could be looked upon as a clear theme choice.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I diggel into the sass color functions combined with css variables. All solutions available start from defining the colors either based in RGB (e.g. red: 255, 0, 0) or HSL (e.g red: 0%, 100%, 50%.

With RBG, it is possible to lighten a color by adding an alpha channel. Darkening the color is harder I think.
HSL provides more flexibility.

The main disadvantage is the theme colors MUST be defined in either RGB, HSL and never Hex. Somehow this feels like a downside for the theme user who quickly wants to define his/her theme colors on top?

@jorisvandenbossche @choldgraf do you have thoughts on this?

--color-admonition-caution: var(--orange);
--color-admonition-caution-light: #ffedcc;
--color-admonition-warning: var(--red);
--color-admonition-warning-light: #fdf3f2;
--color-admonition-danger: var(--red);
--color-admonition-danger-light: #fdf3f2;
--color-admonition-error: var(--red);
--color-admonition-error-light: #fdf3f2;
--color-admonition-hint: var(--yellow);
--color-admonition-hint-light: #fff6dd;
--color-admonition-tip: var(--yellow);
--color-admonition-tip-light: #fff6dd;
--color-admonition-important: var(--blue);
--color-admonition-important-light: #e7f2fa;
--color-admonition-note: var(--blue);
--color-admonition-note-light: #e7f2fa;

/*****************************************************************************
* Icon
**/

/* font awesome icons*/
--icon-info-circle: '\f05a';
--icon-exclamation-circle: '\f06a';
--icon-lightbulb: '\f0eb';
--icon-question: '\f128';
--icon-exclamation-triangle: '\f071';
--icon-times-circle: '\f057';
}
95 changes: 48 additions & 47 deletions src/scss/_admonitions.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
.admonition {
margin: 1.5625em 0 !important;
padding: 0 .6rem !important;
padding: 0 0.6rem !important;
overflow: hidden;
page-break-inside: avoid;
border-left: .2rem solid $blue;
border-radius: .1rem;
box-shadow: 0 0.2rem 0.5rem rgba(0,0,0,.05), 0 0 0.05rem rgba(0,0,0,.1);
transition: color 250ms,background-color 250ms,border-color 250ms;
border-left: 0.2rem solid var(--color-admonition-base);
border-radius: 0.1rem;
box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05),
0 0 0.05rem rgba(0, 0, 0, 0.1);
transition: color 250ms, background-color 250ms, border-color 250ms;

// Last paragraph should have same spacing as title
p:last-child {
Expand All @@ -18,19 +19,19 @@
.admonition-title {
position: relative;
margin: 0 -0.6rem !important;
padding: .4rem .6rem .4rem 2rem;
padding: 0.4rem 0.6rem 0.4rem 2rem;
font-weight: 700;
background-color: rgba(68,138,255,.1);
background-color: rgba(68, 138, 255, 0.1);

&:before {
position: absolute;
left: .6rem;
left: 0.6rem;
width: 1rem;
height: 1rem;
color: $blue;
font-family: "Font Awesome 5 Free";
color: var(--color-admonition-base);
font-family: 'Font Awesome 5 Free';
font-weight: 900;
content: $icon-info-circle; /* info-circle */
content: var(--icon-info-circle);
}

// Next element after title needs some extra upper-space
Expand All @@ -40,109 +41,109 @@
}

&.attention {
border-color: $orange;
border-color: var(--color-admonition-attention);
.admonition-title {
background-color: $orange-light;
background-color: var(--color-admonition-attention-light);

&:before {
color: $orange;
content: $icon-exclamation-circle;
color: var(--color-admonition-attention);
content: var(--icon-exclamation-circle);
}
}
}

&.caution {
border-color: $orange;
border-color: var(--color-admonition-caution);
.admonition-title {
background-color: $orange-light;
border-color: var(--color-admonition-caution-light);

&:before {
color: $orange;
content: $icon-exclamation-triangle;
color: var(--color-admonition-caution);
content: var(--icon-exclamation-triangle);
}
}
}

&.warning {
border-color: $red;
border-color: var(--color-admonition-warning);
.admonition-title {
background-color: $red-light;
background-color: var(--color-admonition-warning-light);

&:before {
color: $red;
content: $icon-exclamation-triangle;
color: var(--color-admonition-warning);
content: var(--icon-exclamation-triangle);
}
}
}

&.danger {
border-color: $red;
border-color: var(--color-admonition-danger);
.admonition-title {
background-color: $red-light;
background-color: var(--color-admonition-danger-light);

&:before {
color: $red;
content: $icon-exclamation-triangle;
color: var(--color-admonition-danger);
content: var(--icon-exclamation-triangle);
}
}
}

&.error {
border-color: $red;
border-color: var(--color-admonition-error);
.admonition-title {
background-color: $red-light;
background-color: var(--color-admonition-error-light);

&:before {
color: $red;
content: $icon-times-circle;
color: var(--color-admonition-error);
content: var(--icon-times-circle);
}
}
}

&.hint {
border-color: $yellow;
border-color: var(--color-admonition-hint);
.admonition-title {
background-color: $yellow-light;
background-color: var(--color-admonition-hint-light);

&:before {
color: $yellow;
content: $icon-lightbulb;
color: var(--color-admonition-hint);
content: var(--icon-lightbulb);
}
}
}

&.tip {
border-color: $yellow;
border-color: var(--color-admonition-tip);
.admonition-title {
background-color: $yellow-light;
background-color: var(--color-admonition-tip-light);

&:before {
color: $yellow;
content: $icon-lightbulb;
color: var(--color-admonition-tip);
content: var(--icon-lightbulb);
}
}
}

&.important {
border-color: $blue;
border-color: var(--color-admonition-important);
.admonition-title {
background-color: $blue-light;
background-color: var(--color-admonition-important-light);

&:before {
color: $blue;
content: $icon-exclamation-circle;
color: var(--color-admonition-important);
content: var(--icon-exclamation-circle);
}
}
}

&.note {
border-color: $blue;
border-color: var(--color-admonition-note);
.admonition-title {
background-color: $blue-light;
background-color: var(--color-admonition-note-light);

&:before {
color: $blue;
content: $icon-info-circle;
color: var(--color-admonition-note);
content: var(--icon-info-circle);
}
}
}
Expand Down
Loading