From 228599b240b0e720ecec008522d18394f6ab82ce Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 15 Sep 2023 09:25:50 +0200 Subject: [PATCH] Documentation --- docs/blog/posts/blog-support-just-landed.md | 4 ++-- docs/blog/posts/chinese-search-support.md | 2 +- docs/blog/posts/search-better-faster-smaller.md | 14 +++++++------- docs/browser-support.md | 2 +- docs/insiders/index.md | 14 +++++++------- docs/plugins/blog.md | 2 +- docs/plugins/requirements/image-processing.md | 2 +- docs/publishing-your-site.md | 8 ++++---- docs/reference/icons-emojis.md | 8 ++++---- docs/setup/adding-a-comment-system.md | 2 +- docs/setup/building-for-offline-usage.md | 2 +- docs/setup/changing-the-fonts.md | 2 +- docs/setup/setting-up-a-blog.md | 8 ++++---- docs/setup/setting-up-tags.md | 4 ++-- docs/upgrade.md | 12 ++++++------ 15 files changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/blog/posts/blog-support-just-landed.md b/docs/blog/posts/blog-support-just-landed.md index 47a2733f8..cd4a06bd4 100644 --- a/docs/blog/posts/blog-support-just-landed.md +++ b/docs/blog/posts/blog-support-just-landed.md @@ -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 diff --git a/docs/blog/posts/chinese-search-support.md b/docs/blog/posts/chinese-search-support.md index 4f06371e4..0652696b4 100644 --- a/docs/blog/posts/chinese-search-support.md +++ b/docs/blog/posts/chinese-search-support.md @@ -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 diff --git a/docs/blog/posts/search-better-faster-smaller.md b/docs/blog/posts/search-better-faster-smaller.md index 430be9cc5..0c5c66c59 100644 --- a/docs/blog/posts/search-better-faster-smaller.md +++ b/docs/blog/posts/search-better-faster-smaller.md @@ -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 diff --git a/docs/browser-support.md b/docs/browser-support.md index 2ccbbb8f0..7cf4f5af9 100644 --- a/docs/browser-support.md +++ b/docs/browser-support.md @@ -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 diff --git a/docs/insiders/index.md b/docs/insiders/index.md index f9af18643..6860d5f20 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -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 diff --git a/docs/plugins/blog.md b/docs/plugins/blog.md index 901e37473..6eac717d7 100644 --- a/docs/plugins/blog.md +++ b/docs/plugins/blog.md @@ -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 diff --git a/docs/plugins/requirements/image-processing.md b/docs/plugins/requirements/image-processing.md index 38b3dc03d..c53cbf6ad 100644 --- a/docs/plugins/requirements/image-processing.md +++ b/docs/plugins/requirements/image-processing.md @@ -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 diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index 264bb687e..abd0a293d 100644 --- a/docs/publishing-your-site.md +++ b/docs/publishing-your-site.md @@ -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 `.github.io/`. [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 diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index 6a1c6dd41..b854a977b 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -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: ```
@@ -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 diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 635848d5f..62f2409b2 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -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 diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md index 54a3987c6..5c13b5742 100644 --- a/docs/setup/building-for-offline-usage.md +++ b/docs/setup/building-for-offline-usage.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 diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index dfd8ccaa9..f3af6ac3f 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -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 diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 83065a120..0b5b1cab3 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/docs/setup/setting-up-a-blog.md @@ -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 diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 1146e98bc..4da70873c 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -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 diff --git a/docs/upgrade.md b/docs/upgrade.md index 65e0be071..b5ee87a07 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -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.