1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-22 12:25:56 +01:00
mkdocs-material/docs/setup/changing-the-logo-and-icons.md
2023-09-21 18:56:35 +02:00

167 lines
6.1 KiB
Markdown

# 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
<!-- md:version 0.1.0 -->
<!-- md:default `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>
[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
<!-- md:version 0.1.0 -->
<!-- md: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 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:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.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