Skip to content

Commit ce4712d

Browse files
hoetmaaiersjorisvandenbossche
hoetmaaiers
and
jorisvandenbossche
authored
ENH: Allow CSS variables to manipulate theme (#190)
Co-authored-by: Robin Houdmeyers <[email protected]> Co-authored-by: Joris Van den Bossche <[email protected]>
1 parent 348c482 commit ce4712d

13 files changed

+259
-133
lines changed

‎docs/user_guide/customizing.rst

+47-3
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,57 @@
11
.. _customizing:
22

3-
**********************
4-
Customizing the layout
5-
**********************
3+
*********************
4+
Customizing the theme
5+
*********************
66

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

1010

11+
Customizing the CSS
12+
===================
13+
14+
The theme's CSS can be tweaked in 2 ways. The most straight forward way is to
15+
change the theme variables. If you are looking for more customisation, you can
16+
write additional css in ``custom.css``.
17+
18+
Theme variables
19+
---------------
20+
21+
This theme is based on top of the basic
22+
`Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`__
23+
extended with some theme specific variables. An overview of all variables and
24+
every default is defined in ``/pydata_sphinx_theme/static/css/theme.css``.
25+
26+
In order to change a variable, add a ``custom.css`` (see below) which updates
27+
the value of certain variables in a ``:root`` section:
28+
29+
.. code-block:: none
30+
31+
:root {
32+
--font-size-base: 17px;
33+
}
34+
35+
Important, the theme is defined with CSS variables, not SASS variables!
36+
37+
Custom stylesheet
38+
-----------------
39+
40+
If the theme variables are not sufficient to shape theme to you liking, you can
41+
take full control over the look and feel via a custom stylesheet. If you have a
42+
stylesheet in ``_static/css/custom.css``, adding the following to ``conf.py``
43+
will ensure this stylesheet is loaded last on top of the theme variables and the
44+
base styleheet:
45+
46+
.. code-block:: rst
47+
48+
html_static_path = ['_static']
49+
50+
html_css_files = [
51+
'css/custom.css',
52+
]
53+
54+
1155
Replacing/Removing Fonts
1256
========================
1357

‎pydata_sphinx_theme/static/css/index.73d71520a4ca3b99cfee5594769eaaae.css renamed to ‎pydata_sphinx_theme/static/css/index.867a4752765d7cafcde5c68b66309846.css

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pydata_sphinx_theme/static/css/theme.css

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
:root {
2+
/*****************************************************************************
3+
* Font size
4+
**/
5+
--font-size-base: 15px; /* base font size - applied at body / html level */
6+
7+
/* heading font sizes */
8+
--font-size-h1: 36px;
9+
--font-size-h2: 32px;
10+
--font-size-h3: 26px;
11+
--font-size-h4: 21px;
12+
--font-size-h5: 18px;
13+
--font-size-h6: 16px;
14+
15+
/* smaller then heading font sizes*/
16+
--font-size-milli: 12px;
17+
18+
/*****************************************************************************
19+
* Font family
20+
**/
21+
--font-family-base: 'Lato', sans-serif;
22+
--font-family-heading: 'Open Sans', sans-serif;
23+
24+
/*****************************************************************************
25+
* Color
26+
*
27+
* Colors are defined in rgb string way, "red, green, blue"
28+
**/
29+
--color-primary: 19, 6, 84;
30+
--color-success: 40, 167, 69;
31+
--color-info: 23, 162, 184;
32+
--color-warning: 255, 193, 7;
33+
--color-danger: 220, 53, 69;
34+
--color-text-base: 51, 51, 51;
35+
--color-h1: var(--color-primary);
36+
--color-h2: var(--color-primary);
37+
--color-h3: var(--color-text-base);
38+
--color-h4: var(--color-text-base);
39+
--color-h5: var(--color-text-base);
40+
--color-h6: var(--color-text-base);
41+
--color-paragraph: var(--color-text-base);
42+
--color-link: 0, 91, 129;
43+
--color-link-hover: 227, 46, 0;
44+
--color-headerlink: 198, 15, 15;
45+
--color-headerlink-hover: 255, 255, 255;
46+
--color-preformatted-text: 34, 34, 34;
47+
--color-preformatted-background: 250, 250, 250;
48+
49+
--color-active-navigation: 19, 6, 84;
50+
--color-navbar-link: 77, 77, 77;
51+
--color-navbar-link-hover: var(--color-active-navigation);
52+
--color-navbar-link-active: var(--color-active-navigation);
53+
--color-sidebar-link: 77, 77, 77;
54+
--color-sidebar-link-hover: var(--color-active-navigation);
55+
--color-sidebar-link-active: var(--color-active-navigation);
56+
--color-toc-link: 119, 117, 122;
57+
--color-toc-link-hover: var(--color-active-navigation);
58+
--color-toc-link-active: var(--color-active-navigation);
59+
60+
--color-admonition-primary: var(--color-primary);
61+
--color-admonition-success: var(--color-success);
62+
--color-admonition-danger: var(--color-danger);
63+
--color-admonition-warning: var(--color-warning);
64+
--color-admonition-info: var(--color-info);
65+
66+
/*****************************************************************************
67+
* Icon
68+
**/
69+
70+
/* font awesome icons*/
71+
--icon-check-circle: '\f058';
72+
--icon-info-circle: '\f05a';
73+
--icon-exclamation-triangle: '\f071';
74+
--icon-exclamation-circle: '\f06a';
75+
--icon-times-circle: '\f057';
76+
--icon-lightbulb: '\f0eb';
77+
}

‎pydata_sphinx_theme/static/js/index.3da636dd464baa7582d2.js renamed to ‎pydata_sphinx_theme/static/js/index.c8075258343c02e88109.js

File renamed without changes.

‎pydata_sphinx_theme/static/webpack-macros.html

+4-3
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@
1616
{% endmacro %}
1717

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

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

2627
{% macro body_post() %}
27-
<script src="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}"></script>
28+
<script src="{{ pathto('_static/js/index.c8075258343c02e88109.js', 1) }}"></script>
2829
{% endmacro %}

‎src/scss/_admonitions.scss

+51-48
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1-
// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
1+
// Admonitions CSS originally inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
2+
23
.admonition {
34
margin: 1.5625em auto;
4-
padding: 0 .6rem .8rem .6rem !important;
5+
padding: 0 0.6rem 0.8rem 0.6rem !important;
56
overflow: hidden;
67
page-break-inside: avoid;
7-
border-left: .2rem solid $blue;
8-
border-radius: .1rem;
9-
box-shadow: 0 0.2rem 0.5rem rgba(0,0,0,.05), 0 0 0.05rem rgba(0,0,0,.1);
10-
transition: color 250ms,background-color 250ms,border-color 250ms;
8+
border-left: 0.2rem solid;
9+
border-color: rgba(var(--color-admonition-primary), 1);
10+
border-radius: 0.1rem;
11+
box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05),
12+
0 0 0.05rem rgba(0, 0, 0, 0.1);
13+
transition: color 250ms, background-color 250ms, border-color 250ms;
1114

1215
// Last item should have no spacing since we'll control that w/ padding
1316
*:last-child {
@@ -28,19 +31,19 @@
2831
.admonition-title {
2932
position: relative;
3033
margin: 0 -0.6rem !important;
31-
padding: .4rem .6rem .4rem 2rem;
34+
padding: 0.4rem 0.6rem 0.4rem 2rem;
3235
font-weight: 700;
33-
background-color: rgba(68,138,255,.1);
36+
background-color: rgba(68, 138, 255, 0.1);
3437

3538
&:before {
3639
position: absolute;
37-
left: .6rem;
40+
left: 0.6rem;
3841
width: 1rem;
3942
height: 1rem;
40-
color: $blue;
41-
font-family: "Font Awesome 5 Free";
43+
color: rgba(var(--color-admonition-primary), 1);
44+
font-family: 'Font Awesome 5 Free';
4245
font-weight: 900;
43-
content: $icon-info-circle; /* info-circle */
46+
content: var(--icon-info-circle);
4447
}
4548

4649
// Next element after title needs some extra upper-space
@@ -50,109 +53,109 @@
5053
}
5154

5255
&.attention {
53-
border-color: $orange;
56+
border-color: rgba(var(--color-admonition-warning), 1);
5457
.admonition-title {
55-
background-color: $orange-light;
58+
background-color: rgba(var(--color-admonition-warning), 0.1);
5659

5760
&:before {
58-
color: $orange;
59-
content: $icon-exclamation-circle;
61+
color: rgba(var(--color-admonition-warning), 1);
62+
content: var(--icon-exclamation-circle);
6063
}
6164
}
6265
}
6366

6467
&.caution {
65-
border-color: $orange;
68+
border-color: rgba(var(--color-admonition-warning), 1);
6669
.admonition-title {
67-
background-color: $orange-light;
70+
background-color: rgba(var(--color-admonition-warning), 0.1);
6871

6972
&:before {
70-
color: $orange;
71-
content: $icon-exclamation-triangle;
73+
color: rgba(var(--color-admonition-warning), 1);
74+
content: var(--icon-exclamation-triangle);
7275
}
7376
}
7477
}
7578

7679
&.warning {
77-
border-color: $red;
80+
border-color: rgba(var(--color-admonition-warning), 1);
7881
.admonition-title {
79-
background-color: $red-light;
82+
background-color: rgba(var(--color-admonition-warning), 0.1);
8083

8184
&:before {
82-
color: $red;
83-
content: $icon-exclamation-triangle;
85+
color: rgba(var(--color-admonition-warning), 1);
86+
content: var(--icon-exclamation-triangle);
8487
}
8588
}
8689
}
8790

8891
&.danger {
89-
border-color: $red;
92+
border-color: rgba(var(--color-admonition-danger), 1);
9093
.admonition-title {
91-
background-color: $red-light;
94+
background-color: rgba(var(--color-admonition-danger), 0.1);
9295

9396
&:before {
94-
color: $red;
95-
content: $icon-exclamation-triangle;
97+
color: rgba(var(--color-admonition-danger), 1);
98+
content: var(--icon-exclamation-triangle);
9699
}
97100
}
98101
}
99102

100103
&.error {
101-
border-color: $red;
104+
border-color: rgba(var(--color-admonition-danger), 1);
102105
.admonition-title {
103-
background-color: $red-light;
106+
background-color: rgba(var(--color-admonition-danger), 0.1);
104107

105108
&:before {
106-
color: $red;
107-
content: $icon-times-circle;
109+
color: rgba(var(--color-admonition-danger), 1);
110+
content: var(--icon-times-circle);
108111
}
109112
}
110113
}
111114

112115
&.hint {
113-
border-color: $yellow;
116+
border-color: rgba(var(--color-admonition-warning), 1);
114117
.admonition-title {
115-
background-color: $yellow-light;
118+
background-color: rgba(var(--color-admonition-warning), 0.1);
116119

117120
&:before {
118-
color: $yellow;
119-
content: $icon-lightbulb;
121+
color: rgba(var(--color-admonition-warning), 1);
122+
content: var(--icon-lightbulb);
120123
}
121124
}
122125
}
123126

124127
&.tip {
125-
border-color: $yellow;
128+
border-color: rgba(var(--color-admonition-info), 1);
126129
.admonition-title {
127-
background-color: $yellow-light;
130+
background-color: rgba(var(--color-admonition-info), 0.1);
128131

129132
&:before {
130-
color: $yellow;
131-
content: $icon-lightbulb;
133+
color: rgba(var(--color-admonition-info), 1);
134+
content: var(--icon-lightbulb);
132135
}
133136
}
134137
}
135138

136139
&.important {
137-
border-color: $blue;
140+
border-color: rgba(var(--color-admonition-info), 1);
138141
.admonition-title {
139-
background-color: $blue-light;
142+
background-color: rgba(var(--color-admonition-info), 0.1);
140143

141144
&:before {
142-
color: $blue;
143-
content: $icon-exclamation-circle;
145+
color: rgba(var(--color-admonition-info), 1);
146+
content: var(--icon-exclamation-circle);
144147
}
145148
}
146149
}
147150

148151
&.note {
149-
border-color: $blue;
152+
border-color: rgba(var(--color-admonition-info), 1);
150153
.admonition-title {
151-
background-color: $blue-light;
154+
background-color: rgba(var(--color-admonition-info), 0.1);
152155

153156
&:before {
154-
color: $blue;
155-
content: $icon-info-circle;
157+
color: rgba(var(--color-admonition-info), 1);
158+
content: var(--icon-info-circle);
156159
}
157160
}
158161
}

0 commit comments

Comments
 (0)