Merge pull request #1 from mkdocs-material/docs/add-more-examples

squidfunk · web-flow · commit b657fb7f159e · 2023-09-20T19:37:49.000+02:00
New examples for colors
diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
 # Examples
 
-- [Tags]
-- [Tags with icons]
+This repository contains runnable examples for [Material for MkDocs].
 
-  [Tags]: example/tags/
-  [Tags with icons]: examples/tags-with-icons/
+  [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
diff --git a/examples/__init__.py b/examples/__init__.py
@@ -45,5 +45,8 @@ def transform(project: MkDocsConfig, config: MkDocsConfig):
     project.copyright = config.copyright
 
     # Inherit settings for theme
-    merge(project.theme["icon"], config.theme["icon"])
     project.theme["features"].extend(config.theme["features"])
+    if "icon" in project.theme:
+        merge(project.theme["icon"], config.theme["icon"])
+    else:
+        project.theme["icon"] = config.theme["icon"]
diff --git a/examples/color-palette-system-preference/docs/README.md b/examples/color-palette-system-preference/docs/README.md
@@ -0,0 +1,8 @@
+# Using the color palette system preference
+
+This example shows how to implement the [color palette toggle] so that it
+automatically uses the user's [system preference]. Click on the button left
+to the search bar to switch between modes.
+
+  [color palette toggle]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle
+  [system preference]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
diff --git a/examples/color-palette-system-preference/mkdocs.yml b/examples/color-palette-system-preference/mkdocs.yml
@@ -0,0 +1,59 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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 the color palette system preference
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.sections
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/color-palette-system-preference/requirements.txt b/examples/color-palette-system-preference/requirements.txt
@@ -0,0 +1,21 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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/color-palette-toggle/docs/README.md b/examples/color-palette-toggle/docs/README.md
@@ -0,0 +1,7 @@
+# Using the color palette toggle
+
+This example shows how to implement the [color palette toggle] to let users switch
+between light and dark mode. Click on the button left to the search bar to
+switch between modes.
+
+  [color palette toggle]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle
diff --git a/examples/color-palette-toggle/mkdocs.yml b/examples/color-palette-toggle/mkdocs.yml
@@ -0,0 +1,53 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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 the color palette toggle
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.sections
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/color-palette-toggle/requirements.txt b/examples/color-palette-toggle/requirements.txt
@@ -0,0 +1,21 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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/cookie-consent/docs/README.md b/examples/cookie-consent/docs/README.md
@@ -0,0 +1,11 @@
+---
+title: Overview
+---
+
+# Adding a cookie consent 
+
+This example shows how to add a [cookie consent]. [Click here] to bring
+up the cookie consent again.
+
+  [cookie consent]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent
+  [Click here]: #__consent
diff --git a/examples/cookie-consent/mkdocs.yml b/examples/cookie-consent/mkdocs.yml
@@ -0,0 +1,50 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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: Adding a cookie consent
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.sections
+
+# Additional configuration
+extra:
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/cookie-consent/requirements.txt b/examples/cookie-consent/requirements.txt
@@ -0,0 +1,21 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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/custom-colors/docs/README.md b/examples/custom-colors/docs/README.md
@@ -0,0 +1,6 @@
+# Using custom colors
+
+This example shows how to set [custom colors] with [additional CSS].
+
+  [custom colors]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#custom-colors
+  [additional CSS]: https://squidfunk.github.io/mkdocs-material/customization/#additional-css
diff --git a/examples/custom-colors/docs/stylesheets/extra.css b/examples/custom-colors/docs/stylesheets/extra.css
@@ -0,0 +1,5 @@
+:root > * {
+  --md-primary-fg-color:        #EE0F0F;
+  --md-primary-fg-color--light: #ECB7B7;
+  --md-primary-fg-color--dark:  #90030C;
+}
diff --git a/examples/custom-colors/mkdocs.yml b/examples/custom-colors/mkdocs.yml
@@ -0,0 +1,44 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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 custom colors
+
+# Theme
+theme:
+  name: material
+  features:
+    - navigation.sections
+
+# Additional CSS
+extra_css:
+  - stylesheets/extra.css
+
+# Markdown extensions
+markdown_extensions:
+  - attr_list
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
diff --git a/examples/custom-colors/requirements.txt b/examples/custom-colors/requirements.txt
@@ -0,0 +1,21 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# 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/custom-cookies/docs/README.md b/examples/custom-cookies/docs/README.md
@@ -0,0 +1,12 @@
+---
+title: Overview
+---
+
+# Adding a custom cookie
+
+This example shows how to add a [custom cookie] to the [cookie consent] and
+check if the user accepted it. [Click here] to bring up the cookie consent again.
+
+  [custom cookie]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#custom-cookies
+  [cookie consent]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent
+  [Click here]: #__consent
diff --git a/examples/custom-cookies/docs/javascripts/consent.js b/examples/custom-cookies/docs/javascripts/consent.js
@@ -0,0 +1,8 @@
+var consent = __md_get("__consent")
+if (consent) {
+  if (consent.custom) {
+    alert$.next("Custom cookie was accepted")
+  } else {
+    alert$.next("Custom cookie was rejected")
+  }
+}
diff --git a/examples/custom-cookies/mkdocs.yml b/examples/custom-cookies/mkdocs.yml
diff --git a/examples/custom-cookies/requirements.txt b/examples/custom-cookies/requirements.txt
diff --git a/examples/tags-with-icons/docs/README.md b/examples/tags-with-icons/docs/README.md
diff --git a/examples/tags-with-icons/mkdocs.yml b/examples/tags-with-icons/mkdocs.yml
diff --git a/examples/tags/docs/README.md b/examples/tags/docs/README.md
diff --git a/examples/tags/mkdocs.yml b/examples/tags/mkdocs.yml
diff --git a/mkdocs.yml b/mkdocs.yml
