Docs WIP

docs/.overrides/hooks/shortcodes.py

@@ -0,0 +1,317 @@
+"""Shortcode hook copied from the mkdocs-material project, then simplified.
+
+https://github.com/squidfunk/mkdocs-material/blob/master/material/overrides/hooks/shortcodes.py
+"""
+
+# Copyright (c) 2016-2024 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 re import Match
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.files import File
+    from mkdocs.structure.files import Files
+    from mkdocs.structure.pages import Page
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+
+# @todo
+def on_page_markdown(
+    markdown: str,
+    *,
+    page: Page,
+    config: MkDocsConfig,  # noqa: ARG001
+    files: Files,
+):
+
+    # Replace callback
+    def replace(match: Match):
+        _type, args = match.groups()
+        args = args.strip()
+        if _type == "version":
+            # if args.startswith("insiders-"):
+            #     return _badge_for_version_insiders(args, page, files)
+            return _badge_for_version(args, page, files)
+        # if _type == "sponsors":
+        #     return _badge_for_sponsors(page, files)
+        if _type == "flag":
+            return flag(args, page, files)
+        # if _type == "option":
+        #     return option(args)
+        # if _type == "setting":
+        #     return setting(args)
+        # if _type == "feature":
+        #     return _badge_for_feature(args, page, files)
+        # if _type == "plugin":
+        #     return _badge_for_plugin(args, page, files)
+        # if _type == "extension":
+        #     return _badge_for_extension(args, page, files)
+        # if _type == "utility":
+        #     return _badge_for_utility(args, page, files)
+        # if _type == "example":
+        #     return _badge_for_example(args, page, files)
+        if _type == "shopify":
+            return _badge_for_shopify_compatible(page, files)
+        if _type == "liquid2":
+            return _badge_for_liquid2(page, files)
+        # if _type == "default":
+        #     if args == "none":
+        #         return _badge_for_default_none(page, files)
+        #     if args == "shopify":
+        #         return _badge_for_shopify_compatible(page, files)
+        #     return _badge_for_default(args, page, files)
+
+        # Otherwise, raise an error
+        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)
+
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+
+# Create a flag of a specific type
+def flag(args: str, page: Page, files: Files):
+    _type, *_ = args.split(" ", 1)
+    if _type == "experimental":
+        return _badge_for_experimental(page, files)
+    if _type == "required":
+        return _badge_for_required(page, files)
+    if _type == "customization":
+        return _badge_for_customization(page, files)
+    if _type == "metadata":
+        return _badge_for_metadata(page, files)
+    if _type == "multiple":
+        return _badge_for_multiple(page, files)
+    raise RuntimeError(f"Unknown type: {_type}")
+
+
+# Create a linkable option
+def option(type: str):
+    _, *_, name = re.split(r"[.:]", type)
+    return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
+
+
+# Create a linkable setting - @todo append them to the bottom of the page
+def setting(type: str):
+    _, *_, name = re.split(r"[.*]", type)
+    return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
+
+
+# -----------------------------------------------------------------------------
+
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve_path(path: str, page: Page, files: Files):
+    path, anchor, *_ = f"{path}#".split("#")
+    path = _resolve(files.get_file_from_path(path), page)
+    return "#".join([path, anchor]) if anchor else path
+
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve(file: File, page: Page):
+    path = posixpath.relpath(file.src_uri, page.file.src_uri)
+    return posixpath.sep.join(path.split(posixpath.sep)[1:])
+
+
+# -----------------------------------------------------------------------------
+
+
+# Create badge
+def _badge(icon: str, text: str = "", type: str = ""):
+    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 []),
+            "</span>",
+        ]
+    )
+
+
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+    icon = "material-heart"
+    href = _resolve_path("insiders/index.md", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Sponsors only')", type="heart")
+
+
+# Create badge for version
+def _badge_for_version(text: str, page: Page, files: Files):
+    icon = "material-tag-outline"
+    href = _resolve_path("conventions.md#version", page, files)
+    return _badge(
+        icon=f"[:{icon}:]({href} 'Minimum version')",
+        text=text or "",
+    )
+
+
+# Create badge for version of Insiders
+def _badge_for_version_insiders(text: str, page: Page, files: Files):
+    spec = text.replace("insiders-", "")
+    path = f"insiders/changelog/index.md#{spec}"
+
+    # Return badge
+    icon = "material-tag-heart-outline"
+    href = _resolve_path("conventions.md#version-insiders", page, files)
+    return _badge(
+        icon=f"[:{icon}:]({href} 'Minimum version')",
+        text=f"[{text}]({_resolve_path(path, page, files)})" if spec else "",
+    )
+
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+    icon = "material-toggle-switch"
+    href = _resolve_path("conventions.md#feature", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Optional feature')", text=text)
+
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+    icon = "material-floppy"
+    href = _resolve_path("conventions.md#plugin", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Plugin')", text=text)
+
+
+# Create badge for extension
+def _badge_for_extension(text: str, page: Page, files: Files):
+    icon = "material-language-markdown"
+    href = _resolve_path("conventions.md#extension", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Markdown extension')", text=text)
+
+
+# Create badge for utility
+def _badge_for_utility(text: str, page: Page, files: Files):
+    icon = "material-package-variant"
+    href = _resolve_path("conventions.md#utility", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Third-party utility')", text=text)
+
+
+# Create badge for example
+def _badge_for_example(text: str, page: Page, files: Files):
+    return "\n".join(
+        [
+            _badge_for_example_download(text, page, files),
+            _badge_for_example_view(text, page, files),
+        ]
+    )
+
+
+# Create badge for example view
+def _badge_for_example_view(
+    text: str,
+    page: Page,  # noqa: ARG001
+    files: Files,  # noqa: ARG001
+):
+    icon = "material-folder-eye"
+    href = f"https://mkdocs-material.github.io/examples/{text}/"
+    return _badge(icon=f"[:{icon}:]({href} 'View example')", type="right")
+
+
+# Create badge for example download
+def _badge_for_example_download(
+    text: str,
+    page: Page,  # noqa: ARG001
+    files: Files,  # noqa: ARG001
+):
+    icon = "material-folder-download"
+    href = f"https://mkdocs-material.github.io/examples/{text}.zip"
+    return _badge(
+        icon=f"[:{icon}:]({href} 'Download example')",
+        text=f"[`.zip`]({href})",
+        type="right",
+    )
+
+
+# Create badge for default value
+def _badge_for_default(text: str, page: Page, files: Files):
+    icon = "material-water"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Default value')", text=text)
+
+
+# Create badge for empty default value
+def _badge_for_default_none(page: Page, files: Files):
+    icon = "material-water-outline"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Default value is empty')")
+
+
+def _badge_for_liquid2(page: Page, files: Files):
+    icon = "material-water-plus-outline"
+    href = _resolve_path("conventions.md#liquid2", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'New to Liquid2')")
+
+
+def _badge_for_shopify_compatible(page: Page, files: Files):
+    icon = "material-water-check-outline"
+    href = _resolve_path("conventions.md#shopify", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Shopify/Liquid compatible')")
+
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+    icon = "material-list-box-outline"
+    href = _resolve_path("conventions.md#metadata", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Metadata property')")
+
+
+# Create badge for required value flag
+def _badge_for_required(page: Page, files: Files):
+    icon = "material-alert"
+    href = _resolve_path("conventions.md#required", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Required value')")
+
+
+# Create badge for customization flag
+def _badge_for_customization(page: Page, files: Files):
+    icon = "material-brush-variant"
+    href = _resolve_path("conventions.md#customization", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Customization')")
+
+
+# Create badge for multiple instance flag
+def _badge_for_multiple(page: Page, files: Files):
+    icon = "material-inbox-multiple"
+    href = _resolve_path("conventions.md#multiple-instances", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Multiple instances')")
+
+
+# Create badge for experimental flag
+def _badge_for_experimental(page: Page, files: Files):
+    icon = "material-flask-outline"
+    href = _resolve_path("conventions.md#experimental", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Experimental')")

docs/conventions.md

@@ -0,0 +1,19 @@
+# Conventions
+
+Throughout this documentation we use icons to indicate if a feature is experimental, compatible with shopify and what version it was introduced.
+
+## <!-- md:version --> – Version { data-toc-label="Version" }
+
+Shows the minimum version of Liquid2 that is required to use a feature.
+
+## <!-- md:flag experimental --> – Experimental { data-toc-label="Experimental" }
+
+Indicates that the feature or example code is experimental and might be changed without warning or appropriate semantic versioning.
+
+## <!-- md:shopify --> – Shopify/Liquid compatible { #shopify data-toc-label="Shopify compatible" }
+
+Indicates that the feature or example code is compatible with [Shopify/Liquid](https://github.com/Shopify/liquid).
+
+## <!-- md:liquid2 --> – New to Liquid2 { #liquid2 data-toc-label="New to Liquid2" }
+
+Indicates that the feature or example code is new to Liquid2 and **not** compatible with [Shopify/Liquid](https://github.com/Shopify/liquid).