diff --git a/hooks/mkdocs/G003_social_cards_adapter.py b/hooks/mkdocs/G003_social_cards_adapter.py new file mode 100644 index 0000000..9fce78a --- /dev/null +++ b/hooks/mkdocs/G003_social_cards_adapter.py @@ -0,0 +1,152 @@ +#! python3 # noqa: E265 + +"""Script joué au chargement du contenu markdown de chaque page (hook). + +Contexte : + + Le thème Material for Mkdocs intègre un plugin (social) qui permet de générer + automatiquement une image pour chaque page en croisant différents éléments + (métadonnées de la page et éléments graphiques de base). + Mais le fonctionnement est très générique (normal) et entre en conflit avec la gestion + des en-têtes du site Geotribu. + +Objectifs : + + - quand une image n'est pas définie sur une page, patcher l'en-tête pour + y insérer la configuration du plugin social de sorte qu'il génère une image + et qu'on la référence + - quand une image est définie manuellement, patcher l'en-tête pour + y insérer la configuration du plugin social de sorte qu'il utilise l'image sans rien toucher + +""" + +# ############################################################################ +# ########## Libraries ############# +# ################################## + +# standard library +import logging +from pathlib import Path +from typing import Optional + +# Mkdocs +from material import __version__ as material_version +from material.plugins.social.plugin import SocialPlugin +from mkdocs.config.defaults import MkDocsConfig +from mkdocs.plugins import event_priority +from mkdocs.structure.files import Files +from mkdocs.structure.pages import Page + +# ########################################################################### +# ########## Global ################ +# ################################## + +logger = logging.getLogger("mkdocs") +hook_name = Path(__file__).stem + +# check si c'est la version Insiders (payante) ou la version Communauté (gratuite) du thème +is_insiders = "insiders" in material_version + +# ########################################################################### +# ########## Functions ############# +# ################################## + + +@event_priority(50) +def on_page_markdown( + markdown: str, *, page: Page, config: MkDocsConfig, files: Files +) -> Optional[str]: + """ + The `page_markdown` event is called after the page's markdown is loaded + from file and can be used to alter the Markdown source text. The meta- + data has been stripped off and is available as `page.meta` at this point. + + Parameters: + markdown: Markdown source text of page as string + page: `mkdocs.structure.pages.Page` instance + config: global configuration object + files: global files collection + + Returns: + Markdown source text of page as string + """ + # vérifie que le plugin social est bien installé et configuré + if not config.plugins.get("material/social"): + logger.warning( + f"[{hook_name}] Le plugin social du thème Material n'est pas présent. " + "Ce hook est donc inutile." + ) + return + + social_plugin: SocialPlugin = config.plugins.get("material/social") + + # vérifie que le plugin est activé + if not social_plugin.config.enabled or not social_plugin.config.cards: + logger.debug( + f"[{hook_name}] Le plugin social du thème Material est présent mais " + "désactivé. Ce hook est donc inutile." + ) + return + + # Cas de figure où une image n'est pas définie + if page.meta.get("image") is None or page.meta.get("image") == "": + if not page.is_index: + social_card_url = ( + f"{config.site_url}assets/images/social{page.abs_url[:-1]}.png" + ) + else: + social_card_url = ( + f"{config.site_url}assets/images/social{page.abs_url[:-1]}/index.png" + ) + + logger.debug( + f"{page.file.abs_src_path} n'a pas d'image. Une 'social card' sera " + f"automatiquement générée : {social_card_url}" + ) + + # si la page a une icône, on adapte le template de l'image (disponible que pour Insiders) + # ref : https://squidfunk.github.io/mkdocs-material/reference#setting-the-page-icon + if page.meta.get("icon") and is_insiders: + cards_layout = "default/variant" + logger.info( + f"[{hook_name}] La page {page.abs_url} a une icône définie " + f"({page.meta.get('icon')}). Dans ce cas, le modèle de social " + f"card est : {cards_layout}" + ) + elif is_insiders: + cards_layout = social_plugin.config.cards_layout + + # définit les paramètres pour les social cards au niveau de la page + if is_insiders: + page.meta["social"] = { + "cards": True, + "cards_layout": cards_layout, + "cards_layout_options": social_plugin.config.cards_layout_options, + } + # else: + # page.meta["social"] = { + # "cards": True, + # "cards_layout_options": { + # "background_color": social_plugin.config.cards_layout_options.get( + # "background_color" + # ), + # "color": social_plugin.config.cards_layout_options.get("color"), + # "font_family": social_plugin.config.cards_layout_options.get( + # "font_family" + # ), + # }, + # } + else: + logger.debug( + f"[{hook_name}] {page.abs_url} a une image paramétrée. " + "Désactivation du plugin social sur la page." + ) + page.meta["social"] = { + "cards": False, + # TODO: les lignes suivantes pourront être réactivées quand le plugin + # social gèrera les images distantes + # "cards_layout": "default/only/image", + # "cards_layout_options": { + # "background_image": page.meta.get("image"), + # }, + } diff --git a/mkdocs.yml b/mkdocs.yml index d4b201d..a7c0f01 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,6 +20,7 @@ site_dir: !ENV [MKDOCS_OUTPUT_DIR, "./build/mkdocs/site"] # Mkdocs hooks hooks: + - hooks/mkdocs/G003_social_cards_adapter.py - hooks/mkdocs/G007_social_share_buttons.py # Plugins