Skip to content

ENH: Allow CSS variables to manipulate theme #190

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

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 all 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
50 changes: 47 additions & 3 deletions docs/user_guide/customizing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,57 @@
.. _customizing:

**********************
Customizing the layout
**********************
*********************
Customizing the theme
*********************

In addition to the configuration options detailed at :ref:`configuration`, it
is also possible to customize the HTML layout and CSS style of the theme.


Customizing the CSS
===================

The theme's CSS can be tweaked in 2 ways. The most straight forward way is to
change the theme variables. If you are looking for more customisation, you can
write additional css in ``custom.css``.

Theme variables
---------------

This theme is based on top of the basic
`Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`__
extended with some theme specific variables. An overview of all variables and
every default is defined in ``/pydata_sphinx_theme/static/css/theme.css``.

In order to change a variable, add a ``custom.css`` (see below) which updates
the value of certain variables in a ``:root`` section:

.. code-block:: none

:root {
--font-size-base: 17px;
}

Important, the theme is defined with CSS variables, not SASS variables!

Custom stylesheet
-----------------

If the theme variables are not sufficient to shape theme to you liking, you can
take full control over the look and feel via a custom stylesheet. If you have a
stylesheet in ``_static/css/custom.css``, adding the following to ``conf.py``
will ensure this stylesheet is loaded last on top of the theme variables and the
base styleheet:

.. code-block:: rst

html_static_path = ['_static']

html_css_files = [
'css/custom.css',
]


Replacing/Removing Fonts
========================

Expand Down
2 changes: 1 addition & 1 deletion ...ndex.73d71520a4ca3b99cfee5594769eaaae.css → ...ndex.867a4752765d7cafcde5c68b66309846.css
View file
Open in desktop

Large diffs are not rendered by default.

77 changes: 77 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,77 @@
:root {
/*****************************************************************************
* Font size
**/
--font-size-base: 15px; /* base font size - applied at body / html level */

/* heading font sizes */
--font-size-h1: 36px;
--font-size-h2: 32px;
--font-size-h3: 26px;
--font-size-h4: 21px;
--font-size-h5: 18px;
--font-size-h6: 16px;

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

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

/*****************************************************************************
* Color
*
* Colors are defined in rgb string way, "red, green, blue"
Copy link
Member

Choose a reason for hiding this comment

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

So if a user overrides those variables in their custom css, do they also always need to define the color as such a tuple?

Eg someone doing

:root {
  --color-primary: #333;
}

will work or not?

And related to my question below, the reason they are defined here as r, g, b, is that to make things like rgba(var(--color-sidebar-link-hover), 1) work? (if that is indeed the reason, a clarifying comment here might be helpful)

Copy link
Contributor

Choose a reason for hiding this comment

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

As long as the custom CSS is added after the theme's CSS, it'll work. :)

**/
--color-primary: 19, 6, 84;
Copy link
Contributor

Choose a reason for hiding this comment

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

OOOOO. It's soooo hacky, that I like it. XD

--color-success: 40, 167, 69;
--color-info: 23, 162, 184;
--color-warning: 255, 193, 7;
--color-danger: 220, 53, 69;
--color-text-base: 51, 51, 51;
--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: 0, 91, 129;
--color-link-hover: 227, 46, 0;
--color-headerlink: 198, 15, 15;
--color-headerlink-hover: 255, 255, 255;
--color-preformatted-text: 34, 34, 34;
--color-preformatted-background: 250, 250, 250;

--color-active-navigation: 19, 6, 84;
--color-navbar-link: 77, 77, 77;
--color-navbar-link-hover: var(--color-active-navigation);
--color-navbar-link-active: var(--color-active-navigation);
--color-sidebar-link: 77, 77, 77;
--color-sidebar-link-hover: var(--color-active-navigation);
--color-sidebar-link-active: var(--color-active-navigation);
--color-toc-link: 119, 117, 122;
--color-toc-link-hover: var(--color-active-navigation);
--color-toc-link-active: var(--color-active-navigation);

--color-admonition-primary: var(--color-primary);
--color-admonition-success: var(--color-success);
--color-admonition-danger: var(--color-danger);
--color-admonition-warning: var(--color-warning);
--color-admonition-info: var(--color-info);

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

/* font awesome icons*/
--icon-check-circle: '\f058';
--icon-info-circle: '\f05a';
--icon-exclamation-triangle: '\f071';
--icon-exclamation-circle: '\f06a';
--icon-times-circle: '\f057';
--icon-lightbulb: '\f0eb';
}
0 ...e/static/js/index.3da636dd464baa7582d2.js → ...e/static/js/index.c8075258343c02e88109.js
View file
Open in desktop
File renamed without changes.
7 changes: 4 additions & 3 deletions pydata_sphinx_theme/static/webpack-macros.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,14 @@
{% endmacro %}

{% macro head_pre_bootstrap() %}
<link rel="stylesheet" href="{{ pathto('_static/css/index.73d71520a4ca3b99cfee5594769eaaae.css', 1) }}">
<link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet" />
<link href="{{ pathto('_static/css/index.867a4752765d7cafcde5c68b66309846.css', 1) }}" rel="stylesheet" />
{% endmacro %}

{% macro head_js_preload() %}
<link rel="preload" as="script" href="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}">
<link rel="preload" as="script" href="{{ pathto('_static/js/index.c8075258343c02e88109.js', 1) }}">
{% endmacro %}

{% macro body_post() %}
<script src="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}"></script>
<script src="{{ pathto('_static/js/index.c8075258343c02e88109.js', 1) }}"></script>
{% endmacro %}
99 changes: 51 additions & 48 deletions src/scss/_admonitions.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
// Admonitions CSS originally inspired by https://squidfunk.github.io/mkdocs-material/getting-started/

.admonition {
margin: 1.5625em auto;
padding: 0 .6rem .8rem .6rem !important;
padding: 0 0.6rem 0.8rem 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;
border-color: rgba(var(--color-admonition-primary), 1);
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 item should have no spacing since we'll control that w/ padding
*:last-child {
Expand All @@ -28,19 +31,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: rgba(var(--color-admonition-primary), 1);
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 @@ -50,109 +53,109 @@
}

&.attention {
border-color: $orange;
border-color: rgba(var(--color-admonition-warning), 1);
.admonition-title {
background-color: $orange-light;
background-color: rgba(var(--color-admonition-warning), 0.1);
Copy link
Member

Choose a reason for hiding this comment

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

Nice! Is this the reason that the colors need to be defined as a RGB tuple?

Copy link
Collaborator Author

@hoetmaaiers hoetmaaiers Jul 8, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

The RGB tuple is the required argument for the rgba() function. This is the downside of not defining the light variants of colours but doing this dynamically.


&:before {
color: $orange;
content: $icon-exclamation-circle;
color: rgba(var(--color-admonition-warning), 1);
content: var(--icon-exclamation-circle);
}
}
}

&.caution {
border-color: $orange;
border-color: rgba(var(--color-admonition-warning), 1);
.admonition-title {
background-color: $orange-light;
background-color: rgba(var(--color-admonition-warning), 0.1);

&:before {
color: $orange;
content: $icon-exclamation-triangle;
color: rgba(var(--color-admonition-warning), 1);
content: var(--icon-exclamation-triangle);
}
}
}

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

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

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

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

&.error {
border-color: $red;
border-color: rgba(var(--color-admonition-danger), 1);
.admonition-title {
background-color: $red-light;
background-color: rgba(var(--color-admonition-danger), 0.1);

&:before {
color: $red;
content: $icon-times-circle;
color: rgba(var(--color-admonition-danger), 1);
content: var(--icon-times-circle);
}
}
}

&.hint {
border-color: $yellow;
border-color: rgba(var(--color-admonition-warning), 1);
.admonition-title {
background-color: $yellow-light;
background-color: rgba(var(--color-admonition-warning), 0.1);

&:before {
color: $yellow;
content: $icon-lightbulb;
color: rgba(var(--color-admonition-warning), 1);
content: var(--icon-lightbulb);
}
}
}

&.tip {
border-color: $yellow;
border-color: rgba(var(--color-admonition-info), 1);
.admonition-title {
background-color: $yellow-light;
background-color: rgba(var(--color-admonition-info), 0.1);

&:before {
color: $yellow;
content: $icon-lightbulb;
color: rgba(var(--color-admonition-info), 1);
content: var(--icon-lightbulb);
}
}
}

&.important {
border-color: $blue;
border-color: rgba(var(--color-admonition-info), 1);
.admonition-title {
background-color: $blue-light;
background-color: rgba(var(--color-admonition-info), 0.1);

&:before {
color: $blue;
content: $icon-exclamation-circle;
color: rgba(var(--color-admonition-info), 1);
content: var(--icon-exclamation-circle);
}
}
}

&.note {
border-color: $blue;
border-color: rgba(var(--color-admonition-info), 1);
.admonition-title {
background-color: $blue-light;
background-color: rgba(var(--color-admonition-info), 0.1);

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