From 74755fc604ecedce7927b8cc6755260976298d0f Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 1 May 2021 20:26:54 +0200 Subject: [PATCH] Documentation --- docs/creating-your-site.md | 36 +++++++++++++------------ docs/customization.md | 4 +-- docs/data-privacy.md | 10 +++---- docs/deprecations.md | 2 +- docs/getting-started.md | 4 +-- docs/insiders/getting-started.md | 2 +- docs/reference/meta-tags.md | 2 +- docs/setup/adding-a-comment-system.md | 2 +- docs/setup/changing-the-fonts.md | 2 +- docs/setup/setting-up-site-analytics.md | 4 +-- docs/setup/setting-up-site-search.md | 16 +++++------ docs/setup/setting-up-tags.md | 6 ++--- docs/setup/setting-up-the-header.md | 2 +- docs/setup/setting-up-versioning.md | 2 +- docs/troubleshooting.md | 2 +- 15 files changed, 49 insertions(+), 47 deletions(-) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index ea9bcf87e..1adf7694f 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -100,11 +100,12 @@ and much more: - [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] +- [Setting up tags][12] +- [Setting up versioning][13] +- [Setting up the header][14] +- [Setting up the footer][15] +- [Adding a git repository][16] +- [Adding a comment system][17] @@ -115,11 +116,12 @@ and much more: [9]: setup/setting-up-navigation.md [10]: setup/setting-up-site-search.md [11]: setup/setting-up-site-analytics.md - [12]: setup/setting-up-versioning.md - [13]: setup/setting-up-the-header.md - [14]: setup/setting-up-the-footer.md - [15]: setup/adding-a-git-repository.md - [16]: setup/adding-a-comment-system.md + [12]: setup/setting-up-tags.md + [13]: setup/setting-up-versioning.md + [14]: setup/setting-up-the-header.md + [15]: setup/setting-up-the-footer.md + [16]: setup/adding-a-git-repository.md + [17]: setup/adding-a-comment-system.md ## Previewing as you write @@ -145,12 +147,12 @@ If you're running Material for MkDocs from within Docker, use: docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material ``` -Point your browser to [localhost:8000][17] and you should see: +Point your browser to [localhost:8000][18] and you should see: -[![Creating your site][18]][18] +[![Creating your site][19]][19] - [17]: http://localhost:8000 - [18]: assets/screenshots/creating-your-site.png + [18]: http://localhost:8000 + [19]: assets/screenshots/creating-your-site.png ## Building your site @@ -163,8 +165,8 @@ mkdocs build The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. -The site can be hosted on [GitHub Pages][19], [GitLab Pages][20], a CDN of your +The site can be hosted on [GitHub Pages][20], [GitLab Pages][21], a CDN of your choice or your private web space. - [19]: publishing-your-site.md#github-pages - [20]: publishing-your-site.md#gitlab-pages + [20]: publishing-your-site.md#github-pages + [21]: publishing-your-site.md#gitlab-pages diff --git a/docs/customization.md b/docs/customization.md index 6d4aeb161..486103fd4 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -152,7 +152,7 @@ directory: MkDocs will now use the new partial when rendering the theme. This can be done with any file. -### Overriding blocks +### Overriding blocks recommended { data-toc-label="Overiding blocks" } Besides overriding partials, it's also possible to override (and extend) _template blocks_, which are defined inside the templates and wrap specific @@ -273,7 +273,7 @@ Start the watcher with: npm start ``` -Then, in a second session, start the MkDocs server with: +Then, in a second session, start the MkDocs live preview server with: ``` mkdocs serve diff --git a/docs/data-privacy.md b/docs/data-privacy.md index 626f26e65..b85f7887f 100644 --- a/docs/data-privacy.md +++ b/docs/data-privacy.md @@ -4,9 +4,9 @@ template: overrides/main.html # Data privacy -In itself, Material for MkDocs does not perform any tracking and should adhere -to the [General Data Protection Regulation][1] (GDPR), but it integrates with -some third-party services that may not. +In itself, Material for MkDocs does not perform any tracking and adheres to the +[General Data Protection Regulation][1] (GDPR), but it integrates with some +third-party services that may not. [1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation @@ -15,7 +15,7 @@ some third-party services that may not. ### Google Fonts Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts -CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily +CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily disabled][3] via `mkdocs.yml`. [2]: setup/changing-the-fonts.md @@ -23,7 +23,7 @@ disabled][3] via `mkdocs.yml`. ### Google Analytics and Disqus -Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] +Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] integrations, both of which must be enabled explicitly, so there's no immediate action if you don't use those. diff --git a/docs/deprecations.md b/docs/deprecations.md index b758cd2e8..1f36a71e4 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -112,7 +112,7 @@ templates can be shared among multiple pages: {% endblock %} ``` - [5]: customization.md#overriding-blocks + [5]: customization.md#overriding-blocks-recommended [6]: customization.md#extending-the-theme ## Docker image diff --git a/docs/getting-started.md b/docs/getting-started.md index caec26292..d062563df 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -13,13 +13,13 @@ If not, we recommended using [`docker`][3]. In case you're running into problems, consult the [troubleshooting][4] section. [1]: https://www.mkdocs.org - [2]: #with-pip + [2]: #with-pip-recommended [3]: #with-docker [4]: troubleshooting.md ## Installation -### with pip +### with pip recommended { data-toc-label="with pip" } Material for MkDocs can be installed with `pip`: diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index 9b117804e..0604085cc 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -11,7 +11,7 @@ Material for MkDocs, and can be installed similar to the public version using account is added to the list of collaborators of the private Insiders repository. - [1]: #with-pip + [1]: #with-pip-recommended [2]: #with-docker [3]: #with-git diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index 0afc570d3..fde01756c 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -94,7 +94,7 @@ policies for search engines: ``` [7]: ../customization.md#extending-the-theme - [8]: ../customization.md#overriding-blocks + [8]: ../customization.md#overriding-blocks-recommended #### on a single page diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 33661a3b3..9e391d959 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -82,4 +82,4 @@ In order to integrate another JavaScript-based comment system provider, you can [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html [7]: ../customization.md#extending-the-theme - [8]: ../customization.md#overriding-blocks + [8]: ../customization.md#overriding-blocks-recommended diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index f0eff3085..bf00f0058 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -109,5 +109,5 @@ fonts being added automatically): [5]: ../data-privacy.md [6]: ../customization.md#extending-the-theme - [7]: ../customization.md#overriding-blocks + [7]: ../customization.md#overriding-blocks-recommended [8]: ../customization.md#additional-stylesheets diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 596e4f4ff..9d834a52b 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -7,7 +7,7 @@ template: overrides/main.html As with any other service offered on the web, understanding how your project documentation is actually used can be an essential success factor. While Material for MkDocs natively integrates with [Google Analytics][1], [other -analytics services][2] can be used, too. +analytics providers][2] can be used, too. [1]: https://developers.google.com/analytics [2]: #other-analytics-providers @@ -61,7 +61,7 @@ and [override the `analytics` block][6]: ``` [5]: ../customization.md#extending-the-theme - [6]: ../customization.md#overriding-blocks + [6]: ../customization.md#overriding-blocks-recommended If you're using [instant loading][7], you may use the `location$` observable, which will emit the current `URL` to listen for navigation events and register diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 15da19188..ad569cd54 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -315,9 +315,9 @@ export function defaultTransform(query: string): string { } ``` -If you want to switch to the default behavior of the `mkdocs` or `readthedocs` -template, both of which don't transform the query prior to submission, or -customize the `transform` function, you can do this by [overriding the +If you want to switch to the default behavior of the `mkdocs` and `readthedocs` +themes, both of which don't transform the query prior to submission, or +customize the `transform` function, you can do this by [overriding the `config` block][21]: ``` html @@ -338,7 +338,7 @@ and must return the processed query string to be submitted to the search index. [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts [20]: ../customization.md#extending-the-theme - [21]: ../customization.md#overriding-blocks + [21]: ../customization.md#overriding-blocks-recommended ### Custom search @@ -361,10 +361,10 @@ directory and [override the `config` block][21]: {% endblock %} ``` -Communication with the search worker is implemented using a standardized -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: +Communication with the search worker is implemented using a designated 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`][24] - [:octicons-file-code-24: `SearchIndex` and `SearchResult`][25] diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 29274e969..87782bb4b 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -72,8 +72,8 @@ The following options are available: [:octicons-file-code-24: Source][1] ยท :octicons-note-24: Metadata -If the [built-in tags plugin][4] and [Metadata][5] extension are enabled, tags -can be added for any page as part of the front matter, e.g. to add the tags +If both, the [built-in tags plugin][4] and [Metadata][5] extension are enabled, +tags can be added for any page as part of the front matter, e.g. to add the tags `insiders` and `brand new` to this page, add: ``` yaml @@ -87,7 +87,7 @@ tags: ``` The page will now render with those tags below the main headline and within the -search preview, which now allows to __search for tags__, as shown in the +search preview, which now allows to __find pages by tags__, as shown in the following screenshots: === "Tags" diff --git a/docs/setup/setting-up-the-header.md b/docs/setup/setting-up-the-header.md index a251f2a4b..be5ff01a7 100644 --- a/docs/setup/setting-up-the-header.md +++ b/docs/setup/setting-up-the-header.md @@ -48,4 +48,4 @@ block][5], which is empty by default: ``` [4]: ../customization.md#extending-the-theme - [5]: ../customization.md#overriding-blocks + [5]: ../customization.md#overriding-blocks-recommended diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md index 2624f9edc..ce51571c5 100644 --- a/docs/setup/setting-up-versioning.md +++ b/docs/setup/setting-up-versioning.md @@ -102,7 +102,7 @@ Make sure that this matches the [default version][11]. [7]: ../insiders/index.md [8]: ../customization.md#extending-the-theme - [9]: ../customization.md#overriding-blocks + [9]: ../customization.md#overriding-blocks-recommended [10]: ../assets/screenshots/version-warning.png [11]: #setting-a-default-version diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b103119d9..09b46a4c9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -113,5 +113,5 @@ of which is to use virtual environments: ``` [1]: https://docs.python.org/3/tutorial/venv.html - [2]: getting-started.md#with-pip + [2]: getting-started.md#with-pip-recommended [3]: https://brew.sh/