feat(build): shortcode to mark version requirements

Author: SIMULATAN

docs/nodes/builtin/mapper.md

@@ -33,22 +33,23 @@ the correct data types, the names are simply incompatible.
 ## Liquid
 
 The Shopify-developed engine is a powerful and flexible templating language that allows for complex data
-transformations. It supports loops, conditionals, filters, and more. \
+transformations. It supports loops, conditionals, filters, and more.  
 The [Liqp](https://github.com/bkiers/Liqp) library provides the Liquid templating engine. Therefore, the behavior may
 not mimic the original Ruby-based Liquid engine perfectly. For the most part, it should work as expected though.
 
 As Liquid is a nicely documented language with a ton of features, please refer to the official documentation:
-https://shopify.github.io/liquid/basics/introduction/
+[https://shopify.github.io/liquid/basics/introduction/]
 
 Apart from the generic features, Snoty also provides some custom filters and tags:
 
-1. `unidiff` filter
+1. `unidiff` filter <!-- md:version 0.5.0 -->
     - This filter is used to convert a list of dictionaries into a unified diff format. It takes a list of dictionaries
       and returns a string representing the unified diff.
     - Example:
       ```liquid
       {% assign diff = diff.change.description.old | unidiff diff.change.description.new %}
       ```
+2. `format` filter <!-- md:version next -->
 
 ## Examples
 ### List all changes

docs/stylesheets/badges.css

@@ -0,0 +1,48 @@
+/*
+Copyright (c) 2016-2023 Martin Donath <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS
+*/
+
+.md-typeset .mdx-badge {
+  font-size: 0.85em;
+}
+
+.md-typeset .mdx-badge--right {
+  float: right;
+  margin-left: 0.35em;
+}
+
+.md-typeset .mdx-badge__icon {
+  padding: 0.25em;
+  background: var(--md-accent-fg-color--transparent);
+  border-start-start-radius: 0.25em;
+  border-end-start-radius: 0.25em;
+}
+
+.md-typeset .mdx-badge__icon:last-child {
+  border-radius: 0.25em;
+}
+
+.md-typeset .mdx-badge__text {
+  padding: 0.25em 0.5em;
+  border-start-end-radius: 0.25em;
+  border-end-end-radius: 0.25em;
+  box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
+}

mkdocs.yml

@@ -34,6 +34,9 @@ markdown_extensions:
   - pymdownx.blocks.caption
   - toc:
       permalink: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 extra:
   homepage: https://snoty.me
@@ -43,6 +46,10 @@ extra:
 extra_css:
   - stylesheets/logo.css
   - stylesheets/extra.css
+  - stylesheets/badges.css
+
+hooks:
+  - ./src/hooks/shortcodes.py
 
 nav:
   - Welcome: index.md

src/hooks/shortcodes.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2016-2025 Martin Donath <[email protected]>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from re import Match
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+def on_page_markdown(
+    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+):
+
+    # Replace callback
+    def replace(match: Match):
+        type, args = match.groups()
+        args = args.strip()
+        if type == "version":
+            return _badge_for_version(args, page, files)
+
+        raise RuntimeError(f"Unknown shortcode: {type}")
+
+    # Find and replace all external asset URLs in current page
+    return re.sub(
+        r"<!-- md:(\w+)(.*?) -->",
+        replace, markdown, flags = re.I | re.M
+    )
+
+def _badge(icon: str, text: str = "", type: str = ""):
+    print("makin")
+    classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
+    return "".join([
+        f"<span class=\"{classes}\">",
+        *([f"<span class=\"mdx-badge__icon\">{icon}</span>"] if icon else []),
+        *([f"<span class=\"mdx-badge__text\">{text}</span>"] if text else []),
+        f"</span>",
+    ])
+
+def _badge_for_version(text: str, page: Page, files: Files):
+    spec = text
+
+    repo_url = "https://github.com/SnotyMe/snoty-backend"
+
+    if spec == "next":
+        url = f"{repo_url}/tree/main"
+    else:
+        url = f"{repo_url}/releases/tag/{spec}"
+
+    text = f"[{spec}]({url})" + '{: target="_blank"}' if spec else ""
+    # dev is on a feature branch => not guaranteed to land in the next version => no link (could be anywhere)
+    if spec == "dev":
+        text = spec
+
+    icon = "material-tag-outline"
+    return _badge(
+        icon = f"[:{icon}:]('Available from version {spec}')",
+        text = text
+    )