OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Added back changelog and upgrade instructions

Browse Source
This commit is contained in:
squidfunk 2020-07-22 13:37:14 +02:00
parent 5ecf99c249
commit cafb79b788
9 changed files with 143 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/releases/changelog.md → docs/changelog.md
View File

@ -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 <small>_ June 29, 2020</small>

5
docs/contributing.md
View File

@ -1,5 +0,0 @@
---
template: overrides/main.html
---
--8<-- "CONTRIBUTING.md"

12
docs/creating-your-site.md
View File

@ -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]
<!-- * [Adding an announcement bar][13] -->
<!-- * [Adding a landing page][14] -->
[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
<!-- [13]: setup/adding-an-announcement-bar.md -->
<!--[14]: setup/adding-a-landing-page.md-->
## Previewing as you write

34
docs/reference/meta-tags.md Normal file
View File

@ -0,0 +1,34 @@
---
template: overrides/main.html
---
# Meta tags
TBD
<!-- Material for MkDocs supports several flavors of lists that cater to different
use cases, including _unordered lists_ and _ordered lists_, which are supported
through standard Markdown, as well as _definition lists_ and _task lists_, which
are supported through extensions. -->
## 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!?

30
docs/releases/4.md
View File

@ -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.

39
docs/setup/adding-a-comment-system.md
View File

@ -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: <shortname>
```
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: <shortname>
---
```
=== "Disable Disqus"
``` markdown
---
disqus: ""
---
```
[4]: ../reference/meta-tags.md#metadata

2
docs/setup/setting-up-site-analytics.md
View File

@ -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

76
docs/releases/5.md → docs/upgrading.md
View File

@ -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 %}
</nav>
```
## 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.

19
mkdocs.yml
View File

@ -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: