From cafb79b7880bb46701c5f221e2b69db43d19f34f Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 22 Jul 2020 13:37:14 +0200 Subject: [PATCH] Added back changelog and upgrade instructions --- docs/{releases => }/changelog.md | 16 +----- docs/contributing.md | 5 -- docs/creating-your-site.md | 12 ++-- docs/reference/meta-tags.md | 34 +++++++++++ docs/releases/4.md | 30 ---------- docs/setup/adding-a-comment-system.md | 39 ++++++++++++- docs/setup/setting-up-site-analytics.md | 2 +- docs/{releases/5.md => upgrading.md} | 76 ++++++++++++++++++------- mkdocs.yml | 19 +++---- 9 files changed, 143 insertions(+), 90 deletions(-) rename docs/{releases => }/changelog.md (99%) delete mode 100644 docs/contributing.md create mode 100644 docs/reference/meta-tags.md delete mode 100644 docs/releases/4.md rename docs/{releases/5.md => upgrading.md} (94%) diff --git a/docs/releases/changelog.md b/docs/changelog.md similarity index 99% rename from docs/releases/changelog.md rename to docs/changelog.md index 234b3d951..aa8bb8361 100644 --- a/docs/releases/changelog.md +++ b/docs/changelog.md @@ -2,21 +2,9 @@ template: overrides/main.html --- -# Upgrading +# Changelog -To upgrade to the latest version: - -``` sh -pip install --upgrade mkdocs-material -``` - -To inspect the currently installed version: - -``` sh -pip show mkdocs-material -``` - -## Changelog +## Release notes ### 5.4.0 _ June 29, 2020 diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 89103b76b..000000000 --- a/docs/contributing.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -template: overrides/main.html ---- - ---8<-- "CONTRIBUTING.md" diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index d22b0fcd7..fc9014029 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -71,10 +71,10 @@ icons and much more: * [Setting up navigation][7] * [Setting up site search][8] * [Setting up site analytics][9] -* [Adding a git repository][10] -* [Adding social links][11] +* [Adding social links][10] +* [Adding a git repository][11] * [Adding a comment system][12] -* [Adding an announcement bar][13] + [2]: getting-started.md#installation @@ -85,10 +85,10 @@ icons and much more: [7]: setup/setting-up-navigation.md [8]: setup/setting-up-site-search.md [9]: setup/setting-up-site-analytics.md - [10]: setup/adding-a-git-repository.md - [11]: setup/adding-social-links.md + [10]: setup/adding-social-links.md + [11]: setup/adding-a-git-repository.md [12]: setup/adding-a-comment-system.md - [13]: setup/adding-an-announcement-bar.md + ## Previewing as you write diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md new file mode 100644 index 000000000..628d9c503 --- /dev/null +++ b/docs/reference/meta-tags.md @@ -0,0 +1,34 @@ +--- +template: overrides/main.html +--- + +# Meta tags + +TBD + + + +## Configuration + +### Metadata + +[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] + +The [Metadata][1] extension, which is part of the standard Markdown +library, adds the ability to add custom metadata to a document and can be +enabled from `mkdocs.yml`: + +``` yaml +markdown_extensions: + - meta +``` + + [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [2]: https://python-markdown.github.io/extensions/meta_data/ + +## Customization + +- add custom meta tags, like twitter cards etc via customization!? diff --git a/docs/releases/4.md b/docs/releases/4.md deleted file mode 100644 index 69a8aaa26..000000000 --- a/docs/releases/4.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -template: overrides/main.html ---- - -# Upgrading to 4.x - -## Highlights - -Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix -includes a mandatory change of the base font-size from `10px` to `20px` which -means all `rem` values needed to be updated. Within the theme, `px` to `rem` -calculation is now encapsulated in a new function called `px2rem` which is part -of the SASS code base. - -If you use Material for MkDocs with custom CSS that is based on `rem` values, -note that those values must now be divided by 2. Now, `1.0rem` doesn't map to -`10px`, but `20px`. To learn more about the problem and implications, please -refer to [the issue][1] in which the problem was discovered and fixed. - - [1]: https://github.com/squidfunk/mkdocs-material/issues/911 - -## How to upgrade - -### Changes to `mkdocs.yml` - -None. - -### Changes to `*.html` files - -None. diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 6b5cf7f44..edbbb84e8 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -1,3 +1,7 @@ +--- +template: overrides/main.html +--- + # Adding a comment system Material for MkDocs is natively integrated with [Disqus][1], a comment system @@ -9,10 +13,43 @@ integrated, too. ## Configuration -### Comment system +### Disqus +First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate +Material for MkDocs with [Disqus][1], create an account and a site giving you a +[shortname][3], and add it to `mkdocs.yml`: +``` yaml +extra: + disqus: +``` + +This will insert a comment system on _every page, except the index page_. + + [2]: https://www.mkdocs.org/user-guide/configuration/#site_url + [3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname ## Customization ### Selective integration + +If the [Metadata][4] extension is enabled, you can disable or enable Disqus for +specific pages by adding the following to the front matter of a page: + +=== "Enable Disqus" + + ``` markdown + --- + disqus: + --- + ``` + +=== "Disable Disqus" + + ``` markdown + --- + disqus: "" + --- + ``` + + [4]: ../reference/meta-tags.md#metadata diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 2d3506a8c..6285bf401 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -31,7 +31,7 @@ google_analytics: [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html [4]: https://support.google.com/analytics/answer/1042508 -### Tracking site search +#### Enabling site search tracking Besides basic page views, _site search_ can also be tracked to better understand how people use your documentation and what they expect to find. To enable diff --git a/docs/releases/5.md b/docs/upgrading.md similarity index 94% rename from docs/releases/5.md rename to docs/upgrading.md index 2c9c71831..473dca837 100644 --- a/docs/releases/5.md +++ b/docs/upgrading.md @@ -2,29 +2,43 @@ template: overrides/main.html --- -# Upgrading to 5.x +# Upgrading -## Highlights +Upgrade to the latest version with: + +``` sh +pip install --upgrade mkdocs-material +``` + +Inspect the currently installed version with: + +``` sh +pip show mkdocs-material +``` + +## Upgrading from 4.x to 5.x + +### What's new? * Reactive architecture – try `app.dialog$.next("Hi!")` in the console -* [Instant loading][5] – make Material behave like a Single Page Application -* Improved CSS customization with [CSS variables][1] – set your brand's colors +* [Instant loading][1] – make Material behave like a Single Page Application +* Improved CSS customization with [CSS variables][2] – set your brand's colors * Improved CSS resilience, e.g. proper sidebar locking for customized headers -* Improved [icon integration][6] and configuration – now including over 5k icons +* Improved [icon integration][3] and configuration – now including over 5k icons * Added possibility to use any icon for logo, repository and social links * Search UI does not freeze anymore (moved to web worker) * Search index built only once when using instant loading * Improved extensible keyboard handling -* Support for [prebuilt search indexes][2] +* Support for [prebuilt search indexes][4] * Support for displaying stars and forks for GitLab repositories * Support for scroll snapping of sidebars and search results * Reduced HTML and CSS footprint due to deprecation of Internet Explorer support * Slight facelifting of some UI elements (Admonitions, tables, ...) - [1]: https://github.com/squidfunk/mkdocs-material/blob/081d540127c41703da3d73aa69eb521615c1cb89/src/assets/stylesheets/base/_colors.scss#L27-L55 - [2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index - -## How to upgrade + [1]: setup/navigation.md#instant-loading + [2]: setup/changing-the-colors.md#custom-colors + [3]: setup/changing-the-logo-and-icons.md#icons + [4]: setup/setting-up-site-search.md#built-in-search ### Changes to `mkdocs.yml` @@ -34,7 +48,7 @@ does not contain the key, you can skip it. #### `theme.feature` -Optional features like [tabs][4] and [instant loading][5] are now implemented as +Optional features like [tabs][5] and [instant loading][1] are now implemented as flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`: === "5.x" @@ -54,13 +68,12 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`: tabs: true ``` - [4]: ../../getting-started/#tabs - [5]: ../../getting-started/#instant-loading + [5]: setup/navigation.md#navigation-tabs #### `theme.logo.icon` The logo icon configuration was centralized under `theme.icon.logo` and can now -be set to any of the [icons bundled with the theme][6]: +be set to any of the [icons bundled with the theme][3]: === "5.x" @@ -70,8 +83,6 @@ be set to any of the [icons bundled with the theme][6]: logo: material/cloud ``` - [6]: ../../getting-started/#icons - === "4.x" ``` yaml @@ -83,7 +94,7 @@ be set to any of the [icons bundled with the theme][6]: #### `extra.repo_icon` The repo icon configuration was centralized under `theme.icon.repo` and can now -be set to any of the [icons bundled with the theme][6]: +be set to any of the [icons bundled with the theme][3]: === "5.x" @@ -102,7 +113,7 @@ be set to any of the [icons bundled with the theme][6]: #### `extra.search.*` -Search is now configured as part of the [plugin options][7]. Note that the +Search is now configured as part of the [plugin options][6]. Note that the search languages must now be listed as an array of strings and the `tokenizer` was renamed to `separator`: @@ -127,7 +138,7 @@ was renamed to `separator`: tokenizer: [\s\-\.]+ ``` - [7]: ../../plugins/search/#configuration + [6]: setup/setting-up-site-search.md#built-in-search #### `extra.social.*` @@ -158,8 +169,8 @@ The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure: -- If you've overridden a __block__, check `base.html` for potential changes -- If you've overridden a __template__, check the respective `*.html` file for +- If you've overridden a **block**, check `base.html` for potential changes +- If you've overridden a **template**, check the respective `*.html` file for potential changes #### `base.html` @@ -869,3 +880,26 @@ matches the new structure: {% endif %} ``` + +## Upgrading from 3.x to 4.x + +### What's new? + +Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix +includes a mandatory change of the base font-size from `10px` to `20px` which +means all `rem` values needed to be updated. Within the theme, `px` to `rem` +calculation is now encapsulated in a new function called `px2rem` which is part +of the SASS code base. + +If you use Material for MkDocs with custom CSS that is based on `rem` values, +note that those values must now be divided by 2. Now, `1.0rem` doesn't map to +`10px`, but `20px`. To learn more about the problem and implications, please +refer to #911 in which the problem was discovered and fixed. + +### Changes to `mkdocs.yml` + +None. + +### Changes to `*.html` files + +None. diff --git a/mkdocs.yml b/mkdocs.yml index 06dc6955a..88505f9ed 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -131,6 +131,7 @@ nav: - Customization: customization.md #- Troubleshooting: troubleshooting.md - Data privacy: data-privacy.md + - License: license.md - Setup: - Changing the colors: setup/changing-the-colors.md - Changing the fonts: setup/changing-the-fonts.md @@ -139,10 +140,10 @@ nav: - Setting up navigation: setup/setting-up-navigation.md - Setting up site search: setup/setting-up-site-search.md - Setting up site analytics: setup/setting-up-site-analytics.md - - Adding a git repository: setup/adding-a-git-repository.md - Adding social links: setup/adding-social-links.md + - Adding a git repository: setup/adding-a-git-repository.md - Adding a comment system: setup/adding-a-comment-system.md - - Adding an announcement bar: setup/adding-an-announcement-bar.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 @@ -150,16 +151,10 @@ nav: - Content tabs: reference/content-tabs.md - Footnotes: reference/footnotes.md - Lists: reference/lists.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 + - Meta tags: reference/meta-tags.md + - Changelog: + - Release notes: changelog.md + - Upgrading: upgrading.md # Google Analytics google_analytics: