mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Updated documentation for Material for MkDocs Insiders
This commit is contained in:
parent
84251be688
commit
dbee5ede5e
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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 }
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user