8000 Improved color setup guide · squidfunk/mkdocs-material@4247e3b · GitHub
[go: up one dir, main page]
Skip to content

Commit 4247e3b

Browse files
squidfunksquidfunk
committed
Improved color setup guide
1 parent 2e60bca commit 4247e3b

File tree

3 files changed

+63
-74
lines changed

3 files changed

+63
-74
lines changed

‎docs/assets/screenshots/palette-toggle-default.png

-133 KB
Binary file not shown.

‎docs/assets/screenshots/palette-toggle-slate.png

-134 KB
Binary file not shown.

‎docs/setup/changing-the-colors.md

Lines changed: 63 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ _Click on a tile to change the primary color_:
9797
button.addEventListener("click", function() {
9898
var attr = this.getAttribute("data-md-color-primary")
9999
document.body.setAttribute("data-md-color-primary", attr)
100-
var name = document.querySelector("#__code_2 code span:nth-child(7)")
100+
var name = document.querySelector("#__code_1 code span:nth-child(7)")
101101
name.textContent = attr.replace("-", " ")
102102
})
103103
})
@@ -153,85 +153,42 @@ _Click on a tile to change the accent color_:
153153
button.addEventListener("click", function() {
154154
var attr = this.getAttribute("data-md-color-accent")
155155
document.body.setAttribute("data-md-color-accent", attr)
156-
var name = document.querySelector("#__code_3 code span:nth-child(7)")
156+
var name = document.querySelector("#__code_2 code span:nth-child(7)")
157157
name.textContent = attr.replace("-", " ")
158158
})
159159
})
160160
</script>
161161

162162
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
163163

164-
---
165-
166-
!!! warning "Accessibility – not all color combinations work well"
167-
168-
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
169-
= __714__ combinations, it's impossible to ensure that all configurations
170-
provide a good user experience (e.g. _yellow on light background_). Make
171-
sure that the color combination of your choosing provides enough contrast
172-
and tweak CSS variables where necessary.
173-
174164
### Color palette toggle
175165

176-
It's also possible to add multiple color palettes, including a [scheme][8],
177-
[primary][9] and [accent][10] color each, and let the user choose. A color
178-
palette toggle can be added via `mkdocs.yml`:
166+
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
179167

180-
``` yaml
168+
It's also possible to offer a list of color palettes to the user, each of which
169+
can include a [`scheme`][7], [`primary`][8] and [`accent`][9] color each. The
170+
user can toggle between those color palettes:
171+
172+
``` yaml hl_lines="4-6 8-10"
181173
theme:
182174
palette:
183-
184-
# Light mode
185-
- media: "(prefers-color-scheme: light)"
186-
scheme: default
187-
primary: indigo
188-
accent: indigo
175+
- scheme: default
189176
toggle:
190177
icon: material/toggle-switch-off-outline
191178
name: Switch to dark mode
192-
193-
# Dark mode
194-
- media: "(prefers-color-scheme: dark)"
195-
scheme: slate
196-
primary: blue
197-
accent: blue
179+
- scheme: slate
198180
toggle:
199181
icon: material/toggle-switch
200182
name: Switch to light mode
201183
```
202184

203-
In order to set a default theme based on user preference, add a valid media
204-
query to the `media` attribute. This will render a color palette toggle in the
205-
header next to the search bar:
206-
207-
208-
<figure markdown="1">
209-
210-
=== "Light mode"
211-
212-
[![Light mode][11]][11]
213-
214-
=== "Dark mode"
215-
216-
[![Dark mode][12]][12]
217-
218-
<figcaption markdown="1" style="margin-top: -2.0rem">
219-
220-
A demo is worth a thousand words — check it out at
221-
[squidfunk.github.io/mkdocs-material-insiders][7]
222-
223-
</figcaption>
224-
</figure>
225-
226-
The `toggle` field allows to specify an `icon` and `name` for each palette. The
227-
toggle is rendered next to the search bar and will cycle through all defined
228-
color palettes:
185+
The following fields must be set for each toggle:
229186

230187
`icon`{ #icon }
231188

232189
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
233190
This field must point to a valid icon path referencing [any icon bundled
234-
with the theme][13], or the build will not succeed. Some popular
191+
with the theme][10], or the build will not succeed. Some popular
235192
combinations:
236193

237194
* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
@@ -245,25 +202,57 @@ color palettes:
245202
This field is used as the toggle's `title` attribute and should be set to a
246203
discernable name to improve accessibility.
247204

248-
[6]: ../insiders/index.md
249-
[7]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors
250-
[8]: #color-scheme
251-
[9]: #primary-color
252-
[10]: #accent-color
253-
[11]: ../assets/screenshots/palette-toggle-default.png
254-
[12]: ../assets/screenshots/palette-toggle-slate.png
255-
[13]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
205+
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/header.html
206+
[7]: #color-scheme
207+
[8]: #primary-color
208+
[9]: #accent-color
209+
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
210+
211+
### System preference
212+
213+
[:octicons-file-code-24: Source][6] · :octicons-milestone-24: Default: _none_
214+
215+
In order to automatically set the color palette to the user's system preference,
216+
a media query can be set as part of the `media` field next to the toggle
217+
definition in `mkdocs.yml`:
218+
219+
``` yaml hl_lines="3 8"
220+
theme:
221+
palette:
222+
- media: "(prefers-color-scheme: light)"
223+
scheme: default
224+
toggle:
225+
icon: material/toggle-switch-off-outline
226+
name: Switch to dark mode
227+
- media: "(prefers-color-scheme: dark)"
228+
scheme: slate
229+
toggle:
230+
icon: material/toggle-switch
231+
name: Switch to light mode
232+
```
233+
234+
When the user first visits your site, the media queries are evaluated in the
235+
order of their definition. The first media query that matches selects the
236+
default color palette.
237+
238+
!!! warning "Accessibility – not all color combinations work well"
239+
240+
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
241+
= __714__ combinations, it's impossible to ensure that all configurations
242+
provide a good user experience (e.g. _yellow on light background_). Make
243+
sure that the color combination of your choosing provides enough contrast
244+
and tweak CSS variables where necessary.
256245

257246
## Customization
258247

259248
### Custom colors
260249

261-
[:octicons-file-code-24: Source][14] ·
250+
[:octicons-file-code-24: Source][11] ·
262251
:octicons-mortar-board-24: Difficulty: _easy_
263252

264-
Material for MkDocs implements colors using [CSS variables][15] (custom
253+
Material for MkDocs implements colors using [CSS variables][12] (custom
265254
properties). If you want to customize the colors beyond the palette (e.g. to
266-
use your brand-specific colors), you can add an [additional stylesheet][16] and
255+
use your brand-specific colors), you can add an [additional stylesheet][13] and
267256
tweak the values of the CSS variables.
268257

269258
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
@@ -278,23 +267,23 @@ add:
278267
}
279268
```
280269

281-
See the file containing the [color definitions][14] for a list of all CSS
270+
See the file containing the [color definitions][11] for a list of all CSS
282271
variables.
283272

284-
[14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
285-
[15]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
286-
[16]: ../customization.md#additional-css
273+
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
274+
[12]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
275+
[13]: ../customization.md#additional-css
287276

288277

289278
### Custom color schemes
290279

291-
[:octicons-file-code-24: Source][14] ·
280+
[:octicons-file-code-24: Source][11] ·
292281
:octicons-mortar-board-24: Difficulty: _easy_
293282

294283
Besides overriding specific colors, you can create your own, named color scheme
295284
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
296-
[attribute selector][17], which you can then set via `mkdocs.yml` as described
297-
in the [color schemes][8] section:
285+
[attribute selector][14], which you can then set via `mkdocs.yml` as described
286+
62D8 in the [color schemes][7] section:
298287

299288
``` css
300289
[data-md-color-scheme="youtube"] {
@@ -314,4 +303,4 @@ can tune the `slate` theme with:
314303
}
315304
```
316305

317-
[17]: https://www.w3.org/TR/selectors-4/#attribute-selectors
306+
[14]: https://www.w3.org/TR/selectors-4/#attribute-selectors

0 commit comments

Comments
 (0)
0