Add version and feature badges

Author: barryvdh

docs/collectors.md

@@ -89,6 +89,9 @@ To enable or disable any of the collectors, set the configuration to `true` or `
 
 ### QueryCollector
 
+<!-- md:version v1.0 -->
+<!-- md:feature collectors.db -->
+
 The Query Collector has the following features
  - Show the executed queries including timing
  - Show/mark duplicate queries
@@ -104,6 +107,8 @@ The Query Collector has the following features
 
 ![Query Collector](img/queries.png)
 
+<details><summary>config/debugbar.php</summary>
+
 ```php
   'options' => [
         // ...
@@ -129,10 +134,12 @@ The Query Collector has the following features
         // ...
     ],
 ```
+</details>
 
 #### On-demand query EXPLAIN
 
 <!-- md:version v3.14.0 -->
+<!-- md:feature options.db.explain -->
 <!-- md:flag experimental -->
 
 Enable the `options.db.explain` option to run on-demand EXPLAIN queries for any SELECT query in the Debugbar.

docs/features.md

@@ -143,4 +143,22 @@ If your working in a remote host or docker, you can change the mapping between r
 
 ```
 
-</details>
+</details>
+
+## Configuraton
+
+### Custom features { #custom }
+
+Custom features or collectors are not enabled by default, but can be enabled by enabling the configuration setting.
+This is usually because the target audience of a feature is not large enough.
+
+### Configurable options { #config }
+
+Configurable features are not enabled by default, but can be enabled. This is usually because the target audience of a feature is not large enough.
+You can enable the feature by changing the mentioned value in [config/debugbar.php](https://github.com/barryvdh/laravel-debugbar/blob/master/config/debugbar.php) after [publishing the config](installation.md#publish-config).
+
+### Experimental Features  { #experimental }
+
+Some features are marked as 'Experimental'. This mostly means the feature is new and not enabled by default, but might become enable by default in the future.
+You are welcome to test this feature and report any issues. 
+

docs/overrides/shortcodes.py

@@ -1,7 +1,5 @@
-## File based on https://github.com/processone/docs.ejabberd.im/blob/master/shortcodes.py and
-## https://github.com/squidfunk/mkdocs-material/tree/master/material/overrides/hooks
-
 # Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
+# Copy from https://github.com/squidfunk/mkdocs-material/blob/master/src/overrides/hooks/shortcodes.py
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -45,8 +43,23 @@ 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)
+            else:
                 return _badge_for_version(args, page, files)
+        elif type == "sponsors":     return _badge_for_sponsors(page, files)
         elif type == "flag":         return flag(args, page, files)
+        elif type == "option":       return option(args)
+        elif type == "setting":      return setting(args)
+        elif type == "feature":      return _badge_for_feature(args, page, files)
+        elif type == "plugin":       return _badge_for_plugin(args, page, files)
+        elif type == "extension":    return _badge_for_extension(args, page, files)
+        elif type == "utility":      return _badge_for_utility(args, page, files)
+        elif type == "example":      return _badge_for_example(args, page, files)
+        elif type == "default":
+            if   args == "none":     return _badge_for_default_none(page, files)
+            elif args == "computed": return _badge_for_default_computed(page, files)
+            else:                    return _badge_for_default(args, page, files)
 
         # Otherwise, raise an error
         raise RuntimeError(f"Unknown shortcode: {type}")
@@ -58,13 +71,46 @@ def replace(match: Match):
     )
 
 # -----------------------------------------------------------------------------
+# 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)
-
+    elif type == "required":      return _badge_for_required(page, files)
+    elif type == "customization": return _badge_for_customization(page, files)
+    elif type == "metadata":      return _badge_for_metadata(page, files)
+    elif 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"
@@ -75,6 +121,14 @@ def _badge(icon: str, text: str = "", type: str = ""):
         f"</span>",
     ])
 
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+    icon = "material-heart"
+    href = _resolve_path("features.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):
@@ -83,24 +137,135 @@ def _badge_for_version(text: str, page: Page, files: Files):
 
     # Return badge
     icon = "material-tag-outline"
+    href = f"{path}"
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Minimum version')",
+        text = f"[{text}]({path})" if spec else ""
+    )
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+    icon = "material-toggle-switch"
+    href = _resolve_path("features.md#config", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Configurable feature')",
+        text = text
+    )
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+    icon = "material-floppy"
+    href = _resolve_path("features.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("features.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("features.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, files: Files):
+    icon = "material-folder-eye"
+    href = f"https://mkdocs-material.github.io/examples/{text}/"
     return _badge(
-        icon = f"[:{icon}:]({path} 'Minimum version')",
-        text = f"{text}" if spec else ""
+        icon = f"[:{icon}:]({href} 'View example')",
+        type = "right"
+    )
+
+# Create badge for example download
+def _badge_for_example_download(text: str, page: Page, files: Files):
+    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("features.md#default", page, files)
     return _badge(
-        icon = f"[:{icon}:]('Default value')",
+        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("features.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is empty')"
+    )
+
+# Create badge for computed default value
+def _badge_for_default_computed(page: Page, files: Files):
+    icon = "material-water-check"
+    href = _resolve_path("features.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is computed')"
+    )
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+    icon = "material-list-box-outline"
+    href = _resolve_path("features.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("features.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("features.md#custom", 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("features.md#experimental", 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("features.md#experimental-features", page, files)
     return _badge(
-        icon = f"[:{icon}:]('Experimental')",
-        text = f"Experimental"
-    )
+        icon = f"[:{icon}:]({href} 'Experimental')"
+    )