From 6be485c38febbe6076555367b4c174c92c6aad15 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 26 Nov 2023 15:22:43 +0100 Subject: [PATCH] Documentation --- docs/plugins/blog.md | 267 +++++++++++++++++++++++--------- material/plugins/blog/author.py | 1 + material/plugins/blog/config.py | 8 +- src/plugins/blog/author.py | 1 + src/plugins/blog/config.py | 8 +- 5 files changed, 205 insertions(+), 80 deletions(-) diff --git a/docs/plugins/blog.md b/docs/plugins/blog.md index 227a30913..3ab34dd83 100644 --- a/docs/plugins/blog.md +++ b/docs/plugins/blog.md @@ -213,9 +213,8 @@ The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]. 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: + +--- + +#### + + + + +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 +``` + +--- + +#### + + + + +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: + : + name: string # Author name + description: string # Author description + avatar: url # Author avatar + slug: url # Author profile slug + url: url # Author website URL + ``` + + Note that `` 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 + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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] + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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: - ---- - -#### - - - - -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 -``` - ---- - -#### - - - - -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: - : - name: string # Author name - description: string # Author description - avatar: url # Author avatar - url: url # Author website URL - ``` - - Note that `` 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: diff --git a/material/plugins/blog/author.py b/material/plugins/blog/author.py index 5fb457b19..2305a8e1b 100644 --- a/material/plugins/blog/author.py +++ b/material/plugins/blog/author.py @@ -30,6 +30,7 @@ class Author(Config): name = Type(str) description = Type(str) avatar = Type(str) + slug = Optional(Type(str)) url = Optional(Type(str)) # ----------------------------------------------------------------------------- diff --git a/material/plugins/blog/config.py b/material/plugins/blog/config.py index 18dbc97d3..d13bc9f9d 100644 --- a/material/plugins/blog/config.py +++ b/material/plugins/blog/config.py @@ -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) diff --git a/src/plugins/blog/author.py b/src/plugins/blog/author.py index 5fb457b19..2305a8e1b 100644 --- a/src/plugins/blog/author.py +++ b/src/plugins/blog/author.py @@ -30,6 +30,7 @@ class Author(Config): name = Type(str) description = Type(str) avatar = Type(str) + slug = Optional(Type(str)) url = Optional(Type(str)) # ----------------------------------------------------------------------------- diff --git a/src/plugins/blog/config.py b/src/plugins/blog/config.py index 18dbc97d3..d13bc9f9d 100644 --- a/src/plugins/blog/config.py +++ b/src/plugins/blog/config.py @@ -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)