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 2023-08-21 18:54:53 +02:00
parent 4759c7aaaf
commit de0fc512e9
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
6 changed files with 61 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/annotations.md
View File

@ -75,7 +75,7 @@ Some popular choices:
### Using annotations
[:octicons-tag-24: 9.2.0b0][Annotation support] ·
[:octicons-tag-24: 9.2.0][Annotation support] ·
:octicons-beaker-24: Experimental
Annotations consist of two parts: a marker, which can be placed anywhere in
@ -104,7 +104,7 @@ Note that the `annotate` class must only be added to the outermost block. All
nested elements can use the same list to define annotations, except when
annotations are nested themselves.
[Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
#### in annotations

8
docs/reference/index.md
View File

@ -121,7 +121,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
### Setting the page `icon`
[:octicons-tag-24: 9.2.0b0][Page icon support] ·
[:octicons-tag-24: 9.2.0][Page icon support] ·
:octicons-beaker-24: Experimental
An icon can be assigned to each page, which is then rendered as part of the
@ -149,14 +149,14 @@ icon: material/emoticon-happy # (1)!
</div>
</div>
[Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[Insiders]: ../insiders/index.md
[icon search]: icons-emojis.md#search
[navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
### Setting the page `status`
[:octicons-tag-24: 9.2.0b0][Page status support] ·
[:octicons-tag-24: 9.2.0][Page status support] ·
:octicons-beaker-24: Experimental
A status can be assigned to each page, which is then displayed as part of the
@ -197,7 +197,7 @@ The following status identifiers are currently supported:
- :material-alert-decagram: – `new`
- :material-trash-can: – `deprecated`
[Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
### Setting the page `subtitle`

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

@ -33,6 +33,12 @@
"type": "boolean",
"default": false
},
"post_dir": {
"title": "Blog posts directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_dir",
"type": "string",
"default": "\"{blog}/posts\""
},
"post_date_format": {
"title": "Format string for post dates",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format",
@ -329,7 +335,7 @@
"title": "Authors file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file",
"type": "string",
"default": ".authors.yml"
"default": "\"{blog}/.authors.yml\""
},
"draft": {
"title": "Render posts marked as drafts",

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

@ -19,7 +19,7 @@ __Check out our [blog], which is created with the new [built-in blog plugin]!__
### Built-in blog plugin
[:octicons-tag-24: 9.2.0b0][Blog plugin support] ·
[:octicons-tag-24: 9.2.0][Blog plugin support] ·
:octicons-cpu-24: Plugin ·
:octicons-beaker-24: Experimental
@ -126,7 +126,7 @@ back here later for fine-tuning the output.__
---
[Blog plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Blog plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[Insiders]: ../insiders/index.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[this is configurable]: #+blog.blog_dir
@ -138,6 +138,22 @@ back here later for fine-tuning the output.__
The following configuration options are available for posts:
[`post_dir`](#+blog.post_dir){ #+blog.post_dir }
: :octicons-milestone-24: Default: `{blog}/posts` – This option specifies
the name of the folder in which the blog plugin should look for posts.
The default settings assumes that the folder is called `posts`:
``` yaml
plugins:
- blog:
post_dir: blog/posts
```
The path must be defined relative to [`docs_dir`][docs_dir]. Note that the
`{blog}` placeholder is replaced with the value specified in
[`blog_dir`][this is configurable].
[`post_date_format`](#+blog.post_date_format){ #+blog.post_date_format }
: :octicons-milestone-24: Default: `long` – This option specifies the date
@ -689,7 +705,7 @@ The following configuration options are available for index pagination:
pagination_url_format: "{page}"
```
[`pagination_template`](#+blog.pagination_template){ #+blog.pagination_template }
[`pagination_format`](#+blog.pagination_format){ #+blog.pagination_format }
: :octicons-milestone-24: Default: `~2~` – This option specifies the format
string that is provided to the [paginate] module, which allows to customize
@ -700,7 +716,7 @@ The following configuration options are available for index pagination:
``` yaml
plugins:
- blog:
pagination_template: "~2~"
pagination_format: "~2~"
```
=== "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
@ -708,7 +724,7 @@ The following configuration options are available for index pagination:
``` yaml
plugins:
- blog:
pagination_template: "$link_first $link_previous ~2~ $link_next $link_last"
pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
```
=== "1 :material-chevron-right:"
@ -716,7 +732,7 @@ The following configuration options are available for index pagination:
``` yaml
plugins:
- blog:
pagination_template: "$link_previous $page $link_next"
pagination_format: "$link_previous $page $link_next"
```
The [paginate] module exposes the following placeholders:
@ -736,6 +752,18 @@ The following configuration options are available for index pagination:
[paginate]: https://pypi.org/project/paginate/
[`pagination_if_single_page`](#+blog.pagination_if_single_page){ #+blog.pagination_if_single_page }
: :octicons-milestone-24: Default: `false` – This option specifies whether
the pagination should also be rendered if all posts fit into a single page.
If you wish to always render pagination, add:
``` yaml
plugins:
- blog:
pagination_if_single_page: true
```
[`pagination_keep_content`](#+blog.pagination_keep_content){ #+blog.pagination_keep_content }
: :octicons-milestone-24: Default: `false` – This option specifies whether
@ -767,10 +795,10 @@ The following configuration options are available for author info:
[`authors_file`](#+blog.authors_file){ #+blog.authors_file }
: :octicons-milestone-24: Default: `.authors.yml` – This option specifies the
name of the file where the authors for your posts resides. The default
settings assumes that the file is called `.authors.yml` (mind the `.` at
the beginning):
: :octicons-milestone-24: Default: `{blog}/.authors.yml` – This option
specifies the name of the file where the authors for your posts resides.
The default settings assumes that the file is called `.authors.yml`
(mind the `.` at the beginning):
``` yaml
plugins:
@ -778,8 +806,9 @@ The following configuration options are available for author info:
authors_file: blog/.authors.yml
```
The path must be defined relative to [`docs_dir`][docs_dir].
Also see the section on [adding authors].
The path must be defined relative to [`docs_dir`][docs_dir]. Note that the
`{blog}` placeholder is replaced with the value specified in
[`blog_dir`][this is configurable]. Also see the section on [adding authors].
[adding authors]: #adding-authors
@ -840,8 +869,7 @@ The following configuration options are available for drafts:
### RSS
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.23.0][Insiders] ·
[:octicons-tag-24: 9.2.0][Blog plugin support] ·
[:octicons-cpu-24: Plugin][rss]
The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
@ -1359,14 +1387,10 @@ which means you can override all templates used for the blog by using
The following templates are added by the [built-in blog plugin]:
- [`blog.html`][blog.html] – Template for blog index
- [`blog.html`][blog.html] – Template for blog, archive and category index
- [`blog-post.html`][blog-post.html] – Template for blog post
- [`blog-archive.html`][blog-archive.html] – Template for blog archive index
- [`blog-category.html`][blog-category.html] – Template for blog category index
[theme extension]: ../customization.md#extending-the-theme
[blog.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog.html
[blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.html
[blog-archive.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-archive.html
[blog-category.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-category.html
[blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.htmlhtml

4
docs/setup/setting-up-navigation.md
View File

@ -223,7 +223,7 @@ theme:
### Navigation pruning
[:octicons-tag-24: 9.2.0b0][Navigation pruning support] ·
[:octicons-tag-24: 9.2.0][Navigation pruning support] ·
:octicons-beaker-24: Experimental
When pruning is enabled, only the visible navigation items are included in the
@ -245,7 +245,7 @@ This feature flag is especially useful for documentation sites with 100+ or even
Navigation pruning will replace all expandable sections with links to the first
page in that section (or the section index page).
[Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[navigation.expand]: #navigation-expansion
### Section index pages

4
docs/setup/setting-up-site-search.md
View File

@ -191,7 +191,7 @@ The following configuration options are supported:
#### Chinese language support
[:octicons-tag-24: 9.2.0b0][Chinese language support] ·
[:octicons-tag-24: 9.2.0][Chinese language support] ·
:octicons-beaker-24: Experimental
In order to add support for Chinese languages to the [built-in search plugin],
@ -236,7 +236,7 @@ The following configuration options are available:
User dictionaries can be used for tuning the segmenter to preserve
technical terms.
[Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
[Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[chinese search]: ../blog/posts/chinese-search-support.md
[jieba]: https://pypi.org/project/jieba/
[built-in search plugin]: #built-in-search-plugin