mkdocs_nype.plugins.nype_tweaks.plugin

Synopsis

MkDocs plugin made to apply small tweaks that don't need to be their own plugin.

This plugin is activated automatically for all projects using the mkdocs_nype theme. This happens in the validate_with_nype_plugin_injection patch __init__.py.

1. URL collision detection tweak:

Automatically detect page URL collisions. This is useful when a blog plugin uses raw slugs and 2 pages can have the same slug.

2. Theme __init__.py issue count handler tweak:

When the --strict flag is used, warnings from the theme __init__.py were ignored. This tweak fixes it. TODO There is probably a better way, because if nype_tweaks won't run automatically, due to an error, then this tweak will not be applied.

3. Extend macros includes directory tweak:

mkdocs-macros-plugin only allows to set one directory for includes. However, the Jinja2.loaders.FileSystemLoader supports a list of paths, so override the macros plugin reference to FileSystemLoader.

4. HEX data obfuscation tweak:

Some data should be obfuscated in plain HTML to make it harder for bots to scrape them. The obfuscation happens just before passing data to JavaScript. Later on this data is deobfuscated in JavaScript.

5. Blog cards tweak:

To convert a normal blog post Excerpt to a Grid Card some HTML needs to be read from the page.content. The provided filter functions get called in the post-card.html template.

6. Create nype_config for page and sync with global tweak:

This was previously done at render time in nype-base.html, but this is too late for blog cards meta placeholders. To use the global value for the placeholder better set it in the event. Errata: Turned out this train of thought was wrong, as the posts' on_page events run after the blog index with the cards, so the tweak doesn't make things easier. Global placeholder loading was moved to the post-card.html template.

7. Enable default tag icon tweak:

The Material tags plugin allows to set icons for each tag, however there is also the default icon, which isn't turned on without setting other icon mappings. The tweak sets the required settings to show the default icon on tags.

• https://github.com/squidfunk/mkdocs-material/issues/7688

8. footer_nav tweak:

To allow normal file system paths in the nype_config->footer_nav this tweak needed to be implemented to convert the file system paths into the URLs used in the copyright.html template.

9. robots.txt tweak:

To help scrapers with avoiding certain path, the plugin generates a robots.txt file. It contains a static list of paths to the custom GTAG tracking, and allows to add paths via theme.nype_config.exclude_via_robots.

MIT License 2024 Kamil Krzyśków (HRY) for Nype (npe.cm)

MACROS_INCLUDES_ROOT: Path = THEME_ROOT / 'macros_includes'

PLUGIN_NAME: str = 'nype_tweaks'

LOG: PrefixedLogger = PrefixedLogger(PLUGIN_NAME, getLogger(f'mkdocs.plugins.{PLUGIN_NAME}'))

run_once = False

NypeTweaksPlugin()

dest_url_mapping = {}

draft_paths: GitIgnoreSpec = None

nype_config_key = 'nype_config'

default_footer_nav = {'Contact': 'contact.md', 'Impressum': 'impressum.md', 'Offer': 'offer.md'}

on_page_markdown = CombinedEvent(_on_page_markdown_social_meta, _on_page_markdown_robots, _on_page_markdown_nype_config)

on_config(config: MkDocsConfig) -> MkDocsConfig | None

on_files(files: Files, /, *, config: MkDocsConfig)

on_env(env: Environment, /, *, config: MkDocsConfig, files: Files) -> macros_module.Environment | None

on_template_context(context: TemplateContext, /, *, template_name: str, config: MkDocsConfig) -> TemplateContext | None

on_post_page(output: str, /, *, page: Page, config: MkDocsConfig) -> str | None

_on_page_markdown_social_meta(markdown: str, /, *, page: Page, config: MkDocsConfig, files: Files) -> str | None

_on_page_markdown_robots(markdown: str, /, *, page: Page, config: MkDocsConfig, files: Files) -> str | None

_on_page_markdown_nype_config(markdown: str, /, *, page: Page, config: MkDocsConfig, files: Files) -> str | None

on_page_context(context: TemplateContext, /, *, page: Page, config: MkDocsConfig, nav: Navigation) -> TemplateContext | None

on_post_build(*, config: MkDocsConfig) -> None

on_serve(server: LiveReloadServer, /, *, config: MkDocsConfig, builder) -> LiveReloadServer | None

prepare_context_with_nype_config(context: TemplateContext, config: MkDocsConfig, page: Page = None)