mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-24 15:40:15 +01:00
138 lines
3.9 KiB
Markdown
138 lines
3.9 KiB
Markdown
---
|
||
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 minimal effort.
|
||
|
||
[1]: #additional-icons
|
||
|
||
## Configuration
|
||
|
||
### Logo
|
||
|
||
[:octicons-file-code-24: Source][2] ·
|
||
:octicons-milestone-24: Default: [`material/library`][3]
|
||
|
||
The _logo_ can be changed to a user-provided image (any type, incl. `*.png` and
|
||
`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
|
||
Add the following lines to `mkdocs.yml`:
|
||
|
||
=== "Image"
|
||
|
||
``` yaml
|
||
theme:
|
||
logo: assets/logo.png
|
||
```
|
||
|
||
=== "Icon, bundled"
|
||
|
||
``` yaml
|
||
theme:
|
||
icon:
|
||
logo: material/library
|
||
```
|
||
|
||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
|
||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg
|
||
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||
|
||
Normally, the logo in the header and sidebar links to the homepage of the
|
||
documentation, which is the same as `site_url`. This behavior can be changed
|
||
with the following configuration:
|
||
|
||
``` yaml
|
||
extra:
|
||
homepage: https://example.com
|
||
```
|
||
|
||
### Favicon
|
||
|
||
[:octicons-file-code-24: Source][5] ·
|
||
: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 via `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
theme:
|
||
favicon: images/favicon.png
|
||
```
|
||
|
||
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
|
||
|
||
### Icons
|
||
|
||
[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][6]
|
||
|
||
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
|
||
adds the ability to __integrate icons__ in the `*.svg` file format, which are
|
||
inlined 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]
|
||
- :octicons-mark-github-16: – [Octicons][11]
|
||
|
||
If you want to add [additional icons][1], read on.
|
||
|
||
[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][4] ·
|
||
:octicons-mortar-board-24: Difficulty: _easy_
|
||
|
||
In order to add additional icons, [extend the theme][12], and create a folder
|
||
named `.icons` in the [`custom_dir`][13] 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][14] icon set, and want to add it to
|
||
your project documentation. The structure of your project should look like this:
|
||
|
||
``` sh
|
||
.
|
||
├─ 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.
|
||
|
||
[12]: ../customization.md#extending-the-theme
|
||
[13]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
|
||
[14]: https://icons.getbootstrap.com/
|