OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Documentation

Browse Source
This commit is contained in:
squidfunk 2022-10-02 16:36:47 +02:00
parent ee1e675da6
commit c44baee78d
12 changed files with 189 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/insiders/index.md
View File

@ -82,15 +82,17 @@ a handful of them, [thanks to our awesome sponsors]!
## What's in for me?
The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
access to 22 additional features__ that you can start using right away, and
access to 24 additional features__ that you can start using right away, and
which are currently exclusively available to sponsors:
<div class="mdx-columns" markdown>
- [x] [Navigation subtitles] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
- [x] [Tags plugin: allow list] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
- [x] [Blog plugin: custom index pages] :material-alert-decagram:{ .mdx-pulse title="Added on September 27, 2022" }
- [x] [Blog plugin: related links] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
- [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" }
- [x] [Blog plugin: related links]
- [x] [Blog plugin]
- [x] [Navigation status]
- [x] [Meta plugin]
- [x] [Tags plugin: additional indexes]
- [x] [Document contributors]
@ -293,14 +295,22 @@ are released for general availability.
- [x] [Blog plugin: related links]
- [x] [Blog plugin: custom index pages]
- [x] [Tags plugin: additional indexes]
- [ ] [Instant previews]
- [ ] Navigation subtitles
- [x] [Tags plugin: allow list]
- [x] [Navigation subtitles]
[Meta plugin]: ../reference/index.md#built-in-meta-plugin
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
[Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
[Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
#### $ 20,000 – Jalapeño
- [ ] [Instant previews]
- ... more to be announced
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
### Goals completed

57
docs/reference/index.md
View File

@ -5,7 +5,7 @@ template: overrides/main.html
# Reference
Material for MkDocs is packed with many great features that make technical
writing a pleasure. This section of the documentation explains how to set up
writing a joyful activity. This section of the documentation explains how to set up
a page, and showcases all available specimen that can be used directly from
within Markdown files.
@ -55,8 +55,10 @@ The following configuration options are available:
### Setting the page title
The page title can be overridden for a document with the front matter `title`
property. Add the following lines at the top of a Markdown file:
Each page has a designated title, which is used in the navigation sidebar, for
[social cards] and in other places. While MkDocs attempts to automatically
determine the title of a page in a [four step process], the title can also be
explicitly set with the front matter `title` property:
``` yaml
---
@ -67,18 +69,23 @@ title: Lorem ipsum dolor sit amet # (1)!
...
```
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.
1. This line sets the [`title`][title] inside the HTML document's
[`head`][head] for the generated page to the given value. Note that the
site title, which is set via [`site_name`][site_name], is appended with a
dash.
[social cards]: ../setup/setting-up-social-cards.md
[four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
[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
The page description can be overridden for a document with the front matter
`description` property. Add the following lines at the top of a Markdown file:
A Markdown file can include a description that is added to the `meta` tags of
a page, and is also used for [social cards]. It's a good idea to set a
[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
the author does not explicitly define a description for a Markdown file:
``` yaml
---
@ -89,9 +96,11 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
...
```
1. This will set the `meta` tag containing the site description inside the
1. This line sets the `meta` tag containing the description inside the
document `head` for the current page to the provided value.
[site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
### Setting the page icon
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
@ -99,7 +108,9 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
:octicons-beaker-24: Experimental
An icon can be assigned to each page, which is then rendered as part of the
navigation sidebar. Add the following lines at the top of a Markdown file:
navigation sidebar, as well as [navigation tabs], if enabled. Use the front
matter `icon` property to reference an icon, adding the following lines at the
top of a Markdown file:
``` yaml
---
@ -123,6 +134,7 @@ icon: material/emoticon-happy # (1)!
[Insiders]: ../insiders/index.md
[icon search]: icons-emojis.md#search
[navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
### Setting the page status
@ -150,9 +162,9 @@ extra:
new: Recently added
```
The page status can now be set for a document with the front matter `status`
property. For example, you can mark a page as `new` with the following lines at
the top of a Markdown file:
The page status can now be set with the front matter `status` property. For
example, you can mark a page as `new` with the following lines at the top of a
Markdown file:
``` yaml
---
@ -168,6 +180,25 @@ The following status identifiers are currently supported:
- :material-alert-decagram: – `new`
- :material-trash-can: – `deprecated`
### Setting the page subtitle
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.25.0][Insiders] ·
:octicons-beaker-24: Experimental
Each page can define a subtitle, which is then rendered below the title as part
of the navigation sidebar by using the front matter `subtitle` property, and
adding the following lines:
``` yaml
---
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---
# Document title
...
```
### Setting the page template
If you're using [theme extension] and created a new page template in the

2
docs/schema/extensions/markdown.json
View File

@ -118,7 +118,7 @@
},
"slugify": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.slugify",
"type": "string"
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"toc_depth": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.toc_depth",

2
docs/schema/extensions/pymdownx.json
View File

@ -159,12 +159,10 @@
"properties": {
"emoji_generator": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator",
"type": "string",
"default": "!!python/name:materialx.emoji.to_svg"
},
"emoji_index": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index",
"type": "string",
"default": "!!python/name:materialx.emoji.twemoji"
},
"options": {

6
docs/schema/plugins/blog.json
View File

@ -85,8 +85,7 @@
"post_slugify": {
"title": "Post slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
"type": "string",
"default": "!!python/name:pymdownx.slugs.uslugify"
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"post_slugify_separator": {
"title": "Post slugify separator",
@ -231,8 +230,7 @@
"categories_slugify": {
"title": "Categories slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
"type": "string",
"default": "!!python/name:pymdownx.slugs.uslugify"
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"categories_slugify_separator": {
"title": "Categories slugify separator",

26
docs/schema/plugins/tags.json
View File

@ -15,6 +15,12 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
"type": "object",
"properties": {
"enabled": {
"title": "Enable plugin",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled",
"type": "boolean",
"default": true
},
"tags_file": {
"title": "Markdown file to render tags index",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
@ -34,6 +40,26 @@
}
},
"additionalProperties": false
},
"tags_slugify": {
"title": "Tags slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify",
"default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
},
"tags_slugify_separator": {
"title": "Tags slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator",
"type": "string",
"default": "\"-\""
},
"tags_allowed": {
"title": "Tags allowed",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed",
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false

6
docs/setup/adding-a-comment-system.md
View File

@ -42,14 +42,14 @@ Before you can use [Giscus], you need to complete the following steps:
</script>
```
The by default empty [`comments.html`][comments] partial is the best place to
add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
The [`comments.html`][comments] partial (empty by default) is the best place to
add the snippet generated by [Giscus]. Follow the guide on [theme extension]
and [override the `comments.html` partial][overriding partials] with:
``` html hl_lines="3"
{% if page.meta.comments %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<!-- Insert generated code here -->
<!-- Insert generated snippet here -->
<!-- Synchronize Giscus theme with palette -->
<script>

2
docs/setup/adding-a-git-repository.md
View File

@ -311,7 +311,7 @@ them at your own risk.
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
#### Document authors :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
#### Document authors
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.19.0][Insiders] ·

4
docs/setup/extensions/python-markdown.md
View File

@ -258,7 +258,9 @@ The following configuration options are supported:
``` yaml
markdown_extensions:
- toc:
slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}
slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"

31
docs/setup/setting-up-a-blog.md
View File

@ -22,7 +22,7 @@ __Check out our [blog], which is created with the new [built-in blog plugin]!__
## Configuration
### Built-in blog plugin :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
### Built-in blog plugin
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.23.0][Insiders] ·
@ -248,7 +248,9 @@ The following configuration options are available for posts:
``` yaml
plugins:
- blog:
post_slugify: !!python/name:pymdownx.slugs.uslugify
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
@ -256,7 +258,7 @@ The following configuration options are available for posts:
``` yaml
plugins:
- blog:
post_slugify: !!python/name:pymdownx.slugs.uslugify_cased
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`post_slugify_separator`](#+blog.post_slugify_separator){ #+blog.post_slugify_separator }
@ -542,7 +544,9 @@ The following configuration options are available for category index generation:
``` yaml
plugins:
- blog:
categories_slugify: !!python/name:pymdownx.slugs.uslugify
categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
@ -550,7 +554,7 @@ The following configuration options are available for category index generation:
``` yaml
plugins:
- blog:
categories_slugify: !!python/name:pymdownx.slugs.uslugify_cased
categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`categories_slugify_separator`](#+blog.categories_slugify_separator){ #+blog.categories_slugify_separator }
@ -1028,7 +1032,7 @@ authors:
Categories are an excellent way for grouping your posts thematically on
dedicated index pages. This way, a user interested in a specific topic can
explore all of your posts on this topic. Make sure [categories] are enabled and
add them to the `categories` front matter property:
add them to the front matter `categories` property:
``` yaml
---
@ -1053,7 +1057,7 @@ the list.
#### Adding tags
Besides [categories], the [built-in blog plugin] also integrates with the
[built-in tags plugin]. If you add tags in the `tags` front matter property as
[built-in tags plugin]. If you add tags in the front matter `tags` property as
part of a post, the post is linked from the [tags index]:
``` yaml
@ -1079,7 +1083,7 @@ linked with their titles.
Related links offer the perfect way to prominently add a _further reading_
section to your post that is included in the left sidebar, guiding the user to
other destinations of your documentation. Use the `links` front matter property
other destinations of your documentation. Use the front matter `links` property
to add related links to a post:
``` yaml
@ -1153,7 +1157,7 @@ offers this capability as well.
Sometimes, however, the computed reading time might not feel accurate, or
result in odd and unpleasant numbers. For this reason, reading time can be
overridden and explicitly set with the `readtime` front matter property for a
overridden and explicitly set with the front matter `readtime` property for a
post:
``` yaml
@ -1189,8 +1193,8 @@ authors, and add a `.meta.yml` file to set common properties:
```
1. As already noted, you can also place a `.meta.yml` file in nested folders
of the `posts` directory. This file then can contain any front matter that
is also valid in posts, e.g.:
of the `posts` directory. This file then can define all front matter
properties that are valid in posts, e.g.:
``` yaml
authors:
@ -1267,8 +1271,7 @@ the [built-in blog plugin] would create it:
- [`categories_slugify`][categories_slugify]
You can now add arbitrary content to the newly created file, or set specific
page properties for this page via front matter, e.g. to change the
[page description]:
front matter properties for this page, e.g. to change the [page description]:
``` yaml
---
@ -1279,7 +1282,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
...
```
All posts belonging to the category will be automatically appended.
All post excerpts belonging to the category are automatically appended.
[add the category]: #adding-categories
[page description]: ../reference/index.md#setting-the-page-description

3
docs/setup/setting-up-site-analytics.md
View File

@ -233,7 +233,8 @@ The following properties are available for each rating:
### Hiding the feedback widget
The [feedback widget] can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file:
The [feedback widget] can be hidden for a document with the front matter `hide`
property. Add the following lines at the top of a Markdown file:
``` yaml
---

77
docs/setup/setting-up-tags.md
View File

@ -30,13 +30,24 @@ plugins:
The following configuration options are available:
[`enabled`](#+tags.enabled){ #+tags.enabled }
: :octicons-milestone-24: Default: `true` – This option specifies whether
the plugin is enabled when building your project. If you want to switch
the plugin off, you can disable it with the following lines:
``` yaml
plugins:
- tags:
enabled: false
```
[`tags_file`](#+tags.tags_file){ #+tags.tags_file }
: :octicons-milestone-24: Default: _none_ – This option specifies which page
should be used to render the tags index. See the section on [adding a tags
index][tags index] for more information. If this option is specified, tags
will become clickable, pointing to the corresponding section in the tags
index:
become clickable, pointing to the corresponding section in the tags index:
``` yaml
plugins:
@ -51,8 +62,8 @@ The following configuration options are available:
[`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files }
: [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows to define additional pages to render
subsets of the [tags index], in order to provide scoped tags indexes for
Default: _none_ – This option specifies additional pages, i.e. to render
subsets of the [tags index], in order to provide scoped tags indexes for
specific sections:
``` yaml
@ -84,11 +95,67 @@ The following configuration options are available:
at least one of the tags `HTML5`, `JavaScript` or `CSS` will be included
in the additional tags index on `web.md`.
See #3864 for additional use cases.
See #3864 for more information.
[`tags_slugify`](#+tags.tags_slugify){ #+tags.tags_slugify }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: `headerid.slugify` – This option specifies which function to use for
generating URL-compatible slugs from tags. [Python Markdown Extensions]
includes several Unicode-aware slug functions which are a good choice for
non-ASCII languages:
=== "Unicode"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`tags_slugify_separator`](#+tags.tags_slugify_separator){ #+tags.tags_slugify_separator }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: `-` – This option specifies the separator which is used by the slug function. By default, a hyphen is used, but it can
be changed to any string:
``` yaml
plugins:
- tags:
tags_slugify_separator: "-"
```
[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed } :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
: [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24:
Default: _none_ – This option allows the author to define explicitly which
tags are allowed to be used on pages. If this setting is omitted, the
[built-in tags plugin] won't check tag names. Use this option to define a
list of tags in order to catch typos:
``` yaml
plugins:
- tags:
tags_allowed:
- HTML5
- JavaScript
- CSS
```
[Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[Insiders]: ../insiders/index.md
[tag identifiers]: #tag-icons
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
### Tag icons