Skip to content

Commit

Permalink
feat: extend material blog configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
@kamilkrzyskow
kamilkrzyskow committed Oct 4, 2024
1 parent 8e31729 commit 69ace77
Show file tree
Hide file tree
Showing 5 changed files with 236 additions and 149 deletions.
7 changes: 7 additions & 0 deletions mkdocs_nype/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
"""

Expand All @@ -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()
Expand Down Expand Up @@ -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()
74 changes: 74 additions & 0 deletions mkdocs_nype/extensions/material.py
View file
Original file line number Diff line number Diff line change
@@ -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
"""
159 changes: 81 additions & 78 deletions mkdocs_nype/templates/blog-post.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
-#}
Expand Down Expand Up @@ -82,103 +83,105 @@
</div>
{% endif %}

<!-- Post metadata -->
<ul class="md-post__meta md-nav__list">
<li class="md-nav__item md-nav__item--section">
<div class="md-post__title">
<span class="md-ellipsis">
{{ lang.t("blog.meta") }}
</span>
</div>
<nav class="md-nav">
<ul class="md-nav__list">

<!-- Post date -->
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/calendar.svg" %}
<time
datetime="{{ page.config.date.created }}"
class="md-ellipsis"
>
{{- page.config.date.created | date -}}
</time>
</div>
</li>

<!-- Post date updated -->
{% if page.config.date.updated %}
{% if not hide_post_metadata %}
<!-- Post metadata -->
<ul class="md-post__meta md-nav__list">
<li class="md-nav__item md-nav__item--section">
<div class="md-post__title">
<span class="md-ellipsis">
{{ lang.t("blog.meta") }}
</span>
</div>
<nav class="md-nav">
<ul class="md-nav__list">

<!-- Post date -->
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/calendar-clock.svg" %}
{% include ".icons/material/calendar.svg" %}
<time
datetime="{{ page.config.date.updated }}"
datetime="{{ page.config.date.created }}"
class="md-ellipsis"
>
{{- page.config.date.updated | date -}}
{{- page.config.date.created | date -}}
</time>
</div>
</li>
{% endif %}

<!-- Post categories -->
{% if page.categories %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/bookshelf.svg" %}
<span class="md-ellipsis">
{{ lang.t("blog.categories.in") }}
{% for category in page.categories %}
<a href="{{ category.url | url }}">
{{- category.title -}}
</a>
{%- if loop.revindex > 1 %}, {% endif -%}
{% endfor -%}
</span>
</div>
</li>
{% endif %}

<!-- Post custom categorization managed by custom_blog_categorization plugin -->
{% if page.custom_categorizations %}
{% for categorization, properties in page.custom_categorizations.items() %}
<!-- Post date updated -->
{% if page.config.date.updated %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/calendar-clock.svg" %}
<time
datetime="{{ page.config.date.updated }}"
class="md-ellipsis"
>
{{- page.config.date.updated | date -}}
</time>
</div>
</li>
{% endif %}

<!-- Post categories -->
{% if page.categories %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/" ~ properties.icon ~ ".svg" %}
{% include ".icons/material/bookshelf.svg" %}
<span class="md-ellipsis">
{{ lang.t("blog.categories.in") }}
{% for entry in page[categorization] %}
<a href="{{ entry.url | url }}">
{{- entry.title -}}
{% for category in page.categories %}
<a href="{{ category.url | url }}">
{{- category.title -}}
</a>
{%- if loop.revindex > 1 %}, {% endif -%}
{% endfor -%}
</span>
</div>
</li>
{% endfor %}
{% endif %}

<!-- Post readtime -->
{% if page.config.readtime %}
{% set time = page.config.readtime %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/clock-outline.svg" %}
<span class="md-ellipsis">
{% if time == 1 %}
{{ lang.t("readtime.one") }}
{% else %}
{{ lang.t("readtime.other") | replace("#", time) }}
{% endif %}
</span>
</div>
</li>
{% endif %}
</ul>
</nav>
</li>
</ul>
{% endif %}

<!-- Post custom categorization managed by custom_blog_categorization plugin -->
{% if page.custom_categorizations %}
{% for categorization, properties in page.custom_categorizations.items() %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/" ~ properties.icon ~ ".svg" %}
<span class="md-ellipsis">
{{ lang.t("blog.categories.in") }}
{% for entry in page[categorization] %}
<a href="{{ entry.url | url }}">
{{- entry.title -}}
</a>
{%- if loop.revindex > 1 %}, {% endif -%}
{% endfor -%}
</span>
</div>
</li>
{% endfor %}
{% endif %}

<!-- Post readtime -->
{% if page.config.readtime %}
{% set time = page.config.readtime %}
<li class="md-nav__item">
<div class="md-nav__link">
{% include ".icons/material/clock-outline.svg" %}
<span class="md-ellipsis">
{% if time == 1 %}
{{ lang.t("readtime.one") }}
{% else %}
{{ lang.t("readtime.other") | replace("#", time) }}
{% endif %}
</span>
</div>
</li>
{% endif %}
</ul>
</nav>
</li>
</ul>
{% endif %}
</nav>

<!-- Table of contents, if integrated -->
Expand Down
Loading

0 comments on commit 69ace77

Please sign in to comment.