mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-23 23:21:00 +01:00
Documentation
This commit is contained in:
squidfunk
parent
f9d5c6709b
commit
228599b240
@ -8,7 +8,7 @@ categories:
|
||||
- Blog
|
||||
links:
|
||||
- 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
|
||||
@ -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
|
||||
[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/
|
||||
|
||||
## Quick start
|
||||
|
||||
@ -35,7 +35,7 @@ _This article explains how to set up Chinese language support for the built-in
|
||||
search plugin in a few minutes._
|
||||
{ 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
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -9,7 +9,7 @@ categories:
|
||||
- Search
|
||||
- Performance
|
||||
links:
|
||||
- setup/setting-up-site-search.md#built-in-search-plugin
|
||||
- plugins/search.md
|
||||
- insiders/index.md#how-to-become-a-sponsor
|
||||
---
|
||||
|
||||
@ -58,7 +58,7 @@ const index$ = document.forms.namedItem("search")
|
||||
|
||||
[lunr]: https://lunrjs.com
|
||||
[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
|
||||
|
||||
@ -244,7 +244,7 @@ carefully considered:
|
||||
stopping at a whitespace character when enough words have been consumed. A
|
||||
preview might look like this:
|
||||
|
||||
```
|
||||
```
|
||||
… 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
|
||||
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].
|
||||
- __Faster__ and __smaller__: significant decrease in search index size of up
|
||||
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]:
|
||||
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,
|
||||
Material for MkDocs adds wildcards to the end of each search term not
|
||||
explicitly preceded with `+` or `-`, effectively disabling tokenization.
|
||||
@ -499,7 +499,7 @@ following expression to the separator allows for just that:
|
||||
&[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
|
||||
other search terms discovered.
|
||||
|
||||
@ -548,7 +548,7 @@ powerful as tokenization:
|
||||
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
|
||||
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].
|
||||
|
||||
[regular expressions]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/highlighter/index.ts#L61-L91
|
||||
|
||||
@ -48,7 +48,7 @@ check the distribution of browser types and versions among your users.
|
||||
[caniuse.com]: https://caniuse.com/
|
||||
[:is pseudo selector]: https://caniuse.com/css-matches-pseudo
|
||||
[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
|
||||
|
||||
|
||||
@ -130,7 +130,7 @@ organization GitHub account for sponsoring.
|
||||
|
||||
__Important__: If you're sponsoring @squidfunk through a GitHub organization,
|
||||
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]
|
||||
|
||||
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
|
||||
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
|
||||
are released for general availability.
|
||||
|
||||
@ -289,7 +289,7 @@ are released for general availability.
|
||||
- [x] [Tags plugin: allow list] + [custom sorting]
|
||||
- [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: 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
|
||||
@ -306,8 +306,8 @@ are released for general availability.
|
||||
- [x] [Privacy plugin: external links]
|
||||
- [x] [Instant prefetching]
|
||||
|
||||
[Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
|
||||
[Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
|
||||
[Optimize plugin]: ../plugins/optimize.md
|
||||
[Typeset plugin]: ../plugins/typeset.md
|
||||
[Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
|
||||
[Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
|
||||
[Navigation path]: ../setup/setting-up-navigation.md#navigation-path
|
||||
@ -322,7 +322,7 @@ are released for general availability.
|
||||
- [x] [Code annotations: custom selectors]
|
||||
- [ ] 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: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
|
||||
[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
|
||||
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.
|
||||
|
||||
- If you cancel your subscription, you're automatically removed as a
|
||||
|
||||
@ -1384,7 +1384,7 @@ a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
|
||||
``` yaml
|
||||
---
|
||||
links:
|
||||
- setup/setting-up-site-search.md#built-in-search-plugin # (1)!
|
||||
- plugins/search.md # (1)!
|
||||
- Insiders:
|
||||
- insiders/index.md#how-to-become-a-sponsor
|
||||
- insiders/getting-started.md#requirements
|
||||
|
||||
@ -132,5 +132,5 @@ The following environments come with a preinstalled version of [pngquant]:
|
||||
- [x] No installation needed in [Docker image]
|
||||
|
||||
[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
|
||||
|
||||
@ -49,7 +49,7 @@ contents:
|
||||
- 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
|
||||
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 }}`.
|
||||
|
||||
- The `--utc` option makes sure that each workflow runner uses the same time zone.
|
||||
- The `%V` format assures a cache update once a week.
|
||||
- You can change the format to `%F` to have daily cache updates.
|
||||
- The `%V` format assures a cache update once a week.
|
||||
- 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.
|
||||
|
||||
@ -128,7 +128,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
|
||||
[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
|
||||
[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
|
||||
[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
|
||||
|
||||
@ -5,8 +5,8 @@ icon: material/emoticon-happy-outline
|
||||
# Icons, Emojis
|
||||
|
||||
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
|
||||
documentation with practically zero additional effort. Moreover, [custom icons
|
||||
than 10,000 icons][icon search] and thousands of emojis in your project
|
||||
documentation with practically zero additional effort. Moreover, [custom icons
|
||||
can be added] and used in `mkdocs.yml`, documents and templates.
|
||||
|
||||
[icon search]: #search
|
||||
@ -75,7 +75,7 @@ between two colons. If you're using [Twemoji] (recommended), you can look up
|
||||
the shortcodes at [Emojipedia]:
|
||||
|
||||
``` title="Emoji"
|
||||
:smile:
|
||||
:smile:
|
||||
```
|
||||
|
||||
<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
|
||||
Markdown and HTML formatting.
|
||||
|
||||
[built-in typeset plugin]: ./index.md#built-in-typeset-plugin
|
||||
[built-in typeset plugin]: ../plugins/typeset.md
|
||||
|
||||
## Customization
|
||||
|
||||
|
||||
@ -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
|
||||
[comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
|
||||
[overriding partials]: ../customization.md#overriding-partials
|
||||
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
@ -36,7 +36,7 @@ For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[site search]: setting-up-site-search.md
|
||||
[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
|
||||
|
||||
|
||||
@ -68,7 +68,7 @@ theme:
|
||||
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
|
||||
[built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
|
||||
[built-in privacy plugin]:../plugins/privacy.md
|
||||
|
||||
## Customization
|
||||
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
#### Changing the slug
|
||||
@ -380,7 +380,7 @@ to add related links to a post:
|
||||
---
|
||||
date: 2023-01-31
|
||||
links:
|
||||
- setup/setting-up-site-search.md#built-in-search-plugin
|
||||
- plugins/search.md
|
||||
- insiders/index.md#how-to-become-a-sponsor
|
||||
---
|
||||
|
||||
@ -396,7 +396,7 @@ links and even use nesting:
|
||||
---
|
||||
date: 2023-01-31
|
||||
links:
|
||||
- setup/setting-up-site-search.md#built-in-search-plugin
|
||||
- plugins/search.md
|
||||
- insiders/index.md#how-to-become-a-sponsor
|
||||
- Nested section:
|
||||
- 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
|
||||
`.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
|
||||
|
||||
|
||||
@ -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
|
||||
appended.
|
||||
|
||||
[built-in tags plugin]: #built-in-tags-plugin
|
||||
[built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
|
||||
[built-in tags plugin]: ../plugins/tags.md
|
||||
[built-in meta plugin]: ../plugins/meta.md
|
||||
|
||||
### Adding a tags index
|
||||
|
||||
|
||||
@ -127,7 +127,7 @@ changes into your templates. A good starting point is to [inspect the diff].
|
||||
#### `pymdownx.tabbed`
|
||||
|
||||
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]:
|
||||
|
||||
=== "8.x"
|
||||
@ -135,7 +135,7 @@ viewports]:
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
alternate_style: true
|
||||
```
|
||||
|
||||
=== "7.x"
|
||||
@ -1119,7 +1119,7 @@ matches the new structure:
|
||||
|
||||
[CSS variables]: setup/changing-the-colors.md#custom-colors
|
||||
[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`
|
||||
|
||||
@ -1217,7 +1217,7 @@ was renamed to `separator`:
|
||||
tokenizer: '[\s\-\.]+'
|
||||
```
|
||||
|
||||
[plugin options]: setup/setting-up-site-search.md#built-in-search-plugin
|
||||
[plugin options]: plugins/search.md
|
||||
|
||||
#### `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 }
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
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
|
||||
of the SASS code base.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user