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-11-26 15:22:43 +01:00
parent 28ebcbfb59
commit 6be485c38f
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
5 changed files with 205 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
docs/plugins/blog.md
View File

@ -213,9 +213,8 @@ The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
<!-- md:default `false` -->
Use this setting to leverage the table of contents to display post titles in
views. The value of this setting is inherited by [`archive_toc`]
[config.archive_toc] and [`categories_toc`][config.categories_toc],
unless they are explicitly set:
views. This might be useful, if your post excerpts are rather long. If you want
to enable it, use:
``` yaml
plugins:
@ -746,7 +745,7 @@ plugins:
Use this setting to change the number of posts rendered per archive page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set:
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
@ -763,7 +762,7 @@ plugins:
Use this setting to leverage the table of contents to display post titles on all
archive pages. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless it's explicitly set:
[config.blog_toc], unless it's explicitly set. To change it, use
``` yaml
plugins:
@ -971,7 +970,7 @@ plugins:
Use this setting to change the number of posts rendered per category page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set:
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
@ -988,7 +987,7 @@ plugins:
Use this setting to leverage the table of contents to display post titles on all
category pages. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless it's explicitly set:
[config.blog_toc], unless it's explicitly set. To change it, use:
``` yaml
plugins:
@ -996,6 +995,195 @@ plugins:
categories_toc: true
```
### Authors
The following settings are available for authors:
---
#### <!-- md:setting config.authors -->
<!-- md:version 9.2.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable post authors. If this setting is enabled,
the plugin will look for a file named [`.authors.yml`][config.authors_file] and
render authors in posts and views. Disable this behavior with:
``` yaml
plugins:
- blog:
authors: false
```
---
#### <!-- md:setting config.authors_file -->
<!-- md:version 9.2.0 -->
<!-- md:default `{blog}/.authors.yml` -->
Use this setting to change the path of the file where the author information for
your posts resides. It's normally not necessary to change this setting, but if
you need to, use:
``` yaml
plugins:
- blog:
authors_file: "{blog}/.authors.yml"
```
The following placeholders are available:
- `blog` – [`blog` directory][config.blog_dir]
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
!!! info "Format of author information"
The `.authors.yml` file must adhere to the following format:
``` yaml title=".authors.yml"
authors:
<author>:
name: string # Author name
description: string # Author description
avatar: url # Author avatar
slug: url # Author profile slug
url: url # Author website URL
```
Note that `<author>` must be set to an identifier for associating authors
with posts, e.g., a GitHub username like `squidfunk`. This identifier can
then be used in the [`authors`][meta.authors] metadata property of
a post. Multiple authors are supported. As an example, see
[the `.authors.yml` file][.authors.yml] we're using for our blog.
[.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
---
#### <!-- md:setting config.authors_profiles -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `false` -->
Use this setting to enable or disable automatically generated author profiles.
An author profile shows all posts by an author in reverse chronological order.
You can enable author profiles with:
``` yaml
plugins:
- blog:
author_profiles: true
```
---
#### <!-- md:setting config.authors_profiles_name -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default computed -->
Use this setting to change the title of the authors section the plugin adds to
the navigation. If this setting is omitted, it's sourced from the translations.
If you want to change it, use:
``` yaml
plugins:
- blog:
authors_profiles_name: Authors
```
---
#### <!-- md:setting config.authors_profiles_url_format -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `author/{slug}` -->
Use this setting to change the format string that is used when generating
author profile URLs. You can freely combine placeholders, and join them with
slashes or other characters:
=== ":material-link: blog/author/:material-dots-horizontal:/"
``` yaml
plugins:
- blog:
authors_profiles_url_format: "author/{slug}"
```
=== ":material-link: blog/:material-dots-horizontal:/"
``` yaml
plugins:
- blog:
authors_profiles_url_format: "{slug}"
```
The following placeholders are available:
- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]
- `name` – Author name from [`authors_file`][config.authors_file]
---
#### <!-- md:setting config.authors_profiles_pagination -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable pagination for author profiles. The value
of this setting is inherited from [`pagination`][config.pagination], unless it's
explicitly set. To disable pagination, use:
``` yaml
plugins:
- blog:
authors_profiles_pagination: false
```
---
#### <!-- md:setting config.authors_profiles_pagination_per_page -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `10` -->
Use this setting to change the number of posts rendered per archive page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
authors_profiles_pagination_per_page: 5
```
---
#### <!-- md:setting config.authors_profiles_toc -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `false` -->
Use this setting to leverage the table of contents to display post titles on all
author profiles. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
authors_profiles_toc: true
```
### Pagination
The following settings are available for pagination:
@ -1151,71 +1339,6 @@ plugins:
pagination_keep_content: true
```
### Authors
The following settings are available for authors:
---
#### <!-- md:setting config.authors -->
<!-- md:version 9.2.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable post authors. If this setting is enabled,
the plugin will look for a file named [`.authors.yml`][config.authors_file] and
render authors in posts and views. Disable this behavior with:
``` yaml
plugins:
- blog:
authors: false
```
---
#### <!-- md:setting config.authors_file -->
<!-- md:version 9.2.0 -->
<!-- md:default `{blog}/.authors.yml` -->
Use this setting to change the path of the file where the author information for
your posts resides. It's normally not necessary to change this setting, but if
you need to, use:
``` yaml
plugins:
- blog:
authors_file: "{blog}/.authors.yml"
```
The following placeholders are available:
- `blog` – [`blog` directory][config.blog_dir]
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
!!! info "Format of author information"
The `.authors.yml` file must adhere to the following format:
``` yaml title=".authors.yml"
authors:
<author>:
name: string # Author name
description: string # Author description
avatar: url # Author avatar
url: url # Author website URL
```
Note that `<author>` must be set to an identifier for associating authors
with posts, e.g., a GitHub username like `squidfunk`. This identifier can
then be used in the [`authors`][meta.authors] metadata property of
a post. Multiple authors are supported. As an example, see
[the `.authors.yml` file][.authors.yml] we're using for our blog.
[.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
### Drafts
The following settings are available for drafts:

1
material/plugins/blog/author.py
View File

@ -30,6 +30,7 @@ class Author(Config):
name = Type(str)
description = Type(str)
avatar = Type(str)
slug = Optional(Type(str))
url = Optional(Type(str))
# -----------------------------------------------------------------------------

8
material/plugins/blog/config.py
View File

@ -67,6 +67,10 @@ class BlogConfig(Config):
categories_allowed = Type(list, default = [])
categories_toc = Optional(Type(bool))
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for pagination
pagination = Type(bool, default = True)
pagination_per_page = Type(int, default = 10)
@ -75,10 +79,6 @@ class BlogConfig(Config):
pagination_if_single_page = Type(bool, default = False)
pagination_keep_content = Type(bool, default = False)
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for drafts
draft = Type(bool, default = False)
draft_on_serve = Type(bool, default = True)

1
src/plugins/blog/author.py
View File

@ -30,6 +30,7 @@ class Author(Config):
name = Type(str)
description = Type(str)
avatar = Type(str)
slug = Optional(Type(str))
url = Optional(Type(str))
# -----------------------------------------------------------------------------

8
src/plugins/blog/config.py
View File

@ -67,6 +67,10 @@ class BlogConfig(Config):
categories_allowed = Type(list, default = [])
categories_toc = Optional(Type(bool))
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for pagination
pagination = Type(bool, default = True)
pagination_per_page = Type(int, default = 10)
@ -75,10 +79,6 @@ class BlogConfig(Config):
pagination_if_single_page = Type(bool, default = False)
pagination_keep_content = Type(bool, default = False)
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for drafts
draft = Type(bool, default = False)
draft_on_serve = Type(bool, default = True)