From 78402da2efc341bcdf1ed1faed4ab37613bd20ac Mon Sep 17 00:00:00 2001 From: squidfunk Date: Tue, 21 Jul 2020 18:39:27 +0200 Subject: [PATCH] Added guide on custom icon integration --- docs/creating-your-site.md | 1 + docs/setup/changing-the-colors.md | 4 +- docs/setup/changing-the-fonts.md | 21 +--- docs/setup/changing-the-logo-and-icons.md | 131 +++++++++++++++++++++- 4 files changed, 139 insertions(+), 18 deletions(-) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 7414f567e..67b8fe70e 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -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 diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 4ca3b26ff..1f62841da 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -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_ diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index 318cdc405..914ad0178 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -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: "", -apple-system, Helvetica, Arial, sans-serif; - } - ``` - -=== "Code blocks" +=== "Proportional font" ``` css pre, code, kbd { diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md index 6497c8d5f..fe0f819c6 100644 --- a/docs/setup/changing-the-logo-and-icons.md +++ b/docs/setup/changing-the-logo-and-icons.md @@ -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/