Merge pull request #615 from davep/script-management

Add support for overriding third party resources

Author: davep

AGENTS.md

@@ -241,4 +241,11 @@ Rules:
     following the patterns used for `sidebar_pages`, `head`,
     `extra_stylesheets`, and the path template fields.
 
+  * **Third-party scripts/stylesheets**: if we ever add another third-party resource,
+    its URLs/endpoints should be added to the nested `third_party` configuration mapping
+    (e.g., `third_party.resource_name.url_type`) rather than creating a top-level property.
+    This keeps all external script and stylesheet configuration grouped and consistent.
+    Follow the validation and merge patterns established in `config.py` for the existing
+    `third_party` fields.
+
 [//]: # (AGENTS.md ends here)

ChangeLog.md

@@ -1,5 +1,16 @@
 # BlogMore ChangeLog
 
+## Unreleased
+
+**Released: WiP**
+
+- Added a `third_party` configuration mapping to allow overriding the script
+  and stylesheet URLs/locations for Mermaid, KaTeX, MathJax, FontAwesome,
+  and Force-Graph. ([#615](https://github.com/davep/blogmore/pull/615))
+- Refactored the FontAwesome metadata caching to hash the configured URL,
+  ensuring cache invalidation when a user updates their targeted version.
+  ([#615](https://github.com/davep/blogmore/pull/615))
+
 ## v2.42.0
 
 **Released: 2026-06-08**

THEME_DEVELOPMENT_GUIDELINES.md

@@ -140,6 +140,7 @@ v2.x.  Key ones that appear in nearly every template:
 - `bundle_css`, `bundle_css_url`, `fontawesome_is_bundled` — for CSS bundling support
 - `inline_theme_js`, `theme_js_content` — for theme JavaScript inlining support
 - `with_related`, `related_title` — for related posts feature support
+- `mermaid_script_url`, `katex_css_url`, `katex_js_url`, `mathjax_js_url`, `fontawesome_woff2_url`, `force_graph_js_url` — for third-party script/resource configuration support
 
 ### Stable Post attributes
 

blogmore.yaml.example

@@ -133,6 +133,28 @@ posts_per_feed: 20
 # Only meaningful when with_maths is true. Configuration file only.
 # maths_provider: katex
 
+# Optional: Third-party script and stylesheet resource URLs
+# By default, these point to public CDN locations. You can override individual
+# URLs (for example, to target different versions, use custom CDN providers,
+# or point to locally-served files).
+# Configuration file only.
+#
+# third_party:
+#   mermaid:
+#     script_url: "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"
+#   katex:
+#     css_url: "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css"
+#     js_url: "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"
+#   mathjax:
+#     js_url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+#   fontawesome:
+#     metadata_url: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.7.2/metadata/icons.json"
+#     webfonts_base: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts"
+#     css_url: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
+#     woff2_url: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts/fa-brands-400.woff2"
+#   force_graph:
+#     js_url: "https://unpkg.com/force-graph"
+
 # Optional: Enable automated build-time related posts calculation (default: false)
 # When true, BlogMore uses a pure-Python TF-IDF and Cosine Similarity engine to
 # automatically find and display contextually relevant posts for each entry,

docs/configuration.md

@@ -551,6 +551,50 @@ This is a **configuration file only** option — it cannot be set on the command
 maths_provider: katex
 ```
 
+#### `third_party`
+
+Allows overriding the URLs and script/stylesheet locations for third-party libraries (Mermaid, KaTeX, MathJax, FontAwesome, and Force-Graph). By default, these point to public CDN locations. This configuration allows you to pin specific versions or point to custom CDN/local asset locations.
+
+This is a **configuration file only** option — it cannot be set on the command line.
+
+**Type:** Mapping  
+**Default:** (See default CDN URLs in the example below)
+
+Within `third_party`, you can configure the following mappings:
+
+*   `mermaid`
+    *   `script_url` — The script module URL for Mermaid.
+*   `katex`
+    *   `css_url` — The stylesheet URL for KaTeX.
+    *   `js_url` — The script URL for KaTeX.
+*   `mathjax`
+    *   `js_url` — The script URL for MathJax.
+*   `fontawesome`
+    *   `metadata_url` — The URL to fetch FontAwesome icon metadata (Unicode mappings) for CSS optimization.
+    *   `webfonts_base` — The base URL for FontAwesome brands WOFF2 and TTF web font files.
+    *   `css_url` — Fallback full stylesheet URL when CSS optimization fails.
+    *   `woff2_url` — FontAwesome brands WOFF2 preload URL.
+*   `force_graph`
+    *   `js_url` — The script URL for the Force-Graph visualization library.
+
+```yaml
+third_party:
+  mermaid:
+    script_url: "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"
+  katex:
+    css_url: "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css"
+    js_url: "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"
+  mathjax:
+    js_url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+  fontawesome:
+    metadata_url: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.7.2/metadata/icons.json"
+    webfonts_base: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts"
+    css_url: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"
+    woff2_url: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts/fa-brands-400.woff2"
+  force_graph:
+    js_url: "https://unpkg.com/force-graph"
+```
+
 #### `with_related`
 
 Enable automated build-time related posts calculation. When `true`, BlogMore uses a pure-Python TF-IDF and Cosine Similarity engine to automatically calculate and list contextually relevant posts for each entry, with zero runtime overhead for readers.

docs/template-api.md

@@ -57,11 +57,16 @@ below lists all variables that are available in every template.
 | `with_graph` | `bool` | `True` when the graph page is enabled. |
 | `graph_url` | `str` | URL to the graph page (respects `graph_path` and `clean_urls`). |
 | `graph_css_url` | `str` | URL to the graph-page stylesheet (with cache-bust query string). |
+| `force_graph_js_url` | `str` | URL to the Force-Graph JS library script. |
 | `with_mermaid` | `bool` | `True` when Mermaid diagram rendering is enabled. |
 | `has_mermaid` | `bool` | `True` if the currently rendered page/post (or any post listed in the current index view) contains a Mermaid diagram. |
+| `mermaid_script_url` | `str` | URL to the Mermaid ESM script. |
 | `with_maths` | `bool` | `True` when LaTeX mathematical formula rendering is enabled. |
 | `maths_provider` | `str` | The selected math rendering engine (`'katex'` or `'mathjax'`). |
 | `has_math` | `bool` | `True` if the currently rendered page/post (or any post listed in the current index view) contains a mathematical equation. |
+| `katex_css_url` | `str` | URL to the KaTeX stylesheet. |
+| `katex_js_url` | `str` | URL to the KaTeX script. |
+| `mathjax_js_url` | `str` | URL to the MathJax script. |
 | `inline_theme_js` | `bool` | `True` when theme JavaScript inlining is enabled. |
 | `theme_js_content` | `str \| None` | The content of `theme.js` to be inlined. |
 | `theme_js_url` | `str` | URL to `theme.js` (with cache-bust query string). |
@@ -70,6 +75,7 @@ below lists all variables that are available in every template.
 | `has_platform_icons` | `bool` | `True` when generated platform icons are present. |
 | `fontawesome_css_url` | `str \| None` | Font Awesome CSS URL, when social icons are used. |
 | `fontawesome_is_bundled` | `bool` | `True` when Font Awesome is included in the bundle. |
+| `fontawesome_woff2_url` | `str` | Font Awesome brands WOFF2 font file URL. |
 | `extra_stylesheets` | `list[str]` | List of extra stylesheet URLs from configuration. |
 | `tag_dir` | `str` | URL prefix for tag pages (e.g. `/tags`). |
 | `category_dir` | `str` | URL prefix for category pages (e.g. `/categories`). |

src/blogmore/config.py

@@ -81,6 +81,7 @@
         "external_links_check_timeout",
         "image_widths",
         "stop_words",
+        "third_party",
     }
 )
 
@@ -750,4 +751,56 @@ def parse_site_config_from_dict(
             )
         kwargs["stop_words"] = []
 
+    # --- third_party ---------------------------------------------------------
+    third_party_defaults = {
+        "mermaid": {
+            "script_url": "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs"
+        },
+        "katex": {
+            "css_url": "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css",
+            "js_url": "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js",
+        },
+        "mathjax": {
+            "js_url": "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
+        },
+        "fontawesome": {
+            "metadata_url": "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.7.2/metadata/icons.json",
+            "webfonts_base": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts",
+            "css_url": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css",
+            "woff2_url": "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/webfonts/fa-brands-400.woff2",
+        },
+        "force_graph": {"js_url": "https://unpkg.com/force-graph"},
+    }
+
+    raw_third_party = config.get("third_party")
+    if raw_third_party is None:
+        kwargs["third_party"] = third_party_defaults
+    elif isinstance(raw_third_party, dict):
+        merged = {}
+        for section, default_keys in third_party_defaults.items():
+            merged[section] = dict(default_keys)
+            user_section = raw_third_party.get(section)
+            if isinstance(user_section, dict):
+                for key in default_keys:
+                    user_val = user_section.get(key)
+                    if user_val is not None:
+                        if isinstance(user_val, str):
+                            merged[section][key] = user_val
+                        else:
+                            errors.append(
+                                f"third_party.{section}.{key} in the configuration file "
+                                "must be a string; ignoring value"
+                            )
+            elif user_section is not None:
+                errors.append(
+                    f"third_party.{section} in the configuration file must be a mapping; "
+                    "ignoring value"
+                )
+        kwargs["third_party"] = merged
+    else:
+        errors.append(
+            "third_party in the configuration file must be a mapping; ignoring value"
+        )
+        kwargs["third_party"] = third_party_defaults
+
     return kwargs, errors

src/blogmore/fontawesome.py

@@ -5,6 +5,7 @@
 ~2-5KB.
 """
 
+import hashlib
 import json
 import urllib.error
 import urllib.request
@@ -65,14 +66,23 @@ class FontAwesomeOptimizer:
     sites.
     """
 
-    def __init__(self, icon_names: list[str]) -> None:
+    def __init__(
+        self,
+        icon_names: list[str],
+        metadata_url: str = FONTAWESOME_METADATA_URL,
+        webfonts_base: str = FONTAWESOME_CDN_WEBFONTS_BASE,
+    ) -> None:
         """Initialize the optimizer with the set of icons to include.
 
         Args:
             icon_names: List of FontAwesome brand icon names (e.g.
                 ``["github", "mastodon"]``).
+            metadata_url: URL to fetch FontAwesome icon metadata from.
+            webfonts_base: Base URL for webfont files.
         """
         self.icon_names = icon_names
+        self.metadata_url = metadata_url
+        self.webfonts_base = webfonts_base
 
     def fetch_icon_metadata(self) -> dict[str, Any]:
         """Fetch FontAwesome icon metadata with local caching.
@@ -91,7 +101,8 @@ def fetch_icon_metadata(self) -> dict[str, Any]:
             ValueError: If the response cannot be parsed as JSON.
         """
         cache_dir = get_user_cache_dir()
-        cache_file = cache_dir / f"fa-metadata-{FONTAWESOME_VERSION}.json"
+        url_hash = hashlib.sha256(self.metadata_url.encode("utf-8")).hexdigest()[:12]
+        cache_file = cache_dir / f"fa-metadata-{url_hash}.json"
 
         # Try to load from cache first
         if cache_file.exists():
@@ -102,7 +113,7 @@ def fetch_icon_metadata(self) -> dict[str, Any]:
                 pass
 
         # Network fetch
-        with urllib.request.urlopen(FONTAWESOME_METADATA_URL) as response:
+        with urllib.request.urlopen(self.metadata_url) as response:
             content = response.read().decode("utf-8")
 
         # Update cache
@@ -128,8 +139,8 @@ def build_css(self, metadata: dict[str, Any]) -> str:
             rules, and one `::before` rule per requested icon found in the
             metadata.
         """
-        woff2_url = f"{FONTAWESOME_CDN_WEBFONTS_BASE}/fa-brands-400.woff2"
-        ttf_url = f"{FONTAWESOME_CDN_WEBFONTS_BASE}/fa-brands-400.ttf"
+        woff2_url = f"{self.webfonts_base.rstrip('/')}/fa-brands-400.woff2"
+        ttf_url = f"{self.webfonts_base.rstrip('/')}/fa-brands-400.ttf"
 
         lines: list[str] = [
             "@font-face {",

src/blogmore/generator/assets.py

@@ -15,7 +15,6 @@
 from blogmore.code_styles import build_code_css
 from blogmore.console import print_warning, timed_step
 from blogmore.fontawesome import (
-    FONTAWESOME_CDN_CSS_URL,
     FONTAWESOME_LOCAL_CSS_MINIFIED_PATH,
     FONTAWESOME_LOCAL_CSS_PATH,
     FontAwesomeOptimizer,
@@ -47,7 +46,9 @@ def __init__(self, site_config: SiteConfig) -> None:
             site_config: The site configuration.
         """
         self.site_config = site_config
-        self.fontawesome_css_url: str = FONTAWESOME_CDN_CSS_URL
+        self.fontawesome_css_url: str = site_config.third_party["fontawesome"][
+            "css_url"
+        ]
         self._fontawesome_css_content: str | None = None
         self.extras_html_paths: frozenset[str] = frozenset()
 
@@ -175,15 +176,21 @@ def prepare_fontawesome_css(self) -> str | None:
             for social in socials
             if isinstance(social, dict) and "site" in social
         ]
-        optimizer = FontAwesomeOptimizer(icon_names)
+        optimizer = FontAwesomeOptimizer(
+            icon_names,
+            metadata_url=self.site_config.third_party["fontawesome"]["metadata_url"],
+            webfonts_base=self.site_config.third_party["fontawesome"]["webfonts_base"],
+        )
 
         try:
             with timed_step("Downloading FontAwesome metadata..."):
                 metadata = optimizer.fetch_icon_metadata()
         except (urllib.error.URLError, ValueError, OSError) as error:
             print_warning(f"Warning: Could not fetch FontAwesome metadata: {error}")
             print_warning("Falling back to full FontAwesome CDN stylesheet.")
-            self.fontawesome_css_url = FONTAWESOME_CDN_CSS_URL
+            self.fontawesome_css_url = self.site_config.third_party["fontawesome"][
+                "css_url"
+            ]
             return None
 
         self.fontawesome_css_url = (

src/blogmore/generator/context.py

@@ -6,7 +6,6 @@
 
 from blogmore import __version__
 from blogmore.clean_url import make_url_clean
-from blogmore.fontawesome import FONTAWESOME_CDN_BRANDS_WOFF2_URL
 from blogmore.generator.constants import (
     ARCHIVE_CSS_FILENAME,
     BUNDLE_CSS_FILENAME,
@@ -264,7 +263,14 @@ def get_global_context(self) -> dict[str, Any]:
             "theme_js_content": self.theme_js_content,
             "fontawesome_is_bundled": self.fontawesome_is_bundled,
             "fontawesome_css_url": self.with_cache_bust(self.fontawesome_css_url),
-            "fontawesome_woff2_url": FONTAWESOME_CDN_BRANDS_WOFF2_URL,
+            "fontawesome_woff2_url": self.site_config.third_party["fontawesome"][
+                "woff2_url"
+            ],
+            "mermaid_script_url": self.site_config.third_party["mermaid"]["script_url"],
+            "katex_css_url": self.site_config.third_party["katex"]["css_url"],
+            "katex_js_url": self.site_config.third_party["katex"]["js_url"],
+            "mathjax_js_url": self.site_config.third_party["mathjax"]["js_url"],
+            "force_graph_js_url": self.site_config.third_party["force_graph"]["js_url"],
             "styles_css_url": self.get_asset_url(
                 CSS_FILENAME, self.site_config.minify_css
             ),