1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-22 20:36:02 +01:00
mkdocs-material/docs/setup/changing-the-logo-and-icons.md
2023-07-06 16:57:01 +02:00

169 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 8,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] with minimal effort.
[additional icons]: #additional-icons
## Configuration
### Logo
[:octicons-tag-24: 0.1.0][Logo support] ·
:octicons-milestone-24: Default: :material-library: `material/library`
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`:
=== ":octicons-image-16: Image"
``` yaml
theme:
logo: assets/logo.png
```
=== ":octicons-package-16: Icon, bundled"
``` yaml
theme:
icon:
logo: material/library # (1)!
```
1. Enter a few keywords to find the perfect icon using our [icon search] and
click on the shortcode to copy it to your clipboard:
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
<input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material library" />
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
<div class="mdx-iconsearch-result__meta"></div>
<ol class="mdx-iconsearch-result__list"></ol>
</div>
</div>
[Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[icon search]: ../reference/icons-emojis.md#search
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-tag-24: 0.1.0][Favicon support] ·
:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
The favicon can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
``` yaml
theme:
favicon: images/favicon.png
```
[Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
### Site icons
[:octicons-tag-24: 9.2.0][Site icon support]
Most icons you see on your site, such as navigation icons, can also be changed. For example,
to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
```yaml
theme:
icon:
previous: fontawesome/solid/angle-left
next: fontawesome/solid/angle-right
```
The following is a complete list of customizable icons used by the theme:
| Icon name | Purpose |
|:-------------|:------------------------------------------------------------------------------|
| `logo` | See [Logo](#logo) |
| `menu` | Open drawer |
| `alternate` | Change language |
| `search` | Search icon |
| `share` | Share search |
| `close` | Reset search, dismiss announcements |
| `top` | Back-to-top button |
| `edit` | Edit current page |
| `view` | View page source |
| `repo` | Repository icon |
| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons) |
| `tag` | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
| `previous` | Previous page in footer, hide search on mobile |
| `next` | Next page in footer |
[Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
## Customization
### Additional icons
In order to use custom icons, [extend the theme] and create a new folder named
`.icons` in the [`custom_dir`][custom_dir] 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] icon set, and want to add it to
your project documentation. The structure of your project should look like this:
``` { .sh .no-copy }
.
├─ 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 can now use all :fontawesome-brands-bootstrap: Bootstrap icons anywhere in
Markdown files, as well as everywhere icons can be used in `mkdocs.yml`.
However, note that the syntaxes are slightly different:
- __Using icons in configuration__: take the path of the `*.svg` icon file
starting at the `.icons` folder and drop the file extension, e.g. for
`.icons/bootstrap/envelope-paper.svg`, use:
``` yaml
theme:
icon:
logo: bootstrap/envelope-paper
```
- __Using icons in Markdown files__: additionally to taking the path from the
`.icons` folder as noted above, replace all `/` with `-` and enclose the icon
shortcode in two colons:
```
:bootstrap-envelope-paper:
```
For further notes on icon usage, please consult the [icon reference].
[extend the theme]: ../customization.md#extending-the-theme
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[Bootstrap]: https://icons.getbootstrap.com/
[icon reference]: ../reference/icons-emojis.md#using-icons