mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2026-07-22 05:53:03 -04:00
Added guide for navigation configuration
This commit is contained in:
squidfunk
@@ -34,7 +34,7 @@ This will create the following structure:
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
[1]: ../getting-started.md
|
||||
[1]: getting-started.md
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -66,7 +66,7 @@ icons and much more:
|
||||
* [Changing colors][3]
|
||||
* [Changing the fonts][4]
|
||||
* [Changing the language][5]
|
||||
* [Navigation structure][6]
|
||||
* [Navigation][6]
|
||||
* [Syntax highlighting][7]
|
||||
* [Adding a landing page][8]
|
||||
* [Adding an announcement bar][9]
|
||||
@@ -75,18 +75,18 @@ icons and much more:
|
||||
* [Adding site analytics][12]
|
||||
* [Adding a comment system][13]
|
||||
|
||||
[2]: ../getting-started.md#installation
|
||||
[3]: ../guides/changing-colors.md
|
||||
[4]: ../guides/changing-the-fonts.md
|
||||
[5]: ../guides/changing-the-language.md
|
||||
[6]: ../guides/navigation-structure.md
|
||||
[7]: ../guides/syntax-highlighting.md
|
||||
[8]: ../guides/adding-a-landing-page.md
|
||||
[9]: ../guides/adding-an-announcement-bar.md
|
||||
[10]: ../guides/adding-icons-and-emojis.md
|
||||
[11]: ../guides/adding-footer-links.md
|
||||
[12]: ../guides/adding-site-analytics.md
|
||||
[13]: ../guides/adding-a-comment-system.md
|
||||
[2]: getting-started.md#installation
|
||||
[3]: guides/changing-colors.md
|
||||
[4]: guides/changing-the-fonts.md
|
||||
[5]: guides/changing-the-language.md
|
||||
[6]: guides/navigation.md
|
||||
[7]: guides/syntax-highlighting.md
|
||||
[8]: guides/adding-a-landing-page.md
|
||||
[9]: guides/adding-an-announcement-bar.md
|
||||
[10]: guides/adding-icons-and-emojis.md
|
||||
[11]: guides/adding-footer-links.md
|
||||
[12]: guides/adding-site-analytics.md
|
||||
[13]: guides/adding-a-comment-system.md
|
||||
|
||||
## Previewing as you write
|
||||
|
||||
@@ -117,7 +117,7 @@ Point your browser to [localhost:8000][14] and you should see:
|
||||
[![Creating your site][15]][14]
|
||||
|
||||
[14]: http://localhost:8000
|
||||
[15]: ../assets/guides/creating-your-site.png
|
||||
[15]: assets/guides/creating-your-site.png
|
||||
|
||||
## Building your site
|
||||
|
||||
@@ -135,7 +135,7 @@ theme. This can be done with any file.
|
||||
### Overriding blocks
|
||||
|
||||
Besides overriding partials, it's also possible to override (and extend) so
|
||||
called *blocks*, which are defined inside the templates and wrap specific
|
||||
called _blocks_, which are defined inside the templates and wrap specific
|
||||
features. To override a block, create a `main.html` inside the `overrides`
|
||||
directory and define the block, e.g.:
|
||||
|
||||
@@ -152,11 +152,11 @@ Material for MkDocs provides the following template blocks:
|
||||
| Block name | Wrapped contents |
|
||||
| ------------ | ----------------------------------------------- |
|
||||
| `analytics` | Wraps the Google Analytics integration |
|
||||
| `announce` | Wraps the Announcement bar |
|
||||
| `announce` | Wraps the announcement bar |
|
||||
| `config` | Wraps the JavaScript application config |
|
||||
| `content` | Wraps the main content |
|
||||
| `disqus` | Wraps the disqus integration |
|
||||
| `extrahead` | Empty block to define additional meta tags |
|
||||
| `disqus` | Wraps the Disqus integration |
|
||||
| `extrahead` | Empty block to add custom meta tags |
|
||||
| `fonts` | Wraps the font definitions |
|
||||
| `footer` | Wraps the footer with navigation and copyright |
|
||||
| `header` | Wraps the fixed header bar |
|
||||
@@ -230,7 +230,7 @@ in front of you.
|
||||
|
||||
[10]: http://localhost:8000
|
||||
|
||||
### Build process
|
||||
### Building the theme
|
||||
|
||||
When you're finished making your changes, you can build the theme by invoking:
|
||||
|
||||
@@ -25,12 +25,12 @@ theme:
|
||||
font: false
|
||||
```
|
||||
|
||||
When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
|
||||
Neue** and **Monaco** with their corresponding fall backs, relying on system
|
||||
When Google Fonts are disabled, Material for MkDocs will default to __Helvetica
|
||||
Neue__ and __Monaco__ with their corresponding fall backs, relying on system
|
||||
fonts. You can easily include your own, self-hosted webfont by [overriding][4]
|
||||
the `fonts` block.
|
||||
|
||||
[2]: ../guides/changing-the-fonts.md
|
||||
[2]: guides/changing-the-fonts.md
|
||||
[3]: https://github.com/google/fonts/issues/1495
|
||||
[4]: customization.md#overriding-template-blocks
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Permalinks
|
||||
|
||||
Permalinks are a feature of the [Table of Contents][1] extension, which is part
|
||||
of the standard Markdown library. The extension inserts an anchor at the end of
|
||||
each headline, which makes it possible to directly link to a specific section
|
||||
of the document.
|
||||
|
||||
[1]: https://python-markdown.github.io/extensions/toc/
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
This will add a link containing the paragraph 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. In order to change the text of the
|
||||
permalink, a string can be passed, e.g.:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: Link
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
When enabled, permalinks are inserted automatically.
|
||||
@@ -57,7 +57,7 @@ extra_javascript:
|
||||
```
|
||||
|
||||
If you want to override the default MathJax configuration, you can do this by
|
||||
adding another JavaScript file **before** the MathJax runtime which contains
|
||||
adding another JavaScript file __before__ the MathJax runtime which contains
|
||||
the MathJax configuration, e.g.:
|
||||
|
||||
``` js
|
||||
@@ -130,7 +130,7 @@ Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
|
||||
|
||||
### BetterEm
|
||||
|
||||
[BetterEm][6] improves the handling of emphasis markup (**bold** and *italic*)
|
||||
[BetterEm][6] improves the handling of emphasis markup (__bold__ and _italic_)
|
||||
within Markdown by providing a more sophisticated parser for better detecting
|
||||
start and end tokens. Read the documentation for [usage notes][7].
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
|
||||
[1]: https://www.mkdocs.org
|
||||
[2]: #with-pip
|
||||
[3]: #with-docker
|
||||
[4]: getting-started/troubleshooting.md
|
||||
[4]: troubleshooting.md
|
||||
|
||||
## Installation
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
183
docs/guides/navigation.md
Normal file
183
docs/guides/navigation.md
Normal 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/
|
||||
@@ -158,8 +158,8 @@ The templates have undergone a set of changes to make them future-proof. If
|
||||
you've used theme extension to override a block or template, make sure that it
|
||||
matches the new structure:
|
||||
|
||||
- If you've overridden a **block**, check `base.html` for potential changes
|
||||
- If you've overridden a **template**, check the respective `*.html` file for
|
||||
- If you've overridden a __block__, check `base.html` for potential changes
|
||||
- If you've overridden a __template__, check the respective `*.html` file for
|
||||
potential changes
|
||||
|
||||
#### `base.html`
|
||||
|
||||
@@ -21,14 +21,14 @@ When you're running the pre-installed version of Python on macOS, `pip` tries
|
||||
to install packages in a folder for which your user might not have the adequate
|
||||
permissions. There are three possible solutions for this:
|
||||
|
||||
1. **Installing in a virtual environment**: Virtual environments provide an easy
|
||||
1. __Installing in a virtual environment__: Virtual environments provide an easy
|
||||
way of encapsulation.
|
||||
|
||||
1. **Installing in user space**: Provide the `--user` flag to the install
|
||||
2. __Installing in user space__: Provide the `--user` flag to the install
|
||||
command and `pip` will install the package in a user-site location. Note
|
||||
that while this is not a global installation, it's still not
|
||||
|
||||
2. **Switching to a homebrewed Python**: Upgrade your Python installation to a
|
||||
3. __Switching to a homebrewed Python__: Upgrade your Python installation to a
|
||||
self-contained solution by installing Python with Homebrew. This should
|
||||
eliminate a lot of problems you could be having with `pip`.
|
||||
|
||||
Reference in New Issue
Block a user