Restructured project

.editorconfig

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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

.github/FUNDING.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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

.github/workflows/documentation.yml

@@ -0,0 +1,81 @@
+# 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.
+
+name: documentation
+on:
+  push:
+    branches:
+      - master
+
+env:
+  PYTHON_VERSION: 3.x
+
+permissions:
+  contents: write
+
+jobs:
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python runtime
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Set the date environmental variable
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Set up build cache
+        uses: actions/cache@v3
+        id: cache
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: sudo apt-get install pngquant
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
+      - name: Install Insiders
+        if: github.event.repository.fork == false
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: |
+          pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+
+      - name: Deploy documentation
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          PYTHONPATH: .
+          # GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
+        run: |
+          mkdocs gh-deploy --force
+          mkdocs --version

.gitignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <[email protected]>
+# 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
@@ -25,6 +25,13 @@
 # Dependencies
 /venv
 
+# Build files
+build
+site
+
+# Generated files
+*.zip
+
 # Caches and logs
 *.log
 .cache

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2022 Martin Donath <[email protected]>
+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

docs/index.md

@@ -1,4 +1,4 @@
-# Example
+# Examples
 
 This project lists all options that are supported by Material for MkDocs and
 can be used as a basis for new projects or reproductions. Note that some options
@@ -8,6 +8,3 @@ to be sure.
   [sponsors]: https://squidfunk.github.io/mkdocs-material/insiders/
   [available features]: https://squidfunk.github.io/mkdocs-material/insiders/#whats-in-for-me
 
-``` yaml
---8<-- "mkdocs.yml"
-```

examples/__init__.py

@@ -0,0 +1,54 @@
+# 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.
+
+import os
+import posixpath
+
+from mergedeep import merge
+from mkdocs.config.defaults import MkDocsConfig
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+# Transform project configuration
+def transform(project: MkDocsConfig, config: MkDocsConfig):
+    root = os.path.dirname(project.config_file_path)
+    name = os.path.basename(root)
+
+    # Inherit settings for repository
+    project.repo_name = config.repo_name
+    project.repo_url  = config.repo_url
+
+    # Inherit settings for site URL and edit URI
+    project.site_url = posixpath.join(config.site_url, name, "")
+    project.edit_uri = f"edit/master/examples/{name}/docs/"
+
+    # Inherit settings for copyright
+    project.copyright = config.copyright
+
+    # Inherit settings for theme
+    merge(project.theme["icon"], config.theme["icon"])
+    project.theme["features"].extend(config.theme["features"])
+
+    root = os.path.dirname(config.config_file_path)
+    project.hooks = [
+        os.path.join(root, "hooks", "zip.py")
+    ]

packages/tags-with-icons/docs/README.md → examples/tags-with-icons/docs/README.md

@@ -10,12 +10,12 @@ This example includes the following pages:
 - [Page 2] – Page with tags [JavaScript] and [CSS]
 - [Tags] – Tags index
 
-  [Page 1]: pages/page-1.md
-  [Page 2]: pages/page-2.md
-  [Tags]: pages/tags.md
-  [HTML]: pages/tags.md#html
-  [JavaScript]: pages/tags.md#javascript
-  [CSS]: pages/tags.md#css
+  [Page 1]: demo/page-1.md
+  [Page 2]: demo/page-2.md
+  [Tags]: demo/tags.md
+  [HTML]: demo/tags.md#html
+  [JavaScript]: demo/tags.md#javascript
+  [CSS]: demo/tags.md#css
 
 Download example as archive:
 
@@ -28,4 +28,4 @@ pip install -r requirements.txt
 mkdocs serve
 ```
 
-  [Download]: https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/mkdocs-material/examples/tree/master/examples/tags
+  [Download]: download.zip

packages/tags-with-icons/mkdocs.yml → examples/tags-with-icons/mkdocs.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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
@@ -25,11 +25,6 @@
 # Project information
 site_name: Using tags with icons
 
-# Repository
-repo_name: mkdocs-material/examples
-repo_url: https://github.com/mkdocs-material/examples
-edit_uri: edit/master/examples/tags-with-icons/docs
-
 # Theme
 theme:
   name: material
@@ -45,7 +40,7 @@ theme:
 plugins:
   - search
   - tags:
-      tags_file: pages/tags.md
+      tags_file: demo/tags.md
 
 # Extra configuration
 extra:

packages/tags-with-icons/requirements.txt → examples/tags-with-icons/requirements.txt

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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

packages/tags/docs/README.md → examples/tags/docs/README.md

@@ -10,12 +10,12 @@ This example includes the following pages:
 - [Page 2] – Page with tags [JavaScript] and [CSS]
 - [Tags] – Tags index
 
-  [Page 1]: pages/page-1.md
-  [Page 2]: pages/page-2.md
-  [Tags]: pages/tags.md
-  [HTML]: pages/tags.md#html
-  [JavaScript]: pages/tags.md#javascript
-  [CSS]: pages/tags.md#css
+  [Page 1]: demo/page-1.md
+  [Page 2]: demo/page-2.md
+  [Tags]: demo/tags.md
+  [HTML]: demo/tags.md#html
+  [JavaScript]: demo/tags.md#javascript
+  [CSS]: demo/tags.md#css
 
 Download example as archive:
 
@@ -28,4 +28,4 @@ pip install -r requirements.txt
 mkdocs serve
 ```
 
-  [Download]: https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/mkdocs-material/examples/tree/master/examples/tags
+  [Download]: download.zip

packages/tags/mkdocs.yml → examples/tags/mkdocs.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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
@@ -23,24 +23,31 @@
 # -----------------------------------------------------------------------------
 
 # Project information
-site_name: Using tags
-
-# Repository
-repo_name: mkdocs-material/examples
-repo_url: https://github.com/mkdocs-material/examples
-edit_uri: edit/master/examples/tags/docs
+site_name: Using tags with icons
 
 # Theme
 theme:
   name: material
   features:
     - navigation.sections
+  icon:
+    tag:
+      css: simple/css3
+      html: simple/html5
+      js: simple/javascript
 
 # Plugins
 plugins:
   - search
   - tags:
-      tags_file: pages/tags.md
+      tags_file: demo/tags.md
+
+# Extra configuration
+extra:
+  tags:
+    CSS: css
+    HTML: html
+    JavaScript: js
 
 # Markdown extensions
 markdown_extensions:

packages/tags/requirements.txt → examples/tags/requirements.txt

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 Martin Donath <[email protected]>
+# 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

hooks/zip.py

@@ -0,0 +1,55 @@
+# 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.
+
+import os
+
+from glob import iglob
+from mkdocs.config.defaults import MkDocsConfig
+from zipfile import ZipFile, ZIP_DEFLATED
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+# Create an archive
+def on_pre_build(config: MkDocsConfig):
+    base = os.path.dirname(config.config_file_path)
+    project_name = os.path.basename(base)
+
+    archive = f"{config.docs_dir}/download.zip"
+    with ZipFile(archive, "w", ZIP_DEFLATED, False) as f:
+        for name in os.listdir(base):
+            # @todo: load ignore patterns from .gitignore
+            if name == "site":
+                continue
+            if name.endswith(".zip"):
+                continue
+
+            # Find all files recursively and add them to the archive
+            path = os.path.join(base, name)
+            if os.path.isdir(path):
+                path = os.path.join(path, "**")
+
+            # @todo
+            for file in iglob(path, recursive = True):
+                f.write(
+                    file,
+                    os.path.join(project_name, os.path.relpath(file, base))
+                )