From 69ace77b867abac8d88f1d4e4d5bb088dc4a492e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20Krzy=C5=9Bk=C3=B3w?= Date: Fri, 4 Oct 2024 03:18:20 +0200 Subject: [PATCH] feat: extend material blog configuration --- mkdocs_nype/__init__.py | 7 + mkdocs_nype/extensions/material.py | 74 +++++++++++ mkdocs_nype/templates/blog-post.html | 159 ++++++++++++----------- mkdocs_nype/templates/partials/post.html | 143 ++++++++++---------- pyproject.toml | 2 +- 5 files changed, 236 insertions(+), 149 deletions(-) create mode 100644 mkdocs_nype/extensions/material.py diff --git a/mkdocs_nype/__init__.py b/mkdocs_nype/__init__.py index 77a7731..a2997a3 100644 --- a/mkdocs_nype/__init__.py +++ b/mkdocs_nype/__init__.py @@ -13,6 +13,10 @@ automatically enabled plugin at runtime that does some kind of validation during the event loop, or enable any recommended plugin markdown extension in each project. +material extensions: +Instead of configuring other plugins and overriding internals of mkdocs-material plugins +extend them before they're loaded into "Python memory" + MIT License 2024 Kamil Krzyśków (HRY) for Nype (npe.cm) """ @@ -28,6 +32,8 @@ from mkdocs.plugins import PrefixedLogger from mkdocs.utils import CountHandler +from .extensions import material as material_extension + LOG: PrefixedLogger = PrefixedLogger("mkdocs_nype", logging.getLogger(f"mkdocs.themes.mkdocs_nype")) issue_counter = CountHandler() @@ -158,3 +164,4 @@ def _get_checksum(source: str) -> str: if __name__ == "mkdocs_nype": patch_default_plugins_auto_load() patch_plugin_loading() + material_extension.extend_blog() diff --git a/mkdocs_nype/extensions/material.py b/mkdocs_nype/extensions/material.py new file mode 100644 index 0000000..5801427 --- /dev/null +++ b/mkdocs_nype/extensions/material.py @@ -0,0 +1,74 @@ +"""mkdocs-material extension module + +Works through being invoked from the mkdocs-nype __init__.py file +before the mkdocs-material plugins get to load etc. + +In some cases, mkdocs-material plugins lack configurability and typically +this issue is solved by adding another plugin with its own configuration +that later overrides stuff during the MkDocs event loop. + +However, some of those cases don't make much sense as a separate plugin with +its own event loop, so this module aims to add those micro adjustments. + +1. Extend the blog config class to be able to configure more options. +2. Monkey-patch some events to add logic before or after their execution. + +MIT License 2024 Kamil Krzyśków (HRY) for Nype (npe.cm) +""" + +from material.plugins.blog import config as blog_config +from material.plugins.blog.structure import View +from mkdocs.config.base import Config +from mkdocs.config.config_options import Choice, Deprecated, Optional, Type + + +def extend_blog(): + """ + This function must be executed before the BlogPlugin class is created + and loaded into "Python memory" via some other "import" + """ + + blog_config.BlogConfig = BlogConfig + + # After modifying the config, import BlogPlugin to make further changes + from material.plugins.blog import plugin as blog_plugin + + blog_plugin.BlogPlugin.on_page_context = wrap_blog_on_page_context( + blog_plugin.BlogPlugin.on_page_context + ) + + +def wrap_blog_on_page_context(func): + + def extended(self, context, *, page, config, nav): + + view = self._resolve_original(page) + blog_view = view in self._resolve_views(self.blog) + blog_post = page in self.blog.posts + + result = func(self, context, page=page, config=config, nav=nav) + + # Pass on the extended config options to the template context + if blog_view or blog_post: + context["hide_read_more"] = self.config.hide_read_more + context["hide_post_metadata"] = self.config.hide_post_metadata + + return result + + return extended + + +class BlogConfig(blog_config.BlogConfig): + """Default values of the new options should match standard mkdocs-material behaviour""" + + hide_read_more = Type(bool, default=False) + """ + Used later in templates to decide if the blog Views should show the read + more link for Excerpts + """ + + hide_post_metadata = Type(bool, default=False) + """ + Used later in templates to decide if the blog Views should show the metadata + of the post, like the date and categories + """ diff --git a/mkdocs_nype/templates/blog-post.html b/mkdocs_nype/templates/blog-post.html index d3a9f54..f32c680 100644 --- a/mkdocs_nype/templates/blog-post.html +++ b/mkdocs_nype/templates/blog-post.html @@ -24,6 +24,7 @@ Modified for mkdocs-nype, last checked up-to-date with mkdocs-material 9.5.39 - Added handling of custom categorization via the custom_blog_categorization plugin + - Added option to hide post metadata via custom hide_post_metadata config option MIT License 2024 Kamil Krzyśków (HRY) for Nype (npe.cm) -#} @@ -82,103 +83,105 @@ {% endif %} - - + {% endif %} diff --git a/mkdocs_nype/templates/partials/post.html b/mkdocs_nype/templates/partials/post.html index 7de9d2e..2ab8155 100644 --- a/mkdocs_nype/templates/partials/post.html +++ b/mkdocs_nype/templates/partials/post.html @@ -24,7 +24,8 @@ Modified for mkdocs-nype, last checked up-to-date with mkdocs-material 9.5.39 - Added handling of custom categorization via the custom_blog_categorization plugin - - Disabled the Continue Reading button + - Added option to hide the Continue Reading link via custom hide_read_more config option + - Added option to hide post metadata via custom hide_post_metadata config option Also note that 'post' is used here rather loosely and it's the Excerpt View object. @@ -33,96 +34,98 @@
-
- - - {% if post.authors %} - - {% endif %} - - -
-
    + {% if not hide_post_metadata %} +
    + + + {% if post.authors %} + + {% endif %} - -
  • - - {#- Collapse whitespace -#} -
    • + +
    +
      - - {% if post.categories %} +
    • - {# lang.t("blog.categories.in") #} - {% set cat_len = post.categories | length %} - Categor{{ 'y' if cat_len < 2 else 'ies' }} - {% for category in post.categories %} - - {{- category.title -}} - - {%- if loop.revindex > 1 %}, {% endif -%} - {% endfor -%} + + {#- Collapse whitespace -#}
      • - {% endif %} - - {% if post.custom_categorizations %} - {% for categorization, properties in post.custom_categorizations.items() %} + + {% if post.categories %}
    • - {%- set cat_len = post[categorization] | length -%} - {{ properties.singular_name if cat_len < 2 else properties.plural_name }} - {% for entry in post[categorization] %} + {# lang.t("blog.categories.in") #} + {% set cat_len = post.categories | length %} + Categor{{ 'y' if cat_len < 2 else 'ies' }} + {% for category in post.categories %} - {{- entry.title -}} + {{- category.title -}} {%- if loop.revindex > 1 %}, {% endif -%} {% endfor -%}
      • - {% endfor %} - {% endif %} + {% endif %} + + + {% if post.custom_categorizations %} + {% for categorization, properties in post.custom_categorizations.items() %} +
    • + {%- set cat_len = post[categorization] | length -%} + {{ properties.singular_name if cat_len < 2 else properties.plural_name }} + {% for entry in post[categorization] %} + + {{- entry.title -}} + + {%- if loop.revindex > 1 %}, {% endif -%} + {% endfor -%} +
      • + {% endfor %} + {% endif %} + + + {% if post.config.readtime %} + {% set time = post.config.readtime %} +
    • + {% if time == 1 %} + {{ lang.t("readtime.one") }} + {% else %} + {{ lang.t("readtime.other") | replace("#", time) }} + {% endif %} +
      • + {% endif %} +
    - - {% if post.config.readtime %} - {% set time = post.config.readtime %} -
  • - {% if time == 1 %} - {{ lang.t("readtime.one") }} - {% else %} - {{ lang.t("readtime.other") | replace("#", time) }} - {% endif %} -
    • + + {% if post.config.draft %} + + {{ lang.t("blog.draft") }} + {% endif %} -
- - - {% if post.config.draft %} - - {{ lang.t("blog.draft") }} - - {% endif %} -
-
+ + + {% endif %}
{{ post.content }} - {% if post.more and false %} + {% if post.more and not hide_read_more %}