mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Finished rewrite of reference documentation
This commit is contained in:
squidfunk
parent
b6cd73e083
commit
e425b99362
@ -110,7 +110,7 @@ import tensorflow as tf
|
||||
|
||||
Code annotations can be placed anywhere in a code block where a comment for the
|
||||
language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
|
||||
`#!js /* ... */`, for Yaml `#!yaml # ...`, etc.[^1]
|
||||
`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]
|
||||
|
||||
[^1]:
|
||||
Code annotations require syntax highlighting with [Pygments] – they're
|
||||
@ -202,7 +202,7 @@ at `1`, regardless of the starting line number specified as part of
|
||||
items[j], items[j + 1] = items[j + 1], items[j]
|
||||
```
|
||||
|
||||
=== "Line ranges"
|
||||
=== "Line number ranges"
|
||||
|
||||
_Example_:
|
||||
|
||||
|
||||
@ -6,57 +6,60 @@ template: overrides/main.html
|
||||
|
||||
In HTML, `meta` tags allow to provide additional metadata for a document, e.g.
|
||||
page titles and descriptions, additional assets to be loaded, and [Open Graph]
|
||||
[1] data. While arbitrary metadata can always be added via [customization][2],
|
||||
metadata. While arbitrary `meta` tags can always be added via [customization],
|
||||
some common `meta` tags can be configured.
|
||||
|
||||
[1]: https://ogp.me/
|
||||
[2]: #customization
|
||||
[Open Graph]: https://ogp.me/
|
||||
[customization]: #customization
|
||||
|
||||
## Configuration
|
||||
|
||||
### Metadata
|
||||
|
||||
The [Metadata][3] extension, which is part of the standard Markdown library,
|
||||
adds the ability to add [front matter][4] to a document and can be enabled via
|
||||
`mkdocs.yml`:
|
||||
This configuration adds support for setting custom page titles and descriptions
|
||||
in [front matter], as well as for using custom metadata in templates. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- meta
|
||||
```
|
||||
|
||||
Front matter is written as a series of key-value pairs at the beginning of the
|
||||
Markdown document, delimited by a blank line which ends the YAML context.
|
||||
See additional configuration options:
|
||||
|
||||
[3]: https://python-markdown.github.io/extensions/meta_data/
|
||||
[4]: https://jekyllrb.com/docs/front-matter/
|
||||
- [Metadata]
|
||||
|
||||
[front matter]: https://jekyllrb.com/docs/front-matter/
|
||||
[Metadata]: ../setup/extensions/python-markdown.md#metadata
|
||||
|
||||
## Usage
|
||||
|
||||
### Setting the page title
|
||||
|
||||
If the [Metadata][5] extension is enabled, the page title can be overridden on
|
||||
a per-document basis with custom front matter:
|
||||
When [Metadata] is enabled, the page title can be overridden on a per-document
|
||||
basis with custom front matter. Add the following lines at the top of a Markdown
|
||||
file:
|
||||
|
||||
``` bash
|
||||
---
|
||||
title: Lorem ipsum dolor sit amet
|
||||
title: Lorem ipsum dolor sit amet # (1)
|
||||
---
|
||||
|
||||
# Document title
|
||||
...
|
||||
```
|
||||
|
||||
This will set the `title` tag inside the document `head` for the current page
|
||||
to the provided value. Note that the site title is appended using a dash as a
|
||||
separator, which is the default behavior.
|
||||
1. This will set the [`title`][title] inside the HTML document's [`head`][head]
|
||||
for the generated page to this value. Note that the site title, which is set
|
||||
via [`site_name`][site_name], is appended with a dash.
|
||||
|
||||
[5]: #metadata
|
||||
[title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
|
||||
[head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
|
||||
[site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
|
||||
|
||||
### Setting the page description
|
||||
|
||||
If the [Metadata][5] extension is enabled, the page description can also be
|
||||
overridden on a per-document basis with custom front matter:
|
||||
When [Metadata] is enabled, the page description can also be overridden on a
|
||||
per-document basis with custom front matter. Add the following lines at the top
|
||||
of a Markdown file:
|
||||
|
||||
``` bash
|
||||
---
|
||||
@ -70,47 +73,41 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
|
||||
This will set the `meta` tag containing the site description inside the
|
||||
document `head` for the current page to the provided value.
|
||||
|
||||
<div class="mdx-deprecated" markdown>
|
||||
|
||||
### Adding a web app manifest
|
||||
|
||||
A [web app manifest][6] is a simple JSON file that specifies how your web
|
||||
:octicons-archive-24: Deprecated ·
|
||||
[:octicons-tag-24: 3.1.0 ... present][web app manifest support] ·
|
||||
:octicons-trash-24: 8.0.0
|
||||
|
||||
A [web app manifest] is a simple JSON file that specifies how your web
|
||||
application should behave when installed on the user's mobile device or desktop,
|
||||
which can be set via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
manifest: manifest.webmanifest
|
||||
manifest: manifest.webmanifest # (1)
|
||||
```
|
||||
|
||||
[6]: https://developers.google.com/web/fundamentals/web-app-manifest/
|
||||
1. This option was deprecated, as it's not widely used and the same behavior
|
||||
can be achieved with [theme extension].
|
||||
|
||||
[web app manifest]: https://developers.google.com/web/fundamentals/web-app-manifest/
|
||||
[web app manifest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/3.1.0
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
|
||||
</div>
|
||||
|
||||
## Customization
|
||||
|
||||
### Displaying the metadata
|
||||
|
||||
Sometimes it's useful to be able to display the medatada in the page body, e.g.
|
||||
print the name of the page author at the bottom of the page. To achieve that,
|
||||
you can [extend the theme][7] by adding the following contents to `main.html`:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block content %}
|
||||
{{ super() }}
|
||||
{% if page and page.meta and page.meta.author %}
|
||||
<p><small>Author: {{ page.meta.author }}</small></p>
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
[7]: ../customization.md#extending-the-theme
|
||||
|
||||
### Custom meta tags
|
||||
### Using metadata in templates
|
||||
|
||||
#### on all pages
|
||||
|
||||
In order to add custom `meta` tags to your document, you can [extend the theme
|
||||
][7] and simply [override the `extrahead` block][8], e.g. to add indexing
|
||||
policies for search engines:
|
||||
][theme extension] and [override the `extrahead` block][override block],
|
||||
e.g. to add indexing policies for search engines via the `robots` property:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
@ -120,7 +117,7 @@ policies for search engines:
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
[8]: ../customization.md#overriding-blocks-recommended
|
||||
[override block]: ../customization.md#overriding-blocks-recommended
|
||||
|
||||
#### on a single page
|
||||
|
||||
@ -140,63 +137,9 @@ template override, e.g.:
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
You can now use `robots` exactly like [`title`][9] and [`description`][10] to
|
||||
set values. Note that in this case, the template defines an `else` branch, which
|
||||
would set a default if none was given.
|
||||
You can now use `robots` exactly like [`title`][title] and
|
||||
[`description`][description] to set values. Note that in this case, the
|
||||
template defines an `else` branch, which would set a default if none was given.
|
||||
|
||||
[9]: #setting-the-page-title
|
||||
[10]: #setting-the-page-description
|
||||
|
||||
### Social meta tags
|
||||
|
||||
Some further examples, including [Open Graph][1] and [Twitter Cards][11]:
|
||||
|
||||
=== "Open Graph"
|
||||
|
||||
``` html
|
||||
{% block extrahead %}
|
||||
{% set title = config.site_name %}
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% endif %}
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:title" content="{{ title }}" />
|
||||
<meta property="og:description" content="{{ config.site_description }}" />
|
||||
<meta property="og:url" content="{{ page.canonical_url }}" />
|
||||
<meta property="og:image" content="<url>" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<meta property="og:image:height" content="630" />
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
=== "Twitter Cards"
|
||||
|
||||
``` html
|
||||
{% block extrahead %}
|
||||
{% set title = config.site_name %}
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% endif %}
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:site" content="<username>" />
|
||||
<meta name="twitter:creator" content="<username>" />
|
||||
<meta name="twitter:title" content="{{ title }}" />
|
||||
<meta name="twitter:description" content="{{ config.site_description }}" />
|
||||
<meta name="twitter:image" content="<url>" />
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
!!! tip "Automatically generated social cards"
|
||||
|
||||
If you don't want to bother with meta tags and social cards yourself, you
|
||||
can let the [built-in social cards plugin][12] do the work for you, which
|
||||
generates beautiful image previews for social media automatically during
|
||||
the build.
|
||||
|
||||
[11]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
|
||||
[12]: ../setup/setting-up-social-cards.md
|
||||
[title]: #setting-the-page-title
|
||||
[description]: #setting-the-page-description
|
||||
|
||||
@ -1,152 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Variables
|
||||
|
||||
Macros and variables are powerful tools to parametrize Markdown files, as they
|
||||
allow to perform Jinja templating directly from Markdown. This is especially
|
||||
useful to include technical data from other files and add central variables via
|
||||
`mkdocs.yml`.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Macros
|
||||
|
||||
The [macros][1] plugin adds support to reference variables and call macros and
|
||||
supports Jinja templating directly from Markdown. It can be installed with
|
||||
`pip`:
|
||||
|
||||
```
|
||||
pip install mkdocs-macros-plugin
|
||||
```
|
||||
|
||||
Then, add the following to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- macros
|
||||
```
|
||||
|
||||
[1]: https://github.com/fralau/mkdocs_macros_plugin
|
||||
|
||||
## Usage
|
||||
|
||||
### Using predefined variables
|
||||
|
||||
A set of predefined variables is enabled by default and can be used from
|
||||
Markdown, including data from `mkdocs.yml`. More specifically, predefined
|
||||
variables fall into the following categories:
|
||||
|
||||
- `config.*`: configuration parameters from `mkdocs.yml`
|
||||
- `page.*`: metadata and content of current page
|
||||
- `navigation.*`: list of all pages and sections
|
||||
- `environment.*`: underlying operating system
|
||||
- `git.*`: git-related information, if available
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
Welcome to {{ config.site_name }}!
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
``` markdown
|
||||
Welcome to Material for MkDocs!
|
||||
```
|
||||
|
||||
A list of all predefined variables can be printed with:
|
||||
|
||||
```
|
||||
{{ macros_info() }}
|
||||
```
|
||||
|
||||
### Using custom variables
|
||||
|
||||
All data defined under `extra` in `mkdocs.yml` is automatically exposed as a
|
||||
variable and can be used from the template. This enables centralized parameter
|
||||
storage and management.
|
||||
|
||||
_Example_:
|
||||
|
||||
=== "`docs/page.md`"
|
||||
|
||||
```` markdown
|
||||
The unit price is {{ unit.price }}
|
||||
````
|
||||
|
||||
=== "`mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
unit:
|
||||
price: 12.50
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
The unit price is 12.50.
|
||||
|
||||
### Using variables in snippets
|
||||
|
||||
The [macros][2] plugin can be used to allow variables in snippets, which is not
|
||||
possible with the [Snippets][3] extension alone. Add the snippets location to
|
||||
the plugin configuration in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search
|
||||
- macros:
|
||||
include_dir: snippets
|
||||
```
|
||||
|
||||
In your Markdown file, include snippets with Jinja's [`include`][4] function:
|
||||
|
||||
``` markdown
|
||||
{% include "definitions.md" %}
|
||||
```
|
||||
|
||||
_Example_:
|
||||
|
||||
=== "`snippets/definitions.md`"
|
||||
|
||||
``` markdown
|
||||
The unit price is {{ page.meta.unit.price }}
|
||||
```
|
||||
|
||||
=== "`docs/page-1.md`"
|
||||
|
||||
``` markdown
|
||||
---
|
||||
unit:
|
||||
price: 12.50
|
||||
---
|
||||
|
||||
{% include "definitions.md" %}
|
||||
```
|
||||
|
||||
=== "`docs/page-2.md`"
|
||||
|
||||
``` markdown
|
||||
---
|
||||
unit:
|
||||
price: 25.00
|
||||
---
|
||||
|
||||
{% include "definitions.md" %}
|
||||
```
|
||||
|
||||
[2]: #macros
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
|
||||
[4]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom macros
|
||||
|
||||
The [macros][1] plugin allows to define custom macros, which can then be used
|
||||
from Markdown files. See the [official documentation][5] for more information
|
||||
how to define custom macros.
|
||||
|
||||
[5]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/python/
|
||||
@ -143,3 +143,52 @@ default values.
|
||||
[11]: ../reference/meta-tags.md#metadata
|
||||
[12]: ../reference/meta-tags.md#setting-the-page-title
|
||||
[13]: ../reference/meta-tags.md#setting-the-page-description
|
||||
|
||||
### Using social media meta tags
|
||||
|
||||
The [built-in social cards plugin] generates beautiful image previews for social
|
||||
media during the build and sets all necessary `meta` tags, equivalent to the
|
||||
following two customizations:
|
||||
|
||||
=== ":material-graph: Open Graph"
|
||||
|
||||
``` html
|
||||
{% block extrahead %}
|
||||
{% set title = config.site_name %}
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% endif %}
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:title" content="{{ title }}" />
|
||||
<meta property="og:description" content="{{ config.site_description }}" />
|
||||
<meta property="og:url" content="{{ page.canonical_url }}" />
|
||||
<meta property="og:image" content="<url>" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<meta property="og:image:height" content="630" />
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
=== ":fontawesome-brands-twitter: Twitter Cards"
|
||||
|
||||
``` html
|
||||
{% block extrahead %}
|
||||
{% set title = config.site_name %}
|
||||
{% if page and page.meta and page.meta.title %}
|
||||
{% set title = title ~ " - " ~ page.meta.title %}
|
||||
{% elif page and page.title and not page.is_homepage %}
|
||||
{% set title = title ~ " - " ~ page.title | striptags %}
|
||||
{% endif %}
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:site" content="<username>" />
|
||||
<meta name="twitter:creator" content="<username>" />
|
||||
<meta name="twitter:title" content="{{ title }}" />
|
||||
<meta name="twitter:description" content="{{ config.site_description }}" />
|
||||
<meta name="twitter:image" content="<url>" />
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
[Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
|
||||
[built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
1
material/assets/stylesheets/main.76ff9fe5.min.css.map
Normal file
1
material/assets/stylesheets/main.76ff9fe5.min.css.map
Normal file
File diff suppressed because one or more lines are too long
@ -39,7 +39,7 @@
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
{% block styles %}
|
||||
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.24c991ad.min.css' | url }}">
|
||||
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.76ff9fe5.min.css' | url }}">
|
||||
{% if config.theme.palette %}
|
||||
{% set palette = config.theme.palette %}
|
||||
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">
|
||||
|
||||
2
material/overrides/assets/stylesheets/main.5136944a.min.css
vendored
Normal file
2
material/overrides/assets/stylesheets/main.5136944a.min.css
vendored
Normal file
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -3,7 +3,7 @@
|
||||
-#}
|
||||
{% extends "base.html" %}
|
||||
{% block extrahead %}
|
||||
<link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.9307850e.min.css' | url }}">
|
||||
<link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.5136944a.min.css' | url }}">
|
||||
{% endblock %}
|
||||
{% block announce %}
|
||||
<a href="https://twitter.com/squidfunk">
|
||||
|
||||
@ -215,7 +215,6 @@ nav:
|
||||
- Lists: reference/lists.md
|
||||
- MathJax: reference/mathjax.md
|
||||
- Meta tags: reference/meta-tags.md
|
||||
- Variables: reference/variables.md
|
||||
- Insiders:
|
||||
- insiders/index.md
|
||||
- Getting started:
|
||||
|
||||
@ -104,6 +104,18 @@
|
||||
}
|
||||
}
|
||||
|
||||
// Deprecation
|
||||
.mdx-deprecated {
|
||||
opacity: 0.5;
|
||||
transition: opacity 250ms;
|
||||
|
||||
// Deprecation on focus/hover
|
||||
&:focus-within,
|
||||
&:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
}
|
||||
|
||||
// Two-column layout
|
||||
.mdx-columns {
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user