1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-13 18:40:54 +01:00

Documentation

This commit is contained in:
squidfunk 2023-09-15 09:25:50 +02:00
parent f9d5c6709b
commit 228599b240
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
15 changed files with 43 additions and 43 deletions

View File

@ -8,7 +8,7 @@ categories:
- Blog - Blog
links: links:
- Getting started with Insiders: insiders/getting-started.md#requirements - Getting started with Insiders: insiders/getting-started.md#requirements
- setup/setting-up-a-blog.md#built-in-blog-plugin - plugins/blog.md
--- ---
# Blog support just landed # Blog support just landed
@ -31,7 +31,7 @@ _This article explains how to build a standalone blog with Material for MkDocs.
If you want to build a blog alongside your documentation, please refer to If you want to build a blog alongside your documentation, please refer to
[the plugin's documentation][built-in blog plugin]._ [the plugin's documentation][built-in blog plugin]._
[built-in blog plugin]: ../../setup/setting-up-a-blog.md#built-in-blog-plugin [built-in blog plugin]: ../../plugins/blog.md
[Jekyll]: https://jekyllrb.com/ [Jekyll]: https://jekyllrb.com/
## Quick start ## Quick start

View File

@ -35,7 +35,7 @@ _This article explains how to set up Chinese language support for the built-in
search plugin in a few minutes._ search plugin in a few minutes._
{ style="display: inline" } { style="display: inline" }
[built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin [built-in search plugin]: ../../plugins/search.md
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
## Configuration ## Configuration

View File

@ -9,7 +9,7 @@ categories:
- Search - Search
- Performance - Performance
links: links:
- setup/setting-up-site-search.md#built-in-search-plugin - plugins/search.md
- insiders/index.md#how-to-become-a-sponsor - insiders/index.md#how-to-become-a-sponsor
--- ---
@ -58,7 +58,7 @@ const index$ = document.forms.namedItem("search")
[lunr]: https://lunrjs.com [lunr]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
[built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin [built-in search plugin]: ../../plugins/search.md
### Search index ### Search index
@ -244,7 +244,7 @@ carefully considered:
stopping at a whitespace character when enough words have been consumed. A stopping at a whitespace character when enough words have been consumed. A
preview might look like this: preview might look like this:
``` ```
… channels, e.g., or which can be configured via mkdocs.yml … … channels, e.g., or which can be configured via mkdocs.yml …
``` ```
@ -286,7 +286,7 @@ it brings:
- __Better__: support for [rich search previews], preserving the structural - __Better__: support for [rich search previews], preserving the structural
information of code blocks, inline code, and lists, so they are rendered information of code blocks, inline code, and lists, so they are rendered
as-is, as well as [lookahead tokenization], [more accurate highlighting], and as-is, as well as [lookahead tokenization], [more accurate highlighting], and
improved stability of typeahead. Also, a [slightly better UX]. improved stability of typeahead. Also, a [slightly better UX].
- __Faster__ and __smaller__: significant decrease in search index size of up - __Faster__ and __smaller__: significant decrease in search index size of up
to 48% due to improved extraction and construction techniques, resulting in a to 48% due to improved extraction and construction techniques, resulting in a
@ -463,7 +463,7 @@ also demonstrates that this now even works properly for search queries.[^5]
[^5]: [^5]:
Previously, the search query was not correctly tokenized due to the way Previously, the search query was not correctly tokenized due to the way
[lunr] treats wildcards, as it disables the pipeline for search terms that [lunr] treats wildcards, as it disables the pipeline for search terms that
contain wildcards. In order to provide a good typeahead experience, contain wildcards. In order to provide a good typeahead experience,
Material for MkDocs adds wildcards to the end of each search term not Material for MkDocs adds wildcards to the end of each search term not
explicitly preceded with `+` or `-`, effectively disabling tokenization. explicitly preceded with `+` or `-`, effectively disabling tokenization.
@ -499,7 +499,7 @@ following expression to the separator allows for just that:
&[lg]t; &[lg]t;
``` ```
Searching for [:octicons-search-24: custom search worker script][q=script] Searching for [:octicons-search-24: custom search worker script][q=script]
brings up the section on [custom search] and matches the `script` tag among the brings up the section on [custom search] and matches the `script` tag among the
other search terms discovered. other search terms discovered.
@ -548,7 +548,7 @@ powerful as tokenization:
Now, only the content blocks that actually contain occurrences of one of Now, only the content blocks that actually contain occurrences of one of
the search terms are considered for inclusion into the search preview. If a the search terms are considered for inclusion into the search preview. If a
term only occurs in a code block, it's the code block that gets rendered, term only occurs in a code block, it's the code block that gets rendered,
see, for example, the results of see, for example, the results of
[:octicons-search-24: twitter][q=twitter]. [:octicons-search-24: twitter][q=twitter].
[regular expressions]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/highlighter/index.ts#L61-L91 [regular expressions]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/highlighter/index.ts#L61-L91

View File

@ -48,7 +48,7 @@ check the distribution of browser types and versions among your users.
[caniuse.com]: https://caniuse.com/ [caniuse.com]: https://caniuse.com/
[:is pseudo selector]: https://caniuse.com/css-matches-pseudo [:is pseudo selector]: https://caniuse.com/css-matches-pseudo
[browser support]: #supported-browsers [browser support]: #supported-browsers
[built-in privacy plugin]: setup/ensuring-data-privacy.md#built-in-privacy-plugin [built-in privacy plugin]: plugins/privacy.md
## Other browsers ## Other browsers

View File

@ -130,7 +130,7 @@ organization GitHub account for sponsoring.
__Important__: If you're sponsoring @squidfunk through a GitHub organization, __Important__: If you're sponsoring @squidfunk through a GitHub organization,
please send a short email to sponsors@squidfunk.com with the name of your please send a short email to sponsors@squidfunk.com with the name of your
organization and the GitHub account of the individual that should be added as a organization and the GitHub account of the individual that should be added as a
collaborator.[^4] collaborator.[^4]
You can cancel your sponsorship anytime.[^5] You can cancel your sponsorship anytime.[^5]
@ -260,7 +260,7 @@ You can cancel your sponsorship anytime.[^5]
The following section lists all funding goals. Each goal contains a list of The following section lists all funding goals. Each goal contains a list of
features prefixed with a checkmark symbol, denoting whether a feature is features prefixed with a checkmark symbol, denoting whether a feature is
:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or
:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
are released for general availability. are released for general availability.
@ -289,7 +289,7 @@ are released for general availability.
- [x] [Tags plugin: allow list] + [custom sorting] - [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Navigation subtitles] - [x] [Navigation subtitles]
[Meta plugin]: ../reference/index.md#built-in-meta-plugin [Meta plugin]: ../plugins/meta.md
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
@ -306,8 +306,8 @@ are released for general availability.
- [x] [Privacy plugin: external links] - [x] [Privacy plugin: external links]
- [x] [Instant prefetching] - [x] [Instant prefetching]
[Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin [Optimize plugin]: ../plugins/optimize.md
[Typeset plugin]: ../reference/index.md#built-in-typeset-plugin [Typeset plugin]: ../plugins/typeset.md
[Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
[Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
[Navigation path]: ../setup/setting-up-navigation.md#navigation-path [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
@ -322,7 +322,7 @@ are released for general availability.
- [x] [Code annotations: custom selectors] - [x] [Code annotations: custom selectors]
- [ ] Code line wrap button - [ ] Code line wrap button
[Projects plugin]: ../setup/building-an-optimized-site.md#built-in-projects-plugin [Projects plugin]: ../plugins/projects.md
[Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
[Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
[Code range selection]: ../reference/code-blocks.md#code-selection-button [Code range selection]: ../reference/code-blocks.md#code-selection-button
@ -536,7 +536,7 @@ __fair use policy__:
- Please __don't distribute the source code__ of Insiders. You may freely use - Please __don't distribute the source code__ of Insiders. You may freely use
it for public, private or commercial projects, privately fork or mirror it, it for public, private or commercial projects, privately fork or mirror it,
but please don't make the source code public, as it would counteract the but please don't make the source code public, as it would counteract the
sponsorware strategy. sponsorware strategy.
- If you cancel your subscription, you're automatically removed as a - If you cancel your subscription, you're automatically removed as a

View File

@ -1384,7 +1384,7 @@ a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
``` yaml ``` yaml
--- ---
links: links:
- setup/setting-up-site-search.md#built-in-search-plugin # (1)! - plugins/search.md # (1)!
- Insiders: - Insiders:
- insiders/index.md#how-to-become-a-sponsor - insiders/index.md#how-to-become-a-sponsor
- insiders/getting-started.md#requirements - insiders/getting-started.md#requirements

View File

@ -132,5 +132,5 @@ The following environments come with a preinstalled version of [pngquant]:
- [x] No installation needed in [Docker image] - [x] No installation needed in [Docker image]
[pngquant]: https://pngquant.org/ [pngquant]: https://pngquant.org/
[built-in optimize plugin]: ../../setup/building-an-optimized-site.md#built-in-optimize-plugin [built-in optimize plugin]: ../../plugins/optimize.md
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild [pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild

View File

@ -49,7 +49,7 @@ contents:
- run: mkdocs gh-deploy --force - run: mkdocs gh-deploy --force
``` ```
1. You can change the name to your liking. 1. You can change the name to your liking.
2. At some point, GitHub renamed `master` to `main`. If your default branch 2. At some point, GitHub renamed `master` to `main`. If your default branch
is named `master`, you can safely remove `main`, vice versa. is named `master`, you can safely remove `main`, vice versa.
@ -58,8 +58,8 @@ contents:
`key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`. `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
- The `--utc` option makes sure that each workflow runner uses the same time zone. - The `--utc` option makes sure that each workflow runner uses the same time zone.
- The `%V` format assures a cache update once a week. - The `%V` format assures a cache update once a week.
- You can change the format to `%F` to have daily cache updates. - You can change the format to `%F` to have daily cache updates.
You can read the [manual page] to learn more about the formatting options of the `date` command. You can read the [manual page] to learn more about the formatting options of the `date` command.
@ -128,7 +128,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[Insiders]: insiders/index.md [Insiders]: insiders/index.md
[built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin [built-in optimize plugin]: plugins/optimize.md
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
[publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
[manual page]: https://man7.org/linux/man-pages/man1/date.1.html [manual page]: https://man7.org/linux/man-pages/man1/date.1.html

View File

@ -5,8 +5,8 @@ icon: material/emoticon-happy-outline
# Icons, Emojis # Icons, Emojis
One of the best features of Material for MkDocs is the possibility to use [more One of the best features of Material for MkDocs is the possibility to use [more
than 10,000 icons][icon search] and thousands of emojis in your project than 10,000 icons][icon search] and thousands of emojis in your project
documentation with practically zero additional effort. Moreover, [custom icons documentation with practically zero additional effort. Moreover, [custom icons
can be added] and used in `mkdocs.yml`, documents and templates. can be added] and used in `mkdocs.yml`, documents and templates.
[icon search]: #search [icon search]: #search
@ -75,7 +75,7 @@ between two colons. If you're using [Twemoji] (recommended), you can look up
the shortcodes at [Emojipedia]: the shortcodes at [Emojipedia]:
``` title="Emoji" ``` title="Emoji"
:smile: :smile:
``` ```
<div class="result" markdown> <div class="result" markdown>
@ -199,7 +199,7 @@ With the help of the [built-in typeset plugin], you can use icons and emojis
in headings, which will then be rendered in the sidebars. The plugin preserves in headings, which will then be rendered in the sidebars. The plugin preserves
Markdown and HTML formatting. Markdown and HTML formatting.
[built-in typeset plugin]: ./index.md#built-in-typeset-plugin [built-in typeset plugin]: ../plugins/typeset.md
## Customization ## Customization

View File

@ -104,4 +104,4 @@ If you wish to enable comments for an entire folder, you can use the
[theme extension]: ../customization.md#extending-the-theme [theme extension]: ../customization.md#extending-the-theme
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
[overriding partials]: ../customization.md#overriding-partials [overriding partials]: ../customization.md#overriding-partials
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin [built-in meta plugin]: ../plugins/meta.md

View File

@ -36,7 +36,7 @@ For a list of all settings, please consult the [plugin documentation].
[site search]: setting-up-site-search.md [site search]: setting-up-site-search.md
[site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir [site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin [built-in privacy plugin]:../plugins/privacy.md
#### Limitations #### Limitations

View File

@ -68,7 +68,7 @@ theme:
by automatically downloading and self-hosting the web font files. by automatically downloading and self-hosting the web font files.
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users [data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin [built-in privacy plugin]:../plugins/privacy.md
## Customization ## Customization

View File

@ -349,7 +349,7 @@ As usual, the tags are rendered above the main headline and posts are linked
on the tags index page, if configured. Note that posts are, as pages, only on the tags index page, if configured. Note that posts are, as pages, only
linked with their titles. linked with their titles.
[built-in tags plugin]: setting-up-tags.md#built-in-tags-plugin [built-in tags plugin]: ../plugins/tags.md
[tags index]: setting-up-tags.md#adding-a-tags-index [tags index]: setting-up-tags.md#adding-a-tags-index
#### Changing the slug #### Changing the slug
@ -380,7 +380,7 @@ to add related links to a post:
--- ---
date: 2023-01-31 date: 2023-01-31
links: links:
- setup/setting-up-site-search.md#built-in-search-plugin - plugins/search.md
- insiders/index.md#how-to-become-a-sponsor - insiders/index.md#how-to-become-a-sponsor
--- ---
@ -396,7 +396,7 @@ links and even use nesting:
--- ---
date: 2023-01-31 date: 2023-01-31
links: links:
- setup/setting-up-site-search.md#built-in-search-plugin - plugins/search.md
- insiders/index.md#how-to-become-a-sponsor - insiders/index.md#how-to-become-a-sponsor
- Nested section: - Nested section:
- External link: https://example.com - External link: https://example.com
@ -510,7 +510,7 @@ Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
values defined for a post, which means you can define common properties in values defined for a post, which means you can define common properties in
`.meta.yml` and then add specific properties or overrides for each post. `.meta.yml` and then add specific properties or overrides for each post.
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin [built-in meta plugin]: ../plugins/meta.md
### Adding pages ### Adding pages

View File

@ -147,8 +147,8 @@ search preview, which now allows to __find pages by tags__.
and then add specific tags for each page. The tags in `.meta.yml` are and then add specific tags for each page. The tags in `.meta.yml` are
appended. appended.
[built-in tags plugin]: #built-in-tags-plugin [built-in tags plugin]: ../plugins/tags.md
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin [built-in meta plugin]: ../plugins/meta.md
### Adding a tags index ### Adding a tags index

View File

@ -127,7 +127,7 @@ changes into your templates. A good starting point is to [inspect the diff].
#### `pymdownx.tabbed` #### `pymdownx.tabbed`
Support for the legacy style of the [Tabbed] extension was dropped in favor Support for the legacy style of the [Tabbed] extension was dropped in favor
of the new, alternate implementation which has [better behavior on mobile of the new, alternate implementation which has [better behavior on mobile
viewports]: viewports]:
=== "8.x" === "8.x"
@ -135,7 +135,7 @@ viewports]:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- pymdownx.tabbed: - pymdownx.tabbed:
alternate_style: true alternate_style: true
``` ```
=== "7.x" === "7.x"
@ -1119,7 +1119,7 @@ matches the new structure:
[CSS variables]: setup/changing-the-colors.md#custom-colors [CSS variables]: setup/changing-the-colors.md#custom-colors
[icon integration]: reference/icons-emojis.md#search [icon integration]: reference/icons-emojis.md#search
[prebuilt search indexes]: setup/setting-up-site-search.md#built-in-search-plugin [prebuilt search indexes]: plugins/search.md
### Changes to `mkdocs.yml` ### Changes to `mkdocs.yml`
@ -1217,7 +1217,7 @@ was renamed to `separator`:
tokenizer: '[\s\-\.]+' tokenizer: '[\s\-\.]+'
``` ```
[plugin options]: setup/setting-up-site-search.md#built-in-search-plugin [plugin options]: plugins/search.md
#### `extra.social.*` #### `extra.social.*`
@ -1245,7 +1245,7 @@ in order to match the new way of specifying which icon to be used:
### Changes to `*.html` files { data-search-exclude } ### Changes to `*.html` files { data-search-exclude }
The templates have undergone a set of changes to make them future-proof. If 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 you've used theme extension to override a block or template, make sure that it
matches the new structure: matches the new structure:
- If you've overridden a __block__, check `base.html` for potential changes - If you've overridden a __block__, check `base.html` for potential changes
@ -1947,7 +1947,7 @@ matches the new structure:
Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix 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 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` 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 calculation is now encapsulated in a new function called `px2rem` which is part
of the SASS code base. of the SASS code base.