From 0fb3a4e53e90b049645a36206e11f5bb1fb2f47d Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 12 May 2021 09:29:40 +0200 Subject: [PATCH] Updated documentation --- docs/insiders/index.md | 31 +++++++++------- docs/setup/setting-up-site-search.md | 55 ++++++++++++++++++++-------- 2 files changed, 56 insertions(+), 30 deletions(-) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index fc1ea38b2..fa396b373 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -111,9 +111,10 @@ The following features are currently exclusively available to sponsors:
+- [x] [Boosting pages in search :material-new-box:][30] - [x] [Tags (with search integration) :material-new-box:][29] -- [x] [Stay on page when switching versions :material-new-box:][28] -- [x] [Version warning :material-new-box:][26] +- [x] [Stay on page when switching versions][28] +- [x] [Version warning][26] - [x] [Custom admonition icons][28] - [x] [Code block annotations][25] - [x] [Anchor tracking ][24] @@ -183,9 +184,11 @@ the public for general availability. #### $ 6,000 – Trinidad Scorpion +- [x] [Boosting pages in search][30] - [ ] Improved search result summaries - [ ] Stay on page when switching languages -- [ ] List of last searches + + [30]: ../setup/setting-up-site-search.md#boosting-a-page #### $ 7,000 – Royal Gold @@ -195,19 +198,19 @@ the public for general availability. #### $ 8,000 – Scotch Bonnet -- [x] [Custom admonition icons][30] +- [x] [Custom admonition icons][31] - [ ] Table of contents shows which sections have search results -- [ ] TBA +- [ ] List of last searches - [30]: ../reference/admonitions.md#changing-the-icons + [31]: ../reference/admonitions.md#changing-the-icons #### Future -- [ ] [Material for MkDocs Live Edit][31] +- [ ] [Material for MkDocs Live Edit][32] - [ ] New layouts and styles - [ ] Code block palette toggle - [31]: https://twitter.com/squidfunk/status/1338252230265360391 + [32]: https://twitter.com/squidfunk/status/1338252230265360391 ### Goals completed @@ -262,10 +265,10 @@ implemented behind feature flags; all configuration changes are backward-compatible. This means that your users will be able to build the documentation locally with Material for MkDocs and when they push their changes, it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's -recommended to [install Insiders][32] only in CI, as you don't want to expose +recommended to [install Insiders][33] only in CI, as you don't want to expose your `GH_TOKEN` to users. - [32]: ../publishing-your-site.md#github-pages + [33]: ../publishing-your-site.md#github-pages ### Terms @@ -274,7 +277,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_ Yes. Whether you're an individual or a company, you may use _Material for MkDocs Insiders_ precisely under the same terms as Material for MkDocs, which are given -by the [MIT license][33]. However, we kindly ask you to respect the following +by the [MIT license][34]. However, we kindly ask you to respect the following guidelines: - Please __don't distribute the source code__ of Insiders. You may freely use @@ -285,7 +288,7 @@ guidelines: - If you cancel your subscription, you're removed as a collaborator and will miss out on future updates of Insiders. However, you may __use the latest version__ that's available to you __as long as you like__. Just remember that - [GitHub deletes private forks][34]. + [GitHub deletes private forks][35]. - [33]: ../license.md - [34]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository + [34]: ../license.md + [35]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index ad569cd54..e9772ca79 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -261,6 +261,29 @@ For setup instructions, refer to the [official documentation][18]. system, you will also want to set `use_directory_urls: false` in `mkdocs.yml` to make page links function correctly. +## Usage + +### Boosting a page + +[:octicons-file-code-24: Source][8] · +:octicons-note-24: Metadata · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][8]{ .mdx-insiders } + +In order to give specific pages a higher relevance in search, [lunr][4] supports +page-specific boosts, which can be defined for each page by leveraging the +[Metadata][19] extension: + +``` yaml +--- +search: + boost: 100 +--- + +... +``` + + [19]: ../../reference/meta-tags/#metadata + ## Customization The search implementation of Material for MkDocs is probably its most @@ -273,12 +296,12 @@ your needs. ### Query transformation -[:octicons-file-code-24: Source][19] · +[:octicons-file-code-24: Source][20] · :octicons-mortar-board-24: Difficulty: _easy_ When a user enters a query into the search box, the query is pre-processed before it is submitted to the search index. Material for MkDocs will apply the -following transformations, which can be customized by [extending the theme][20]: +following transformations, which can be customized by [extending the theme][21]: ``` ts /** @@ -318,7 +341,7 @@ export function defaultTransform(query: string): string { 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]: +`config` block][22]: ``` html {% block config %} @@ -336,19 +359,19 @@ customize the `transform` function, you can do this by [overriding the The `transform` function will receive the query string as entered by the user 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-recommended + [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts + [21]: ../customization.md#extending-the-theme + [22]: ../customization.md#overriding-blocks-recommended ### Custom search -[:octicons-file-code-24: Source][22] · +[:octicons-file-code-24: Source][23] · :octicons-mortar-board-24: Difficulty: _challenging_ -Material for MkDocs implements search as part of a [web worker][23]. If you +Material for MkDocs implements search as part of a [web worker][24]. If you want to switch the web worker with your own implementation, e.g. to submit -search to an external service, you can add a custom JavaScript file to the `docs` -directory and [override the `config` block][21]: +search to an external service, you can add a custom JavaScript file to the +`docs` directory and [override the `config` block][21]: ``` html {% block config %} @@ -366,8 +389,8 @@ 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] +- [:octicons-file-code-24: `SearchMessage`][25] +- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][26] The sequence and direction of messages is rather intuitive: @@ -376,7 +399,7 @@ The sequence and direction of messages is rather intuitive: - :octicons-arrow-right-24: `SearchQueryMessage` - :octicons-arrow-left-24: `SearchResultMessage` - [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker - [23]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers - [24]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts - [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts + [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker + [24]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers + [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts + [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts