mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Added guide on custom icon integration
This commit is contained in:
parent
8f2b10fad5
commit
78402da2ef
@ -29,6 +29,7 @@ If you're running Material for MkDocs from within Docker, use:
|
||||
This will create the following structure:
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs/
|
||||
│ └─ index.md
|
||||
└─ mkdocs.yml
|
||||
|
@ -10,7 +10,7 @@ Google's original [color palette][1], which can be easily configured through
|
||||
fit your brand's identity by using [CSS variables][2].
|
||||
|
||||
[1]: http://www.materialui.co/colors
|
||||
[2]: #customization
|
||||
[2]: #custom-colors
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -184,7 +184,7 @@ color:
|
||||
|
||||
## Customization
|
||||
|
||||
### Brand colors
|
||||
### Custom colors
|
||||
|
||||
[:octicons-file-code-24: Source][6] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
@ -58,10 +58,10 @@ If you want to load fonts from other destinations or don't want to use Google
|
||||
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
|
||||
font loading as described below.
|
||||
|
||||
### Disable font loading
|
||||
### Disabling font loading
|
||||
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
:octicons-mortar-board-24: Difficulty: _none_
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
If you want to prevent typefaces from being loaded from Google Fonts and fall
|
||||
back to system fonts, add the following lines to `mkdocs.yml`:
|
||||
@ -87,11 +87,10 @@ corresponding `@font-face` definition:
|
||||
}
|
||||
```
|
||||
|
||||
The font can then be configured to be used globally as the regular or
|
||||
proportional font, or limited to be used for specific elements only, e.g.
|
||||
headlines:
|
||||
The font can then be applied to specific elements, e.g. only headlines, or
|
||||
globally to be used as the site-wide regular or proportional font:
|
||||
|
||||
=== "Body copy"
|
||||
=== "Regular font"
|
||||
|
||||
``` css
|
||||
body, input {
|
||||
@ -99,15 +98,7 @@ headlines:
|
||||
}
|
||||
```
|
||||
|
||||
=== "Headlines"
|
||||
|
||||
``` css
|
||||
.md-typeset h1 {
|
||||
font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
|
||||
}
|
||||
```
|
||||
|
||||
=== "Code blocks"
|
||||
=== "Proportional font"
|
||||
|
||||
``` css
|
||||
pre, code, kbd {
|
||||
|
@ -1 +1,130 @@
|
||||
Icons are all inlined!
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Changing the logo and icons
|
||||
|
||||
When installing Material for MkDocs, you immediately get access to _over 7.000
|
||||
icons_ ready to be used for customization of specific parts of the theme and/or
|
||||
when writing your documentation in Markdown. Not enough? You can also [add
|
||||
additional icons][1] with very little effort.
|
||||
|
||||
[1]: #additional-icons
|
||||
|
||||
## Configuration
|
||||
|
||||
### Logo
|
||||
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
:octicons-milestone-24: Default: `material/library`
|
||||
|
||||
There're two ways to specify a _logo_: it must be a valid path to [any icon
|
||||
bundled with the theme][3], or to a user-provided image located in the `docs`
|
||||
folder. Both can be set from `mkdocs.yml`:
|
||||
|
||||
=== "Icon"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
logo: material/library
|
||||
```
|
||||
|
||||
=== "Image"
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
logo: assets/logo.png
|
||||
```
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
### Favicon
|
||||
|
||||
[:octicons-file-code-24: Source][4] ·
|
||||
:octicons-milestone-24: Default: `assets/images/favicon.png`
|
||||
|
||||
The _favicon_ can be changed to a path pointing to a user-provided image, which
|
||||
must be located in the `docs` folder. It can be set from `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
favicon: images/favicon.png
|
||||
```
|
||||
|
||||
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L71
|
||||
|
||||
### Emoji (icons)
|
||||
|
||||
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
|
||||
|
||||
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
|
||||
adds the ability to __integrate custom icons__ in the `*.svg` file format,
|
||||
which are inlined into the HTML when [building your site][8]:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
||||
```
|
||||
|
||||
The following icon sets are bundled with Material for MkDocs:
|
||||
|
||||
* :material-material-design: – [Material Design][9]
|
||||
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
|
||||
* :fontawesome-brands-github: – [Octicons][11]
|
||||
|
||||
If you want to add [additional icons][1], read on.
|
||||
|
||||
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_emoji.scss
|
||||
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/
|
||||
[8]: ../creating-your-site.md#building-your-site
|
||||
[9]: https://materialdesignicons.com/
|
||||
[10]: https://fontawesome.com/icons?d=gallery&m=free
|
||||
[11]: https://octicons.github.com/
|
||||
|
||||
## Customization
|
||||
|
||||
### Additional icons
|
||||
|
||||
[:octicons-file-code-24: Source][3] ·
|
||||
:octicons-mortar-board-24: Difficulty: _moderate_
|
||||
|
||||
In order to add additional icons, [extend the theme][13] and create a folder
|
||||
named `.icons` in the [`custom_dir`][14] you want to use for overrides. Next,
|
||||
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
|
||||
downloaded and unpacked the [Bootstrap][15] icon set, and want to add it to
|
||||
your project documentation. The structure of your project should look like this:
|
||||
|
||||
``` sh
|
||||
.
|
||||
├─ docs/
|
||||
│ └─ index.md
|
||||
├─ overrides/
|
||||
│ └─ .icons/
|
||||
│ └─ bootstrap/
|
||||
│ └─ *.svg
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
||||
options:
|
||||
custom_icons:
|
||||
- overrides/.icons
|
||||
```
|
||||
|
||||
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
|
||||
icons.
|
||||
|
||||
[13]: ../customization.md#extending-the-theme
|
||||
[14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
|
||||
[15]: https://icons.getbootstrap.com/
|
||||
|
Loading…
Reference in New Issue
Block a user