1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-23 23:21:00 +01:00

Updated documentation for Material for MkDocs Insiders

This commit is contained in:
squidfunk 2020-12-06 17:41:10 +01:00
parent 84251be688
commit dbee5ede5e
5 changed files with 83 additions and 26 deletions

View File

@ -1,3 +1,7 @@
mkdocs-material-6.1.7+insiders-1.12.0 (2020-12-06)
* Added support for adding a language selector
mkdocs-material-6.1.7 (2020-12-06)
* Fixed #2081: Fixed stats for private GitHub repositories

View File

@ -6,6 +6,10 @@ template: overrides/main.html
## Material for MkDocs Insiders
### 1.12.0 <small>_ December 6, 2020</small>
- Added support for adding a language selector
### 1.11.2 <small>_ November 29, 2020</small>
- Fixed #2068: Search highlight interprets code blocks as JavaScript

View File

@ -114,6 +114,7 @@ for MkDocs Insiders. You can click on each feature to learn more about it:
- [x] [Remove _Made with Material for MkDocs_ from footer][11]
- [x] [Support for user-toggleable themes (light/dark mode switch)][12]
- [x] [Support for deploying multiple versions][13]
- [x] [Support for deploying multiple languages][22]
- [x] [Search suggestions help to save keystrokes][14]
- [x] [Highlighting of matched search terms in content area][15]
- [x] Search goes to first result on ++enter++ (I'm feeling lucky)
@ -135,19 +136,20 @@ for MkDocs Insiders. You can click on each feature to learn more about it:
[19]: setup/setting-up-navigation.md#navigation-integration
[20]: setup/setting-up-the-header.md#automatic-hiding
[21]: reference/admonitions.md#inline-blocks
[22]: setup/changing-the-language.md#site-language-selector
## Roadmap
The following list of funding goals named after varieties of chili peppers
[I'm growing on my balcony][22] shows which features are already available
[I'm growing on my balcony][23] shows which features are already available
in Material for MkDocs Insiders.
[22]: https://www.instagram.com/squidfunk/
[23]: https://www.instagram.com/squidfunk/
### Madame Jeanette
[:octicons-flame-24: Funding goal: __$500__][6] ·
:octicons-unlock-24: Status: _released_
:octicons-unlock-24: Status: _Generally available_
- [x] Improved search result grouping (pages + headings)
- [x] Improved search result relevance and scoring
@ -156,7 +158,7 @@ in Material for MkDocs Insiders.
### Prairie Fire
[:octicons-flame-24: Funding goal: __$1,000__][6] ·
:octicons-lock-24: Status: _exclusive_
:octicons-lock-24: Status: _Insiders only_
- [x] [Navigation can be grouped into sections][16]
- [x] [Navigation can be always expanded][17]
@ -167,16 +169,16 @@ in Material for MkDocs Insiders.
### Bhut Jolokia
[:octicons-flame-24: Funding goal: __$1,500__][6] ·
:octicons-lock-24: Status: _exclusive_
:octicons-lock-24: Status: _Insiders only_
- [x] [Support for Admonitions as inline blocks][21]
- [x] [Support for deploying multiple versions][13]
- [ ] Support for deploying multiple languages
- [x] [Support for deploying multiple languages][22]
### Black Pearl
[:octicons-flame-24: Funding goal: __$2,000__][6] ·
:octicons-lock-24: Status: _exclusive_
:octicons-lock-24: Status: _Insiders only_
- [x] [Support for user-toggleable themes (light/dark mode switch)][12]
- [ ] Support for user-toggleable code-block styles (light/dark mode switch)
@ -185,7 +187,7 @@ in Material for MkDocs Insiders.
### Biquinho Vermelho
[:octicons-flame-24: Funding goal: __$2,500__][6] ·
:octicons-lock-24: Status: _exclusive_
:octicons-lock-24: Status: _Insiders only_
- [x] [Search suggestions help to save keystrokes][14]
- [x] [Highlighting of matched search terms in content area][15]
@ -197,7 +199,7 @@ in Material for MkDocs Insiders.
### Caribbean Red
[:octicons-flame-24: Funding goal: __$3,000__][6] ·
:octicons-lock-24: Status: _exclusive_
:octicons-lock-24: Status: _Insiders only_
- [x] [Remove _Made with Material for MkDocs_ from footer][11]
- [ ] Brand-new and exclusive vertical layout
@ -215,10 +217,10 @@ improvements (e.g. search) do not require any changes to existing configuration.
This means that your users will be able to build the docs locally with the
regular version and when they push their changes to CI/CD, they will be built
with Material for MkDocs Insiders. For this reason, it's recommended to
[install Insiders][23] only in CI, as you don't want to expose your `GH_TOKEN`
[install Insiders][24] only in CI, as you don't want to expose your `GH_TOKEN`
to users.
[23]: publishing-your-site.md#github-pages
[24]: publishing-your-site.md#github-pages
### Terms
@ -228,7 +230,7 @@ terms?_
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][24]. However, we kindly ask you to respect the following
by the [MIT license][25]. However, we kindly ask you to respect the following
guidelines:
- Please __don't distribute the source code__ from Material for MkDocs Insiders.
@ -239,7 +241,7 @@ guidelines:
- If you cancel your subscription, you're removed as a collaborator and will
miss out on future updates of Material for MkDocs 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][25]__.
Just remember that __[GitHub deletes private forks][26]__.
[24]: license.md
[25]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
[25]: license.md
[26]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

View File

@ -84,23 +84,70 @@ as [documented here][2]._
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html
[2]: setting-up-navigation.md#slugify
### Site search language
### Site language selector
[:octicons-file-code-24: Source][3] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
If your documentation is available in multiple languages, a _language selector_
can be added to the header next to the search bar. Languages can be defined via
`mkdocs.yml`:
``` yaml
extra:
alternate:
- name: English
link: https://squidfunk.github.io/mkdocs-material-insiders/en/
lang: en
- name: Deutsch
link: https://squidfunk.github.io/mkdocs-material-insiders/de/
lang: de
- name: 日本語
link: https://squidfunk.github.io/mkdocs-material-insiders/jp/
lang: jp
```
This will render a language selector in the header next to the search bar:
[![Language selection][4]][4]
[3]: ../insiders.md
[4]: ../assets/screenshots/language-selection.png
This assumes that your project is structured into multiple subfolders, each of
which contain the entire documentation for a given language, e.g.:
``` sh
.
├─ en/
│ ├─ docs/
│ └─ mkdocs.yml
├─ de/
│ ├─ docs/
│ └─ mkdocs.yml
└─ jp/
├─ docs/
└─ mkdocs.yml
```
### Site search language
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _automatically set_
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][4] to provide this
functionality. See the guide detailing how to [set up site search][5] for
work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
functionality. See the guide detailing how to [set up site search][7] for
more information.
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
[4]: https://github.com/MihaiValentin/lunr-languages
[5]: setting-up-site-search.md
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108
[6]: https://github.com/MihaiValentin/lunr-languages
[7]: setting-up-site-search.md
### Directionality
[:octicons-file-code-24: Source][6] ·
[:octicons-file-code-24: Source][8] ·
:octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also
@ -132,7 +179,7 @@ directionality:
})
</script>
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185
## Customization
@ -142,7 +189,7 @@ directionality:
:octicons-mortar-board-24: Difficulty: _easy_
If you want to customize some (or all) of the translations for your language,
you may follow the guide on [theme extension][7] and create a new partial in
you may follow the guide on [theme extension][9] and create a new partial in
`partials/language`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial.
@ -161,4 +208,4 @@ theme:
language: en-custom
```
[7]: ../customization.md#extending-the-theme
[9]: ../customization.md#extending-the-theme

View File

@ -33,7 +33,7 @@ extra:
This will render a version selector in the header next to the title of your
project:
[![Versioning][3]][3]
[![Version selection][3]][3]
[Try this feature][4]{: .md-button .md-button--primary }