diff --git a/docs/assets/guides/creating-your-site.png b/docs/assets/creating-your-site.png similarity index 100% rename from docs/assets/guides/creating-your-site.png rename to docs/assets/creating-your-site.png diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 903d0e5b8..7414f567e 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -63,32 +63,32 @@ Material for MkDocs comes with a lot of configuration options. The _guides_ section explains in great detail how to configure and customize colors, fonts, icons and much more: -* [Changing colors][3] +* [Changing the colors][3] * [Changing the fonts][4] * [Changing the language][5] -* [Setting up navigation][6] -* [Setting up site search][7] -* [Adding a git repository][8] -* [Adding icons and emojis][9] -* [Adding footer links][10] +* [Changing the logo and icons][6] +* [Setting up navigation][7] +* [Setting up site search][8] +* [Adding a git repository][9] +* [Adding social links][10] * [Adding site analytics][11] * [Adding a comment system][12] * [Adding an announcement bar][13] -* [Adding a landing page][14] + [2]: getting-started.md#installation - [3]: guides/changing-colors.md - [4]: guides/changing-the-fonts.md - [5]: guides/changing-the-language.md - [6]: guides/setting-up-navigation.md - [7]: guides/setting-up-site-search.md - [8]: guides/adding-a-git-repository.md - [9]: guides/adding-icons-and-emojis.md - [10]: guides/adding-footer-links.md - [11]: guides/adding-site-analytics.md - [12]: guides/adding-a-comment-system.md - [13]: guides/adding-an-announcement-bar.md - [14]: guides/adding-a-landing-page.md + [3]: setup/changing-the-colors.md + [4]: setup/changing-the-fonts.md + [5]: setup/changing-the-language.md + [6]: setup/changing-the-logo-and-icons.md + [7]: setup/setting-up-navigation.md + [8]: setup/setting-up-site-search.md + [9]: setup/adding-a-git-repository.md + [10]: setup/adding-social-links.md + [11]: setup/adding-site-analytics.md + [12]: setup/adding-a-comment-system.md + [13]: setup/adding-an-announcement-bar.md + ## Previewing as you write @@ -119,7 +119,7 @@ Point your browser to [localhost:8000][15] and you should see: [![Creating your site][16]][15] [15]: http://localhost:8000 - [16]: assets/guides/creating-your-site.png + [16]: assets/creating-your-site.png ## Building your site diff --git a/docs/data-privacy.md b/docs/data-privacy.md index e5956fbaf..42e070806 100644 --- a/docs/data-privacy.md +++ b/docs/data-privacy.md @@ -30,7 +30,7 @@ Neue__ and __Monaco__ with their corresponding fall backs, relying on system fonts. You can easily include your own, self-hosted webfont by [overriding][4] the `fonts` block. - [2]: guides/changing-the-fonts.md + [2]: setup/changing-the-fonts.md [3]: https://github.com/google/fonts/issues/1495 [4]: customization.md#overriding-blocks diff --git a/docs/guides/adding-footer-links.md b/docs/guides/adding-footer-links.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/guides/adding-icons-and-emojis.md b/docs/guides/adding-icons-and-emojis.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 41ea1008e..58efa14a1 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -24,7 +24,7 @@ configuring syntax highlighting of code blocks: `use_pygments` -: :octicons-milestone-24: Default: `true` · This option allows to control +: :octicons-milestone-24: Default: `true` – This option allows to control whether highlighting should be carried out during build time by [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the necessary [additional stylesheets][6] and [JavaScript][7] if you want to @@ -73,7 +73,7 @@ configuring syntax highlighting of code blocks: `linenums` -: :octicons-milestone-24: Default: `false` · This option will add line numbers +: :octicons-milestone-24: Default: `false` – This option will add line numbers to _all_ code blocks. If you wish to add line numbers to _some_, but not all code blocks, consult the section on [adding line numbers][10] later in this document, which also contains some tips on working with line numbers: @@ -86,7 +86,7 @@ configuring syntax highlighting of code blocks: `linenums_style` -: :octicons-milestone-24: Default: `table` · The Highlight extension provides +: :octicons-milestone-24: Default: `table` – The Highlight extension provides three ways to add line numbers, all of which are supported by Material for MkDocs. While `table` wraps a code block in a table, `inline` and `pymdownx.inline` render line numbers as part of the line itself: diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md index d0f5e4865..f4f251ef6 100644 --- a/docs/reference/content-tabs.md +++ b/docs/reference/content-tabs.md @@ -26,6 +26,22 @@ markdown_extensions: [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ [3]: https://facelessuser.github.io/pymdown-extensions/ +### SuperFences + +[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5] + +The [SuperFences][5] extension, which is also part of [Python Markdown +Extensions][3], allows for the __nesting of code blocks inside tabs__, and is +therefore strongly recommended: + +``` yaml +markdown_extensions: + - pymdownx.superfences +``` + + [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss + [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ + ## Usage ### Grouping code blocks @@ -123,7 +139,7 @@ _Result_: ### Embedded content Content tabs can contain arbitrary nested content, including further content -tabs, and can be nested in other blocks like [admonitions][4], [details][5] or +tabs, and can be nested in other blocks like [admonitions][6], [details][7] or blockquotes: _Example_: @@ -200,5 +216,5 @@ _Result_: 2. Donec vitae suscipit est 3. Nulla tempor lobortis orci - [4]: admonitions.md - [5]: admonitions.md#details + [6]: admonitions.md + [7]: admonitions.md#details diff --git a/docs/guides/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md similarity index 100% rename from docs/guides/adding-a-comment-system.md rename to docs/setup/adding-a-comment-system.md diff --git a/docs/guides/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md similarity index 79% rename from docs/guides/adding-a-git-repository.md rename to docs/setup/adding-a-git-repository.md index 7963eabad..067d210e0 100644 --- a/docs/guides/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -57,17 +57,18 @@ theme: repo: fontawesome/brands/git-alt ``` -Some popular repository icons: +Some popular choices: -- :fontawesome-brands-git: – `:fontawesome-brands-git:` -- :fontawesome-brands-git-square: – `:fontawesome-brands-git-square:` -- :fontawesome-brands-github: – `:fontawesome-brands-github:` -- :fontawesome-brands-github-alt: – `:fontawesome-brands-github-alt:` -- :fontawesome-brands-github-square: – `:fontawesome-brands-github-square:` -- :fontawesome-brands-gitlab: – `:fontawesome-brands-gitlab:` -- :fontawesome-brands-gitkraken: – `:fontawesome-brands-gitkraken:` -- :fontawesome-brands-bitbucket: – `:fontawesome-brands-bitbucket:` -- :fontawesome-solid-trash: – `:fontawesome-solid-trash:` +- :fontawesome-brands-git: – `fontawesome/brands/git` +- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt` +- :fontawesome-brands-git-square: – `fontawesome/brands/git-square` +- :fontawesome-brands-github: – `fontawesome/brands/github` +- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt` +- :fontawesome-brands-github-square: – `fontawesome/brands/github-square` +- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab` +- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken` +- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket` +- :fontawesome-solid-trash: – `fontawesome/solid/trash` [4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons diff --git a/docs/guides/adding-a-landing-page.md b/docs/setup/adding-a-landing-page.md similarity index 100% rename from docs/guides/adding-a-landing-page.md rename to docs/setup/adding-a-landing-page.md diff --git a/docs/guides/adding-an-announcement-bar.md b/docs/setup/adding-an-announcement-bar.md similarity index 100% rename from docs/guides/adding-an-announcement-bar.md rename to docs/setup/adding-an-announcement-bar.md diff --git a/docs/guides/adding-site-analytics.md b/docs/setup/adding-site-analytics.md similarity index 100% rename from docs/guides/adding-site-analytics.md rename to docs/setup/adding-site-analytics.md diff --git a/docs/setup/adding-social-links.md b/docs/setup/adding-social-links.md new file mode 100644 index 000000000..6456a4f36 --- /dev/null +++ b/docs/setup/adding-social-links.md @@ -0,0 +1,88 @@ +--- +template: overrides/main.html +--- + +# Adding social links + +The footer of your project documentation is a good place to add links to +websites or platforms you or your company are using as additional marketing +channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" }, +:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or +:fontawesome-brands-facebook:{: style="color: #3B5998" }, which can be +configured through `mkdocs.yml`. + +## Configuration + +[:octicons-file-code-24: Source][1] · +:octicons-milestone-24: Default: _none_ + +All _social links_ are rendered next to the copyright information as part of the +footer of your project documentation. Add a list of social links in `mkdocs.yml` +with: + +``` yaml +extra: + social: + - icon: fontawesome/brands/twitter + link: https://twitter.com/squidfunk +``` + +For each entry, the following fields are available: + +`icon` + +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – + This field must point to a valid icon path referencing [any icon bundled + with the theme][2], or the build will not succeed. Some popular choices: + + - :fontawesome-brands-behance: – `fontawesome/brands/behance` + - :fontawesome-brands-docker: – `fontawesome/brands/docker` + - :fontawesome-brands-github: – `fontawesome/brands/github` + - :fontawesome-brands-instagram: – `fontawesome/brands/instagram` + - :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin` + - :fontawesome-brands-medium: – `fontawesome/brands/medium` + - :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt` + - :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt` + - :fontawesome-brands-slack: – `fontawesome/brands/slack` + - :fontawesome-brands-twitter: – `fontawesome/brands/twitter` + + [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html + [2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons + +`link` + +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – + This field must contain a valid relative or absolute URL including the URI + scheme. All URI schemes are supported, including `mailto` and `bitcoin`: + + === "Twitter" + + ``` yaml + extra: + social: + - icon: fontawesome/brands/twitter + link: https://twitter.com/squidfunk + ``` + + === "Email address" + + ``` yaml + extra: + social: + - icon: fontawesome/solid/paper-plane + link: mailto:martin.donath@squidfunk.com + ``` + +`name` + +: :octicons-milestone-24: Default: _domain name from_ `link`, if available – + This field is used as the link's `title` attribute and can be set to a + discernable name to improve accessibility: + + ``` yaml + extra: + social: + - icon: fontawesome/brands/twitter + link: https://twitter.com/squidfunk + name: squidfunk on Twitter + ``` diff --git a/docs/guides/changing-colors.md b/docs/setup/changing-the-colors.md similarity index 98% rename from docs/guides/changing-colors.md rename to docs/setup/changing-the-colors.md index 4f28c6ff6..4ca3b26ff 100644 --- a/docs/guides/changing-colors.md +++ b/docs/setup/changing-the-colors.md @@ -2,7 +2,7 @@ template: overrides/main.html --- -# Changing colors +# Changing the colors As any good Material Design implementation, Material for MkDocs supports Google's original [color palette][1], which can be easily configured through @@ -49,8 +49,8 @@ scheme: The _color scheme_ can also be set based on _user preference_, which makes use -of the `prefers-color-scheme` media query. This can be done by adding the -following to `mkdocs.yml`: +of the `prefers-color-scheme` media query, by setting the value in `mkdocs.yml` +to `preference`: ``` yaml theme: @@ -184,8 +184,10 @@ color: ## Customization +### Brand colors + [:octicons-file-code-24: Source][6] · -:octicons-mortar-board-24: Difficulty: easy +:octicons-mortar-board-24: Difficulty: _easy_ Material for MkDocs implements colors using [CSS variables][7] (custom properties). If you want to customize the colors beyond the palette (e.g. to diff --git a/docs/guides/changing-the-fonts.md b/docs/setup/changing-the-fonts.md similarity index 67% rename from docs/guides/changing-the-fonts.md rename to docs/setup/changing-the-fonts.md index 981afc970..318cdc405 100644 --- a/docs/guides/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -54,23 +54,31 @@ The typeface will be loaded in 400. ## Customization -[:octicons-file-code-24: Source][2] · -:octicons-mortar-board-24: Difficulty: easy - 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_, add the following lines -to `mkdocs.yml`: +Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize +font loading as described below. + +### Disable font loading + +[:octicons-file-code-24: Source][2] · +:octicons-mortar-board-24: Difficulty: _none_ + +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`: ``` yaml theme: font: false ``` -This will prevent typefaces from being loaded from Google Fonts. As a fallback, -common system fonts will be used automatically. Additionally, if you want to -load a font from another destination, you may either follow the guide on [theme -extension][6] and [override the `fonts` block][7] with a `style` tag, or use an -[additional stylesheet][8] to add the necessary `@font-face` definition: +### Additional fonts + +[:octicons-file-code-24: Source][2] · +:octicons-mortar-board-24: Difficulty: _easy_ + +If you want to load an (additional) font from another destination, or override +the fallback font, you can use an [additional stylesheet][8] to add the +corresponding `@font-face` definition: ``` css @font-face { @@ -79,9 +87,11 @@ extension][6] and [override the `fonts` block][7] with a `style` tag, or use an } ``` -The font can then be configured to be used as the regular or proportional font: +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: -=== "Regular font" +=== "Body copy" ``` css body, input { @@ -89,7 +99,15 @@ The font can then be configured to be used as the regular or proportional font: } ``` -=== "Proportional font" +=== "Headlines" + + ``` css + .md-typeset h1 { + font-family: "", -apple-system, Helvetica, Arial, sans-serif; + } + ``` + +=== "Code blocks" ``` css pre, code, kbd { diff --git a/docs/guides/changing-the-language.md b/docs/setup/changing-the-language.md similarity index 98% rename from docs/guides/changing-the-language.md rename to docs/setup/changing-the-language.md index 7c27029ab..85c138403 100644 --- a/docs/guides/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -129,8 +129,10 @@ directionality: ## Customization +### Translations + [:octicons-file-code-24: Source][1] · -:octicons-mortar-board-24: Difficulty: easy +:octicons-mortar-board-24: Difficulty: _easy_ If you want to customize some (or all) of the translations for your language, you may follow the guide on [theme extension][6] and create a new partial in diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md new file mode 100644 index 000000000..6497c8d5f --- /dev/null +++ b/docs/setup/changing-the-logo-and-icons.md @@ -0,0 +1 @@ +Icons are all inlined! diff --git a/docs/guides/setting-up-navigation.md b/docs/setup/setting-up-navigation.md similarity index 90% rename from docs/guides/setting-up-navigation.md rename to docs/setup/setting-up-navigation.md index 3f98ead7d..7c4cc1674 100644 --- a/docs/guides/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -180,17 +180,3 @@ them at your own risk._ [7]: https://python-markdown.github.io/extensions/toc/ [8]: https://python-markdown.github.io/extensions/toc/#usage [9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ - -## Customization - -[:octicons-file-code-24: Source][10] · -:octicons-mortar-board-24: Difficulty: moderate - -All navigational elements are defined as partials and can be overridden through -[theme extension][11] by [overriding partials][12] or [blocks][13], i.e. -`site_nav` which contains both sidebars, `tabs` and `footer`. - - [10]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials - [11]: ../customization.md#extending-the-theme - [12]: ../customization.md#overriding-partials - [13]: ../customization.md#overriding-blocks diff --git a/docs/guides/setting-up-site-search.md b/docs/setup/setting-up-site-search.md similarity index 98% rename from docs/guides/setting-up-site-search.md rename to docs/setup/setting-up-site-search.md index 783654735..a294d2e41 100644 --- a/docs/guides/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -32,7 +32,7 @@ The following options are supported: `lang` -: :octicons-milestone-24: Default: _automatically set_ · This option allows +: :octicons-milestone-24: Default: _automatically set_ – This option allows to include the language-specific stemmers provided by [lunr-languages][5]. Note that Material for MkDocs will set this automatically based on the [site language][6], but it may be overriden, e.g. to support multiple @@ -159,7 +159,7 @@ This section explains how search can be customized to tailor it to your needs. ### Query transformation [:octicons-file-code-24: Source][12] · -:octicons-mortar-board-24: Difficulty: easy +:octicons-mortar-board-24: Difficulty: _easy_ When a user enters a query into the search box, the query is pre-processed before it is submitted to the search index. Material for MkDocs will apply the @@ -233,7 +233,7 @@ and must return the processed query string to be submitted to the search index. ### Worker implementation [:octicons-file-code-24: Source][15] · -:octicons-mortar-board-24: Difficulty: challenging +:octicons-mortar-board-24: Difficulty: _challenging_ Material for MkDocs implements search as part of a [web worker][16]. If you want to switch the web worker with your own implementation, e.g. to submit diff --git a/mkdocs.yml b/mkdocs.yml index 61d60fea9..f48f497c2 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -131,29 +131,32 @@ nav: - Customization: customization.md #- Troubleshooting: troubleshooting.md - Data privacy: data-privacy.md + - Setup: + - Changing the colors: setup/changing-the-colors.md + - Changing the fonts: setup/changing-the-fonts.md + - Changing the language: setup/changing-the-language.md + - Changing the logo and icons: setup/changing-the-logo-and-icons.md + - Setting up navigation: setup/setting-up-navigation.md + - Setting up site search: setup/setting-up-site-search.md + - Adding a git repository: setup/adding-a-git-repository.md + - Adding social links: setup/adding-social-links.md + - Adding site analytics: setup/adding-site-analytics.md + - Adding a comment system: setup/adding-a-comment-system.md + - Adding an announcement bar: setup/adding-an-announcement-bar.md + #- Adding a landing page: setup/adding-a-landing-page.md - Reference: - Admonitions: reference/admonitions.md - Code blocks: reference/code-blocks.md - Content tabs: reference/content-tabs.md - Footnotes: reference/footnotes.md - Lists: reference/lists.md - - Guides: - - Changing colors: guides/changing-colors.md - - Changing the fonts: guides/changing-the-fonts.md - - Changing the language: guides/changing-the-language.md - - Setting up navigation: guides/setting-up-navigation.md - - Setting up site search: guides/setting-up-site-search.md - - Adding a git repository: guides/adding-a-git-repository.md - - Adding icons and emojis: guides/adding-icons-and-emojis.md - - Adding footer links: guides/adding-footer-links.md - - Adding site analytics: guides/adding-site-analytics.md - - Adding a comment system: guides/adding-a-comment-system.md - - Adding an announcement bar: guides/adding-an-announcement-bar.md - - Adding a landing page: guides/adding-a-landing-page.md - - Releases: - - Upgrading to 5.x: releases/5.md - - Upgrading to 4.x: releases/4.md - - Changelog: releases/changelog.md + # - Releases: + # - Upgrading to 5.x: releases/5.md + # - Upgrading to 4.x: releases/4.md + # - Changelog: releases/changelog.md + # Changelog: + # - Releases + # - Migration # - Contributing: contributing.md # - License: license.md