Added demo repository badge (#7915)

* docs(shortcodes): Add example repository badge

* docs(shortcodes): Update description for 'Example Repository'

* docs(relations): link example repos in docs pages

* docs(shortcodes): Fix permanent link for convention page

* docs(shortcodes): Revert to commit 365dc24

* docs(shortcodes): Rename md:example to md:demonstration

* docs(shortcodes): Fix examples url

* docs(shortcodes): Add demo badge

* docs(shortcodes): Add badges for demo repositories

* docs(shortcodes): Replace md:demonstration with md:example

* docs(shortcodes): Replace demonstration with example

* docs(shortcodes): Replace demonstration with example

* docs(shortcodes): Build new theme

* docs(shortcodes): Build with pymdownx

docs/conventions.md

@@ -91,3 +91,4 @@ Besides plugins, there are some utilities that build on top of MkDocs in order
 to provide extended functionality, like for example support for versioning.
 
   [Insiders]: insiders/index.md
+

docs/setup/setting-up-a-blog.md

@@ -22,6 +22,7 @@ __Check out our [blog], which is created with the new [built-in blog plugin]!__
 <!-- md:version 9.2.0 -->
 <!-- md:plugin -->
 <!-- md:flag experimental -->
+<!-- md:demo create-blog -->
 
 The built-in blog plugin adds support for building a blog from a folder of
 posts, which are annotated with dates and other structured data. First, add the

docs/setup/setting-up-social-cards.md

@@ -37,6 +37,7 @@ Social card of our [formatting] reference
 <!-- md:version 8.5.0 -->
 <!-- md:plugin -->
 <!-- md:flag experimental -->
+<!-- md:demo create-social-cards -->
 
 The built-in social plugin automatically generate a custom preview image for
 each page. Install all [dependencies for image processing] and add the

docs/setup/setting-up-versioning.md

@@ -13,6 +13,7 @@ documentation remain untouched.
 
 <!-- md:version 7.0.0 -->
 <!-- md:utility [mike] -->
+<!-- md:demo example-versioning -->
 
 [mike] makes it easy to deploy multiple versions of your project documentation.
 It integrates natively with Material for MkDocs and can be enabled via

material/overrides/hooks/shortcodes.py

@@ -54,7 +54,8 @@ def on_page_markdown(
         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 == "example": return _badge_for_example(args, page, files)
+        elif type == "demo":         return _badge_for_demo(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)
@@ -212,11 +213,21 @@ 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')",
+        icon = f"[:{icon}:]({href} 'Download example files')",
         text = f"[`.zip`]({href})",
         type = "right"
     )
 
+# Create badge for demo repository
+def _badge_for_demo(text: str, page: Page, files: Files):
+    icon = "material-github"
+    href = f"https://github.com/mkdocs-material/{text}"
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Demo repository')",
+        text = text,
+        type = "right"
+    )
+
 # Create badge for default value
 def _badge_for_default(text: str, page: Page, files: Files):
     icon = "material-water"
@@ -280,4 +291,4 @@ def _badge_for_experimental(page: Page, files: Files):
     href = _resolve_path("conventions.md#experimental", page, files)
     return _badge(
         icon = f"[:{icon}:]({href} 'Experimental')"
-    )
+    )

src/overrides/hooks/shortcodes.py

@@ -54,7 +54,8 @@ def on_page_markdown(
         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 == "example": return _badge_for_example(args, page, files)
+        elif type == "demo":         return _badge_for_demo(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)
@@ -212,11 +213,21 @@ 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')",
+        icon = f"[:{icon}:]({href} 'Download example files')",
         text = f"[`.zip`]({href})",
         type = "right"
     )
 
+# Create badge for demo repository
+def _badge_for_demo(text: str, page: Page, files: Files):
+    icon = "material-github"
+    href = f"https://github.com/mkdocs-material/{text}"
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Demo repository')",
+        text = text,
+        type = "right"
+    )
+
 # Create badge for default value
 def _badge_for_default(text: str, page: Page, files: Files):
     icon = "material-water"
@@ -280,4 +291,4 @@ def _badge_for_experimental(page: Page, files: Files):
     href = _resolve_path("conventions.md#experimental", page, files)
     return _badge(
         icon = f"[:{icon}:]({href} 'Experimental')"
-    )
+    )