mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Updated documentation
This commit is contained in:
squidfunk
parent
e8aa1b92a2
commit
c90b9211f4
1064
docs/changelog.md
1064
docs/changelog.md
File diff suppressed because it is too large
Load Diff
@ -77,9 +77,9 @@ be slightly different:
|
||||
logo: logo
|
||||
```
|
||||
|
||||
_If you cloned Material for MkDocs from GitHub, you must add all of the themes'
|
||||
defaults by yourself, since_ [`mkdocs_theme.yml`][3] _is not loaded (as
|
||||
[described in the official documentation][4])._
|
||||
_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
|
||||
defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
|
||||
[described in the official documentation][4]._
|
||||
|
||||
[2]: getting-started.md#installation
|
||||
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
|
||||
@ -91,18 +91,22 @@ Material for MkDocs comes with a lot of configuration options. The _setup_
|
||||
section explains in great detail how to configure and customize colors, fonts,
|
||||
icons and much more:
|
||||
|
||||
* [Changing the colors][5]
|
||||
* [Changing the fonts][6]
|
||||
* [Changing the language][7]
|
||||
* [Changing the logo and icons][8]
|
||||
* [Setting up navigation][9]
|
||||
* [Setting up site search][10]
|
||||
* [Setting up site analytics][11]
|
||||
* [Setting up versioning][12]
|
||||
* [Setting up the header][13]
|
||||
* [Setting up the footer][14]
|
||||
* [Adding a git repository][15]
|
||||
* [Adding a comment system][16]
|
||||
<ul class="tx-columns" markdown="1">
|
||||
|
||||
- [Changing the colors][5]
|
||||
- [Changing the fonts][6]
|
||||
- [Changing the language][7]
|
||||
- [Changing the logo and icons][8]
|
||||
- [Setting up navigation][9]
|
||||
- [Setting up site search][10]
|
||||
- [Setting up site analytics][11]
|
||||
- [Setting up versioning][12]
|
||||
- [Setting up the header][13]
|
||||
- [Setting up the footer][14]
|
||||
- [Adding a git repository][15]
|
||||
- [Adding a comment system][16]
|
||||
|
||||
</ul>
|
||||
|
||||
[5]: setup/changing-the-colors.md
|
||||
[6]: setup/changing-the-fonts.md
|
||||
|
||||
@ -67,8 +67,8 @@ covered in the following sections.
|
||||
|
||||
The following plugins are bundled with the Docker image:
|
||||
|
||||
* [mkdocs-minify-plugin][12]
|
||||
* [mkdocs-redirects][13]
|
||||
- [mkdocs-minify-plugin][12]
|
||||
- [mkdocs-redirects][13]
|
||||
|
||||
[11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[12]: https://github.com/byrnereese/mkdocs-minify-plugin
|
||||
|
||||
@ -339,24 +339,24 @@ If [Pygments][23] is used, Material for MkDocs provides the [styles for code
|
||||
blocks][22], which are built with a custom and well-balanced palette that works
|
||||
equally well for both [color schemes][24]:
|
||||
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
|
||||
|
||||
Code block foreground, background and line highlight colors are defined via:
|
||||
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
|
||||
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
|
||||
- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
|
||||
|
||||
Let's say you want to change the color of `#!js "strings"`. While there are
|
||||
several [types of string tokens][25], Material for MkDocs assigns a single color
|
||||
|
||||
@ -155,16 +155,16 @@ highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* ==This was marked==
|
||||
* ^^This was inserted^^
|
||||
* ~~This was deleted~~
|
||||
- ==This was marked==
|
||||
- ^^This was inserted^^
|
||||
- ~~This was deleted~~
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* ==This was marked==
|
||||
* ^^This was inserted^^
|
||||
* ~~This was deleted~~
|
||||
- ==This was marked==
|
||||
- ^^This was inserted^^
|
||||
- ~~This was deleted~~
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
|
||||
@ -177,13 +177,13 @@ HTML tags:
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* H~2~0
|
||||
* A^T^A
|
||||
- H~2~0
|
||||
- A^T^A
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* H~2~0
|
||||
* A^T^A
|
||||
- H~2~0
|
||||
- A^T^A
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
|
||||
@ -28,9 +28,9 @@ markdown_extensions:
|
||||
|
||||
The following icon sets are bundled with Material for MkDocs:
|
||||
|
||||
* :material-material-design: – [Material Design][6]
|
||||
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
|
||||
* :octicons-mark-github-16: – [Octicons][8]
|
||||
- :material-material-design: – [Material Design][6]
|
||||
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
|
||||
- :octicons-mark-github-16: – [Octicons][8]
|
||||
|
||||
You can also add [additional icons][9]. When using emojis, it's recommended to
|
||||
consult the official documentation of [Python Markdown Extensions][3] to learn
|
||||
@ -89,16 +89,16 @@ a valid path to any icon bundled with the theme, which are located in the
|
||||
_Example_:
|
||||
|
||||
```
|
||||
* :material-account-circle: – `.icons/material/account-circle.svg`
|
||||
* :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
|
||||
* :octicons-octoface-16: – `.icons/octicons/octoface-16.svg`
|
||||
- :material-account-circle: – `.icons/material/account-circle.svg`
|
||||
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
|
||||
- :octicons-octoface-16: – `.icons/octicons/octoface-16.svg`
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* :material-account-circle: – [`.icons/material/account-circle.svg`][14]
|
||||
* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
|
||||
* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16]
|
||||
- :material-account-circle: – [`.icons/material/account-circle.svg`][14]
|
||||
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
|
||||
- :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16]
|
||||
|
||||
[13]: #emoji
|
||||
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
|
||||
@ -141,16 +141,16 @@ Then, simply add the CSS class to the icon.
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* :fontawesome-brands-medium:{: .medium } – Medium
|
||||
* :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
* :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
- :fontawesome-brands-medium:{: .medium } – Medium
|
||||
- :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* :fontawesome-brands-medium:{: .medium } – Medium
|
||||
* :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
* :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
- :fontawesome-brands-medium:{: .medium } – Medium
|
||||
- :fontawesome-brands-twitter:{: .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{: .facebook } – Facebook
|
||||
|
||||
[17]: #attribute-list
|
||||
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
|
||||
|
||||
@ -74,7 +74,7 @@ of lists can be nested inside each other.
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
|
||||
- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
|
||||
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
|
||||
lacinia sed. Aenean in finibus diam.
|
||||
|
||||
@ -85,7 +85,7 @@ _Example_:
|
||||
|
||||
_Result_:
|
||||
|
||||
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
|
||||
- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
|
||||
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
|
||||
lacinia sed. Aenean in finibus diam.
|
||||
|
||||
@ -182,21 +182,21 @@ checkbox.
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
||||
* [ ] Vestibulum convallis sit amet nisi a tincidunt
|
||||
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
||||
- [ ] Vestibulum convallis sit amet nisi a tincidunt
|
||||
* [x] In hac habitasse platea dictumst
|
||||
* [x] In scelerisque nibh non dolor mollis congue sed et metus
|
||||
* [ ] Praesent sed risus massa
|
||||
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
||||
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
||||
* [ ] Vestibulum convallis sit amet nisi a tincidunt
|
||||
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
||||
- [ ] Vestibulum convallis sit amet nisi a tincidunt
|
||||
* [x] In hac habitasse platea dictumst
|
||||
* [x] In scelerisque nibh non dolor mollis congue sed et metus
|
||||
* [ ] Praesent sed risus massa
|
||||
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
||||
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
||||
|
||||
[7]: #tasklist
|
||||
|
||||
@ -62,18 +62,22 @@ specific pages by adding the following to the front matter of a page:
|
||||
|
||||
=== "Enable Disqus"
|
||||
|
||||
``` markdown
|
||||
``` yaml
|
||||
---
|
||||
disqus: <shortname>
|
||||
---
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
=== "Disable Disqus"
|
||||
|
||||
``` markdown
|
||||
``` yaml
|
||||
---
|
||||
disqus: ""
|
||||
---
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
[7]: #metadata
|
||||
|
||||
@ -59,16 +59,16 @@ theme:
|
||||
|
||||
Some popular choices:
|
||||
|
||||
* :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`
|
||||
- :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
|
||||
|
||||
|
||||
@ -72,9 +72,9 @@ markdown_extensions:
|
||||
|
||||
The following icon sets are bundled with Material for MkDocs:
|
||||
|
||||
* :material-material-design: – [Material Design][8]
|
||||
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][9]
|
||||
* :octicons-mark-github-16: – [Octicons][10]
|
||||
- :material-material-design: – [Material Design][8]
|
||||
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][9]
|
||||
- :octicons-mark-github-16: – [Octicons][10]
|
||||
|
||||
If you want to add [additional icons][1], read on.
|
||||
|
||||
|
||||
@ -312,15 +312,15 @@ message format using _discriminated unions_, i.e. through the `type` property
|
||||
of the message. See the following interface definitions to learn about the
|
||||
message formats:
|
||||
|
||||
* [:octicons-file-code-24: `SearchMessage`][22]
|
||||
* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][23]
|
||||
- [:octicons-file-code-24: `SearchMessage`][22]
|
||||
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][23]
|
||||
|
||||
The sequence and direction of messages is rather intuitive:
|
||||
|
||||
* :octicons-arrow-right-24: `SearchSetupMessage`
|
||||
* :octicons-arrow-left-24: `SearchReadyMessage`
|
||||
* :octicons-arrow-right-24: `SearchQueryMessage`
|
||||
* :octicons-arrow-left-24: `SearchResultMessage`
|
||||
- :octicons-arrow-right-24: `SearchSetupMessage`
|
||||
- :octicons-arrow-left-24: `SearchReadyMessage`
|
||||
- :octicons-arrow-right-24: `SearchQueryMessage`
|
||||
- :octicons-arrow-left-24: `SearchResultMessage`
|
||||
|
||||
[20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
|
||||
[21]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
|
||||
|
||||
@ -20,15 +20,15 @@ pip show mkdocs-material
|
||||
|
||||
### What's new?
|
||||
|
||||
* Improved search result look and feel
|
||||
* Improved search result stability while typing
|
||||
* Improved search result grouping (pages + headings)
|
||||
* Improved search result relevance and scoring
|
||||
* Added display of missing query terms to search results
|
||||
* Reduced size of vendor bundle by 25% (84kb → 67kb)
|
||||
* Reduced size of the Docker image to improve CI build performance
|
||||
* Removed hero partial in favor of [custom implementation][1]
|
||||
* Removed [deprecated front matter features][2]
|
||||
- Improved search result look and feel
|
||||
- Improved search result stability while typing
|
||||
- Improved search result grouping (pages + headings)
|
||||
- Improved search result relevance and scoring
|
||||
- Added display of missing query terms to search results
|
||||
- Reduced size of vendor bundle by 25% (84kb → 67kb)
|
||||
- Reduced size of the Docker image to improve CI build performance
|
||||
- Removed hero partial in favor of [custom implementation][1]
|
||||
- Removed [deprecated front matter features][2]
|
||||
|
||||
[1]: deprecations.md#hero
|
||||
[2]: deprecations.md#front-matter
|
||||
@ -287,20 +287,20 @@ matches the new structure:
|
||||
|
||||
### What's new?
|
||||
|
||||
* Reactive architecture – try `#!js app.dialog$.next("Hi!")` in the console
|
||||
* [Instant loading][4] – make Material behave like a Single Page Application
|
||||
* Improved CSS customization with [CSS variables][5] – 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
|
||||
* 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][7]
|
||||
* 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, ...)
|
||||
- Reactive architecture – try `#!js app.dialog$.next("Hi!")` in the console
|
||||
- [Instant loading][4] – make Material behave like a Single Page Application
|
||||
- Improved CSS customization with [CSS variables][5] – 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
|
||||
- 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][7]
|
||||
- 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, ...)
|
||||
|
||||
[5]: setup/changing-the-colors.md#custom-colors
|
||||
[6]: setup/changing-the-logo-and-icons.md#icons
|
||||
|
||||
@ -58,5 +58,10 @@
|
||||
> * {
|
||||
break-inside: avoid;
|
||||
}
|
||||
|
||||
// [mobile portrait -]: Reset columns on mobile
|
||||
@include break-to-device(mobile portrait) {
|
||||
columns: initial;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user