From 64471665609149ebcc4a12f8188e4ea738999c24 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 27 Feb 2022 13:19:44 +0100 Subject: [PATCH] Documentation --- docs/blog/2021/search-better-faster-smaller.md | 2 +- docs/setup/changing-the-fonts.md | 4 ++-- docs/setup/ensuring-data-privacy.md | 14 +++++++------- docs/setup/setting-up-site-search.md | 2 +- docs/setup/setting-up-social-cards.md | 10 +++++----- docs/setup/setting-up-tags.md | 8 ++++---- docs/upgrade.md | 4 ++-- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/blog/2021/search-better-faster-smaller.md b/docs/blog/2021/search-better-faster-smaller.md index 9c9c38913..773836d4d 100644 --- a/docs/blog/2021/search-better-faster-smaller.md +++ b/docs/blog/2021/search-better-faster-smaller.md @@ -68,7 +68,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 + [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin ### Search index diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index d67825f6a..d431c937b 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -68,13 +68,13 @@ theme: !!! tip "Automatically bundle Google Fonts" - The brand-new [built-in privacy] plugin makes it easy to use Google Fonts + The brand-new [built-in privacy plugin] makes it easy to use Google Fonts while complying with the __General Data Protection Regulation__ (GDPR), 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 [font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 - [built-in privacy]: ensuring-data-privacy.md#built-in-privacy + [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin ## Customization diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index e6957b65f..e834615fd 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -14,7 +14,7 @@ automatically bundled as part of the build process. ## Configuration -### Built-in privacy +### Built-in privacy plugin [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-4.9.0][Insiders] · @@ -99,7 +99,7 @@ The following configuration options are available: authors might add external assets like third-party scripts or stylesheets that would need to be remembered to be defined as further local assets. - This is the very reason the [built-in privacy] plugin exists — it automates + This is the very reason the [built-in privacy plugin] exists — it automates the process of downloading all external assets manually to ensure compliance with GDPR. Note that there are some [technical limitations]. @@ -110,7 +110,7 @@ The following configuration options are available: #### How it works -The [built-in privacy] plugin scans the resulting HTML for links to external +The [built-in privacy plugin] scans the resulting HTML for links to external resources, including external scripts, style sheets, images and web fonts, and downloads them to bundle them with your documentation site. Every URL refering to an external resource, no matter if part of a template or Markdown file is @@ -129,7 +129,7 @@ The external script is downloaded, and the link is replaced with: Style sheets are scanned for external `url(...)` references, e.g. images and web fonts, which are then also downloaded and bundled with your documentation site. This means that [Google Fonts] can be configured in `mkdocs.yml` as usual, -as the [built-in privacy] plugin automatically downloads and bundles all +as the [built-in privacy plugin] automatically downloads and bundles all dependent resources. As a third measure, [`preconnect`][preconnect] hints used for DNS pre-fetching @@ -138,7 +138,7 @@ removed during the build process. ??? example "Expand to inspect example" - For the official documentation, the [built-in privacy] plugin downloads the + For the official documentation, the [built-in privacy plugin] downloads the following resources: ``` { .sh id="example" } @@ -206,7 +206,7 @@ removed during the build process. └─ polyfill.io/v3/polyfill.min.js ``` - [built-in privacy]: #built-in-privacy + [built-in privacy plugin]: #built-in-privacy-plugin [preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch #### Caching recommended { #caching data-toc-label="Caching" } @@ -248,7 +248,7 @@ carried out. You might want to: #### Limitations Note that dynamically created URLs as part of scripts are not detected, and thus -cannot be automatically downloaded. The [built-in privacy] plugin does not +cannot be automatically downloaded. The [built-in privacy plugin] does not execute scripts – it can only detect fully qualified URLs to download and replace. diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index de71050a6..5112cbd5a 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -15,7 +15,7 @@ not be compliant with privacy regulations. Moreover, search even works ## Configuration -### Built-in search +### Built-in search plugin [:octicons-tag-24: 0.1.0][search support] · :octicons-cpu-24: Plugin diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index 0d5cebfc8..bf3e095b1 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -37,7 +37,7 @@ The social preview image for the page on [setting up site analytics]. ## Configuration -### Built-in social cards +### Built-in social plugin [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [:octicons-tag-24: insiders-2.12.0][Insiders] · @@ -179,8 +179,8 @@ install all dependencies on your system: #### Caching recommended { #caching data-toc-label="Caching" } -The [built-in social cards] plugin automatically fetches the fonts you define -in `mkdocs.yml` from Google Fonts, and uses them to render the text that is +The [built-in social plugin] automatically fetches the fonts you define in +`mkdocs.yml` from Google Fonts, and uses them to render the text that is displayed on the social card. The font files and generated cards are both written to the `.cache` directory, which is used in subsequent builds to detect whether the social cards need to be regenerated. You might want to: @@ -213,12 +213,12 @@ whether the social cards need to be regenerated. You might want to: - run: mkdocs gh-deploy --force ``` - [built-in social cards]: #built-in-social-cards + [built-in social plugin]: #built-in-social-plugin [publishing guide]: ../publishing-your-site.md#with-github-actions #### Meta tags -The [built-in social cards] plugin automatically sets all necessary `meta` tags, +The [built-in social plugin] automatically sets all necessary `meta` tags, equivalent to the following two customizations, which you can set manually when you don't want to use it: diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index e088d258b..1a9e98177 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -11,7 +11,7 @@ can help to discover relevant information faster. ## Configuration -### Built-in tags +### Built-in tags plugin [:octicons-tag-24: 8.2.0][tags support] · :octicons-cpu-24: Plugin · @@ -53,7 +53,7 @@ The following configuration options are available: ### Adding tags -When both, the [built-in tags] plugin and [Metadata] extension are enabled, +When both, the [built-in tags plugin] and [Metadata] extension are enabled, tags can be added for a document with custom front matter. Add the following lines at the top of a Markdown file: @@ -79,14 +79,14 @@ following screenshots: [![Tag search preview]][Tag search preview] - [built-in tags]: #built-in-tags + [built-in tags plugin]: #built-in-tags-plugin [Metadata]: extensions/python-markdown.md#metadata [Tags preview]: ../assets/screenshots/tags.png [Tag search preview]: ../assets/screenshots/tags-search.png ### Adding a tags index -The [built-in tags] plugin allows to define a file to render a [tags index] +The [built-in tags plugin] allows to define a file to render a [tags index] [tags.tags_file], which can be any page that is part of the `nav` section. To add a tags index, create a page, e.g. `tags.md`: diff --git a/docs/upgrade.md b/docs/upgrade.md index 8c6dfdaa6..b0942b3d6 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -1037,7 +1037,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 + [prebuilt search indexes]: setup/setting-up-site-search.md#built-in-search-plugin ### Changes to `mkdocs.yml` @@ -1135,7 +1135,7 @@ was renamed to `separator`: tokenizer: '[\s\-\.]+' ``` - [plugin options]: setup/setting-up-site-search.md#built-in-search + [plugin options]: setup/setting-up-site-search.md#built-in-search-plugin #### `extra.social.*`