starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-07-24 14:53:45 -04:00
Code Issues Packages Projects Releases Wiki Activity

Added guide for navigation configuration

Browse Source
This commit is contained in:
squidfunk
2020-07-17 13:08:27 +02:00
parent b652bdad59
commit 9cc396315c
23 changed files with 285 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/guides/changing-colors.md
View File

@@ -6,7 +6,7 @@ template: overrides/main.html
As any good Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be adjusted with a few lines of CSS to
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand identity by using [CSS variables][2].
[1]: http://www.materialui.co/colors
@@ -52,11 +52,11 @@ scheme:
<script>
var buttons = document.querySelectorAll("button[data-md-color-scheme]")
buttons.forEach(function(button) {
var attr = "data-md-color-scheme"
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-scheme")
document.body.setAttribute("data-md-color-scheme", attr)
var name = document.querySelector("#__code_0 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = this.getAttribute(attr)
name.textContent = attr
})
})
</script>
@@ -130,11 +130,11 @@ color:
<script>
var buttons = document.querySelectorAll("button[data-md-color-primary]")
buttons.forEach(function(button) {
var attr = "data-md-color-primary"
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-primary")
document.body.setAttribute("data-md-color-primary", attr)
var name = document.querySelector("#__code_2 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = this.getAttribute(attr)
name.textContent = attr.replace("-", " ")
})
})
</script>
@@ -192,17 +192,27 @@ color:
<script>
var buttons = document.querySelectorAll("button[data-md-color-accent]")
buttons.forEach(function(button) {
var attr = "data-md-color-accent"
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-accent")
document.body.setAttribute("data-md-color-accent", attr)
var name = document.querySelector("#__code_3 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = this.getAttribute(attr)
name.textContent = attr.replace("-", " ")
})
})
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
---
!!! warning "Accessibility – not all color combinations work well"
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_), so make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
## Customization
Material for MkDocs implements colors using [CSS variables][6] (custom
@@ -267,16 +277,7 @@ colors or neutral colors:
```
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[7]: ../getting-started/customization.md#additional-stylesheets
[7]: ../customization.md#additional-stylesheets
[8]: ../extensions/codehilite.md
[9]: ../extensions/admonition.md
## Caveats
!!! warning "Accessibility – not all color combinations work well"
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_), so make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.

8
docs/guides/changing-the-fonts.md
View File

@@ -27,7 +27,7 @@ theme:
text: Roboto
```
The typeface will be loaded in 300, 400, *400i* and **700**.
The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L120-L139
[3]: https://fonts.google.com/specimen/Roboto
@@ -93,6 +93,6 @@ The font can then be configured to be used as the regular or proportional font:
}
```
[5]: ../getting-started/data-privacy.md
[6]: ../getting-started/customization.md#overriding-blocks
[7]: ../getting-started/customization.md#additional-stylesheets
[5]: ../data-privacy.md
[6]: ../customization.md#overriding-blocks
[7]: ../customization.md#additional-stylesheets

33
docs/guides/changing-the-language.md
View File

@@ -5,9 +5,8 @@ template: overrides/main.html
# Changing the language
Material for MkDocs supports internationalization (i18n) and provides
translation keys for all template variables and labels in 40+ languages.
Additionally, search can be configured to use a language-specific stemmer
(if available).
translations for template variables and labels in 40+ languages. Additionally,
search can be configured to use a language-specific stemmer (if available).
## Configuration
@@ -89,11 +88,25 @@ The following languages are supported:
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html
### Directionality
### Site search
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: best match
for `theme.language`, automatically set
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][3] to provide this
functionality. See the [search plugin documentation][4] for more information.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
[3]: https://github.com/MihaiValentin/lunr-languages
[4]: ../plugins/search.md#language
### Directionality
[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: best match
for `theme.language`, automatically set
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) directionality which is inferred from the
selected language, but can also be set with:
@@ -127,17 +140,13 @@ directionality:
<script>
var buttons = document.querySelectorAll("button[data-md-dir]")
buttons.forEach(function(button) {
var attr = "data-md-dir"
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir")
document.body.dir = attr
var name = document.querySelector("#__code_1 code span:nth-child(5)")
document.body.dir = this.getAttribute(attr)
name.textContent = this.getAttribute(attr)
name.textContent = attr
})
})
</script>
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L180
### Search
TBD
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L168

0
docs/guides/navigation-structure.md
View File

183
docs/guides/navigation.md Normal file
View File

@@ -0,0 +1,183 @@
---
template: overrides/main.html
---
# Navigation
A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides several options to configure the
behavior of navigational elements, some of those through _feature flags_.
## Configuration
### Instant loading
[:octicons-file-code-24: Source][1] · :octicons-beaker-24: Experimental ·
:octicons-unlock-24: Feature flag
When _instant loading_ is activated, clicks on all internal links will be
intercepted and dispatched via [XHR][2] without fully reloading the page. It
can be enabled from `mkdocs.yml` with:
``` yaml
theme:
features:
- instant
```
The resulting page is parsed and injected and all event handlers and components
are automatically rebound. This means that __Material for MkDocs behaves like a
Single Page Application__, which is especially useful for large documentation
sites that come with a huge search index, as the search index will now remain
intact in-between document switches.
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Tabs navigation
[:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag
When _tabs_ are activated, top-level sections are rendered in a menu layer
below the header on big screens (but not when the sidebar is hidden). It can be
enabled from `mkdocs.yml` with:
``` yaml
theme:
features:
- tabs
```
Note that all __top-level pages__ (i.e. all top-level entries that directly
refer to an `*.md` file) defined inside the `nav` entry of `mkdocs.yml` will be
grouped under the first tab which will receive the title of the first page.
This means that there will effectively be no collapsible subsections for the
first tab, because each subsection is rendered as another tab. If you want more
fine-grained control, _i.e. collapsible subsections for the first tab_, you can
use __top-level sections__, so that the top-level is entirely made up of
sections. This is illustrated in the following example:
=== "Top-level pages"
``` yaml
nav:
- Tab 1
- Page 1.1
- Tab 2:
- Page 2.1
- Page 2.2
- Page 1.2
```
=== "Top-level sections"
``` yaml
nav:
- Tab 1:
- Page 1.1
- Page 1.2
- Tab 2:
- Page 2.1
- Page 2.2
```
Note that tabs are only shown for larger screens, so make sure that navigation
is plausible on mobile devices. As another example, see the [`mkdocs.yml`][4]
used to render these pages.
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
### Table of contents
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
The [Table of Contents][7] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance.
`permalink`
: This options adds an anchor link containing the paragraph symbol `` or
another custom symbol at the end of each headline, exactly like on the page
you're currently viewing, which Material for MkDocs will make appear on
hover:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
=== "Link"
``` yaml
markdown_extensions:
- toc:
permalink: Link
```
`slugify`
: This option allows for customization of the slug function. For some
languages, the standard slug function may not produce good and readable
identifiers. Consider using another slug function like for example those
from [PyMdown Extensions][8]:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: pymdownx.slugs.uslugify
```
=== "Casing"
``` yaml
markdown_extensions:
- toc:
slugify: pymdownx.slugs.uslugify_cased
```
`toc_depth`
: Define the range of levels to be included in the table of contents. This is
especially useful for project documentation with deeply structured headings
to decrease the length of the table of contents, or to remove the table of
contents altogether:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may yield weird results. Use them at your own risk._
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[6]: https://python-markdown.github.io/extensions/toc/
[7]: https://python-markdown.github.io/extensions/toc/#usage
[8]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/