diff --git a/CHANGELOG b/CHANGELOG index f53a11185..f11e4717c 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-8.1.2+insiders-4.5.0 (2021-12-16) + + * Added support for navigation icons + mkdocs-material-8.1.2 (2012-12-15) * Switched CSS sources to logical properties diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index f4dd06e6d..f2da3b6fc 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 4.5.0 _ December 16, 2021 { id="4.5.0" } + +- Added support for navigation icons + ### 4.4.0 _ December 10, 2021 { id="4.4.0" } - Added support for code annotation anchor links (deep linking) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 6d9b6ea90..a643ceca7 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -162,6 +162,7 @@ The following features are solely available via Material for MkDocs Insiders:
+- [x] [Navigation icons] :material-new-box: - [x] [Code annotations: anchor links] :material-new-box: - [x] [Code annotations: strip comments] :material-new-box: - [x] [Dismissable announcement bar] @@ -250,9 +251,11 @@ are released for general availability. #### $ 12,000 – Piri Piri -- [ ] Text annotations -- [ ] Navigation icons +- [x] [Navigation icons] - [ ] Navigation pruning +- [ ] Text annotations + + [Navigation icons]: ../reference/index.md#setting-the-page-icon ### Goals completed diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md index 49a8454dc..99b6bc7ee 100644 --- a/docs/reference/abbreviations.md +++ b/docs/reference/abbreviations.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/image-size-select-small --- # Abbreviations diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 0fd362ab2..9c9113eff 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/alert-outline --- # Admonitions diff --git a/docs/reference/buttons.md b/docs/reference/buttons.md index 6f82d493e..25592a423 100644 --- a/docs/reference/buttons.md +++ b/docs/reference/buttons.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/gesture-tap-button --- # Buttons diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 595a15dfb..41c18a2c8 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/code-tags --- # Code blocks diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md index 1cca9411c..93da1b40b 100644 --- a/docs/reference/content-tabs.md +++ b/docs/reference/content-tabs.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/tab --- # Content tabs diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md index 445c35f8f..50056ab7f 100644 --- a/docs/reference/data-tables.md +++ b/docs/reference/data-tables.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/table-edit --- # Data tables diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md index f76370521..307baf9a2 100644 --- a/docs/reference/diagrams.md +++ b/docs/reference/diagrams.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/chart-gantt --- # Diagrams diff --git a/docs/reference/footnotes.md b/docs/reference/footnotes.md index 6c832f390..f9ce00c83 100644 --- a/docs/reference/footnotes.md +++ b/docs/reference/footnotes.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/format-superscript --- # Footnotes diff --git a/docs/reference/formatting.md b/docs/reference/formatting.md index a5647c593..cc9a7741e 100644 --- a/docs/reference/formatting.md +++ b/docs/reference/formatting.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/format-font --- # Formatting diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index fff540013..439f14436 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/emoticon-wink-outline --- # Icons + Emojis diff --git a/docs/reference/images.md b/docs/reference/images.md index 5b323f96d..5156bf8de 100644 --- a/docs/reference/images.md +++ b/docs/reference/images.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/image-frame --- # Images diff --git a/docs/reference/meta-tags.md b/docs/reference/index.md similarity index 62% rename from docs/reference/meta-tags.md rename to docs/reference/index.md index 52fd3ecd5..f685ab3d3 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/index.md @@ -2,21 +2,18 @@ template: overrides/main.html --- -# Meta tags +# Reference -In HTML, `meta` tags allow to provide additional metadata for a document, e.g. -page titles and descriptions, additional assets to be loaded, and [Open Graph] -metadata. While arbitrary `meta` tags can always be added via [customization], -some common `meta` tags can be configured. - - [Open Graph]: https://ogp.me/ - [customization]: #customization +Material for MkDocs is packed with many great features that make technical +writing a pleasure. This section of the documentation explains how to set up +a page, and showcases all available specimen that can be used directly from +within Markdown files. ## Configuration -This configuration adds support for setting custom page titles and descriptions -in [front matter], as well as for using custom metadata in templates. Add the -following lines to `mkdocs.yml`: +This configuration allows to set a title and description for a page, change the +template or define an icon to be rendered in the navigation. Add the following +lines to `mkdocs.yml`: ``` yaml markdown_extensions: @@ -62,15 +59,57 @@ Markdown file: ``` bash --- -description: Nullam urna elit, malesuada eget finibus ut, ac tortor. +description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! --- # Document title ... ``` -This will set the `meta` tag containing the site description inside the -document `head` for the current page to the provided value. +1. This will set the `meta` tag containing the site description inside the + document `head` for the current page to the provided value. + +### Setting the page icon + +[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.5.0][Insiders] · +:octicons-beaker-24: Experimental + +An icon can be assigned to each page, which is then rendered as part of the +navigation sidebar. Ensure [Metadata] is enabled and add the following lines +at the top of a Markdown file: + +``` bash +--- +icon: material/emoticon-happy # (1)! +--- + +# Document title +... +``` + +1. Check out the left sidebar to see icons in action! Also check out our + [icon search] to find the perfect icon with a few keystrokes. + + [Insiders]: ../insiders/index.md + [icon search]: icons-emojis.md#search + +### Setting the page template + +If you're using [theme extension] and created a new page template in the +`overrides` directory, you can enable it for a specific page. Add the following +lines at the top of a Markdown file: + +``` bash +--- +template: custom.html +--- + +# Document title +... +``` + + [theme extension]: ../customization.md#extending-the-theme ## Customization @@ -90,7 +129,6 @@ e.g. to add indexing policies for search engines via the `robots` property: {% endblock %} ``` - [theme extension]: ../customization.md#extending-the-theme [overriding blocks]: ../customization.md#overriding-blocks #### on a single page diff --git a/docs/reference/lists.md b/docs/reference/lists.md index 0b2beb197..c6ac063ef 100644 --- a/docs/reference/lists.md +++ b/docs/reference/lists.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/format-list-bulleted --- # Lists diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md index 8ccb25b5e..20fbcb1aa 100644 --- a/docs/reference/mathjax.md +++ b/docs/reference/mathjax.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +icon: material/alphabet-greek --- # MathJax diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index 31097f6ab..05f3a4a06 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -165,8 +165,8 @@ No configuration options are available. See reference for usage: [Metadata]: https://python-markdown.github.io/extensions/meta_data/ [Metadata support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 - [Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title - [Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description + [Setting the page title]: ../../reference/index.md#setting-the-page-title + [Setting the page description]: ../../reference/index.md#setting-the-page-description [Adding tags]: ../../setup/setting-up-tags.md#adding-tags [Hiding the tags]: ../../setup/setting-up-tags.md#hiding-the-tags [Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index e85a059d3..294907a95 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -272,5 +272,5 @@ default values. - [Changing the description] [Metadata]: extensions/python-markdown.md#metadata - [Changing the title]: ../reference/meta-tags.md#setting-the-page-title - [Changing the description]: ../reference/meta-tags.md#setting-the-page-description + [Changing the title]: ../reference/index.md#setting-the-page-title + [Changing the description]: ../reference/index.md#setting-the-page-description diff --git a/mkdocs.yml b/mkdocs.yml index cd2276de0..6eff977b6 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -91,9 +91,10 @@ plugins: - redirects: redirect_maps: changelog/insiders.md: insiders/changelog.md - upgrading.md: upgrade.md + reference/meta-tags.md: reference/index.md reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/ sponsorship.md: insiders/index.md + upgrading.md: upgrade.md - minify: minify_html: true @@ -189,6 +190,7 @@ nav: - Python Markdown: setup/extensions/python-markdown.md - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md - Reference: + - reference/index.md - Abbreviations: reference/abbreviations.md - Admonitions: reference/admonitions.md - Buttons: reference/buttons.md @@ -202,7 +204,6 @@ nav: - Images: reference/images.md - Lists: reference/lists.md - MathJax: reference/mathjax.md - - Meta tags: reference/meta-tags.md - Insiders: - insiders/index.md - Getting started: