mkdocs-material · squidfunk · Dec 22, 2023 · Dec 22, 2023 · Dec 22, 2023 · Apr 17, 2024
diff --git a/examples/__init__.py b/examples/__init__.py
@@ -45,7 +45,8 @@ def transform(project: Project, root: Project):
 
     # Inherit settings for site URL and edit URI
     project.config.site_url = posixpath.join(config.site_url, name, "")
-    project.config.edit_uri = f"edit/master/examples/{name}/docs/"
+    # @todo: fix relative path - messed up by repo_url
+    project.config.edit_uri = f"../../../../edit/master/examples/{name}/docs/"
 
     # Inherit settings for theme
     if "features" in project.config.theme:

diff --git a/examples/tags-hierarchy/docs/README.md b/examples/tags-hierarchy/docs/README.md
@@ -0,0 +1,33 @@
+# Using tags with hierarchies
+
+This example shows how to use [tags] with scoped listings to create listings
+that show pages under the current section. It includes the following pages:
+
+- [Tags] – Listing pages for tag <span class="md-tag">Section</span>
+
+- [Section 1] – Listing pages in scope of section 1
+
+    - [Page 1.1] – Page with tags <span class="md-tag">Code</span> and 
+      <span class="md-tag">Code/HTML</span>, and
+      <span class="md-tag">Code/JavaScript</span>
+
+    - [Page 1.2] – Page with tags <span class="md-tag">Code/JavaScript</span>
+      and <span class="md-tag">Code/CSS</span>
+
+- [Section 2] – Listing pages in scope of section 2
+
+    - [Page 2.1] – Page with tags <span class="md-tag">Code</span> and 
+      <span class="md-tag">Code/HTML</span>, and
+      <span class="md-tag">Code/JavaScript</span>
+
+    - [Page 2.2] – Page with tags <span class="md-tag">Code/JavaScript</span>
+      and <span class="md-tag">Code/CSS</span>
+
+  [tags]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/
+  [Tags]: demo/tags.md
+  [Section 1]: demo/section-1/index.md
+  [Page 1.1]: demo/section-1/page-1.md
+  [Page 1.2]: demo/section-1/page-2.md
+  [Section 2]: demo/section-2/index.md
+  [Page 2.1]: demo/section-2/page-1.md
+  [Page 2.2]: demo/section-2/page-2.md
diff --git a/examples/tags-hierarchy/docs/demo/section-1/index.md b/examples/tags-hierarchy/docs/demo/section-1/index.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Section
+---
+
+# Section 1
+
+## Tags
+
+<!-- material/tags { scope: true } -->
diff --git a/examples/tags-hierarchy/docs/demo/section-1/page-1.md b/examples/tags-hierarchy/docs/demo/section-1/page-1.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Code 
+  - Code/HTML
+  - Code/JavaScript
+---
+
+# Page 1.1
+
+...
diff --git a/examples/tags-hierarchy/docs/demo/section-1/page-2.md b/examples/tags-hierarchy/docs/demo/section-1/page-2.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - Code/JavaScript
+  - Code/CSS
+---
+
+# Page 1.2
+
+...
diff --git a/examples/tags-hierarchy/docs/demo/section-2/index.md b/examples/tags-hierarchy/docs/demo/section-2/index.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Section
+---
+
+# Section 2
+
+## Tags
+
+<!-- @tags { scope: true } -->
diff --git a/examples/tags-hierarchy/docs/demo/section-2/page-1.md b/examples/tags-hierarchy/docs/demo/section-2/page-1.md
@@ -0,0 +1,10 @@
+---
+tags: 
+  - Code 
+  - Code/HTML
+  - Code/JavaScript
+---
+
+# Page 2.1
+
+...
diff --git a/examples/tags-hierarchy/docs/demo/section-2/page-2.md b/examples/tags-hierarchy/docs/demo/section-2/page-2.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - Code/JavaScript
+  - Code/CSS
+---
+
+# Page 2.2
+
+...
diff --git a/examples/tags-hierarchy/docs/demo/tags.md b/examples/tags-hierarchy/docs/demo/tags.md
@@ -0,0 +1,3 @@
+# Tags
+
+<!-- material/tags { include: [Section] } -->
diff --git a/examples/tags-hierarchy/mkdocs.yml b/examples/tags-hierarchy/mkdocs.yml
@@ -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
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Recommended: set up configuration validation, see https://t.ly/xpZXU
+# -----------------------------------------------------------------------------
+
+# Project information
+site_name: Using tags with hierarchies
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.expand
+    - navigation.indexes
+    - navigation.sections
+
+# Plugins
+plugins:
+  - search
+  - tags:
+      tags_hierarchy: true
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/tags-hierarchy/requirements.txt b/examples/tags-hierarchy/requirements.txt
@@ -0,0 +1,21 @@
+# 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
+# IN THE SOFTWARE.
+
+mkdocs-material
diff --git a/examples/tags-scope/docs/README.md b/examples/tags-scope/docs/README.md
@@ -0,0 +1,31 @@
+# Using tags with scoped listings
+
+This example shows how to use [tags] with scoped listings to create listings
+that show pages under the current section. It includes the following pages:
+
+- [Tags] – Listing pages for tag <span class="md-tag">Section</span>
+
+- [Section 1] – Listing pages in scope of section 1
+
+    - [Page 1.1] – Page with tags <span class="md-tag">HTML</span> and 
+      <span class="md-tag">JavaScript</span>
+
+    - [Page 1.2] – Page with tags <span class="md-tag">JavaScript</span> and
+      <span class="md-tag">CSS</span>
+
+- [Section 2] – Listing pages in scope of section 2
+
+    - [Page 2.1] – Page with tags <span class="md-tag">HTML</span> and 
+      <span class="md-tag">JavaScript</span>
+
+    - [Page 2.2] – Page with tags <span class="md-tag">JavaScript</span> and
+      <span class="md-tag">CSS</span>
+
+  [tags]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/
+  [Tags]: demo/tags.md
+  [Section 1]: demo/section-1/index.md
+  [Page 1.1]: demo/section-1/page-1.md
+  [Page 1.2]: demo/section-1/page-2.md
+  [Section 2]: demo/section-2/index.md
+  [Page 2.1]: demo/section-2/page-1.md
+  [Page 2.2]: demo/section-2/page-2.md
diff --git a/examples/tags-scope/docs/demo/section-1/index.md b/examples/tags-scope/docs/demo/section-1/index.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Section
+---
+
+# Section 1
+
+## Tags
+
+<!-- @tags { scope: true } -->
diff --git a/examples/tags-scope/docs/demo/section-1/page-1.md b/examples/tags-scope/docs/demo/section-1/page-1.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - HTML
+  - JavaScript
+---
+
+# Page 1.1
+
+...
diff --git a/examples/tags-scope/docs/demo/section-1/page-2.md b/examples/tags-scope/docs/demo/section-1/page-2.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - JavaScript
+  - CSS
+---
+
+# Page 1.2
+
+...
diff --git a/examples/tags-scope/docs/demo/section-2/index.md b/examples/tags-scope/docs/demo/section-2/index.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Section
+---
+
+# Section 2
+
+## Tags
+
+<!-- @tags { scope: true } -->
diff --git a/examples/tags-scope/docs/demo/section-2/page-1.md b/examples/tags-scope/docs/demo/section-2/page-1.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - HTML
+  - JavaScript
+---
+
+# Page 2.1
+
+...
diff --git a/examples/tags-scope/docs/demo/section-2/page-2.md b/examples/tags-scope/docs/demo/section-2/page-2.md
@@ -0,0 +1,9 @@
+---
+tags:
+  - JavaScript
+  - CSS
+---
+
+# Page 2.2
+
+...
diff --git a/examples/tags-scope/docs/demo/tags.md b/examples/tags-scope/docs/demo/tags.md
@@ -0,0 +1,3 @@
+# Tags
+
+<!-- @tags { include: [Section] } -->
diff --git a/examples/tags-scope/mkdocs.yml b/examples/tags-scope/mkdocs.yml
@@ -0,0 +1,47 @@
+# 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
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Recommended: set up configuration validation, see https://t.ly/xpZXU
+# -----------------------------------------------------------------------------
+
+# Project information
+site_name: Using tags with scoped listings
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.expand
+    - navigation.indexes
+    - navigation.sections
+
+# Plugins
+plugins:
+  - search
+  - tags
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/tags-scope/requirements.txt b/examples/tags-scope/requirements.txt
@@ -0,0 +1,21 @@
+# 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
+# IN THE SOFTWARE.
+
+mkdocs-material
diff --git a/examples/tags-shadow/docs/README.md b/examples/tags-shadow/docs/README.md
@@ -0,0 +1,31 @@
+# Using shadow tags
+
+This example shows how to use shadow [tags] and includes the following pages:
+
+- [Tags] – Listing pages for tag <span class="md-tag md-tag-shadow">Draft</span>
+  and <span class="md-tag">Section</span>
+
+- [Section 1] – Listing pages in scope of section 1
+
+    - [Page 1.1] – Page with tags <span class="md-tag">HTML</span> and 
+      <span class="md-tag">JavaScript</span>
+
+    - [Page 1.2] – Page with tags <span class="md-tag">JavaScript</span> and
+      <span class="md-tag">CSS</span>
+
+- [Section 2] – Listing pages in scope of section 2
+
+    - [Page 2.1] – Page with tags <span class="md-tag">HTML</span> and 
+      <span class="md-tag">JavaScript</span>
+
+    - [Page 2.2] – Page with tags <span class="md-tag">JavaScript</span> and
+      <span class="md-tag">CSS</span>
+
+  [tags]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/
+  [Tags]: demo/tags.md
+  [Section 1]: demo/section-1/index.md
+  [Page 1.1]: demo/section-1/page-1.md
+  [Page 1.2]: demo/section-1/page-2.md
+  [Section 2]: demo/section-2/index.md
+  [Page 2.1]: demo/section-2/page-1.md
+  [Page 2.2]: demo/section-2/page-2.md
diff --git a/examples/tags-shadow/docs/demo/section-1/index.md b/examples/tags-shadow/docs/demo/section-1/index.md
@@ -0,0 +1,10 @@
+---
+tags:
+  - Section
+---
+
+# Section 1
+
+## Tags
+
+<!-- @tags { scope: true, exclude: [Draft] } -->
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Tags

		<!-- material/tags { include: [Section] } -->