Improved path checks by making them more explicit

Bump authors plugin in Dockerfile

.babelrc

@@ -1,10 +0,0 @@
-{
-  "presets": ["es2015"],
-  "plugins": [
-    "add-module-exports",
-    "babel-root-import",
-    ["transform-react-jsx", {
-      "pragma": "JSX.createElement"
-    }]
-  ]
-}

.browserslistrc

@@ -0,0 +1 @@
+last 4 years

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+	"name": "Material for MkDocs - VS Code dev container",
+	"image": "mcr.microsoft.com/devcontainers/typescript-node:0-18",
+	"features": {
+		"ghcr.io/devcontainers/features/python:1": {
+			"installTools": true,
+			"version": "3.11"
+	  }
+	},
+	"postCreateCommand": "pip install -e . && pip install mkdocs-minify-plugin mkdocs-redirects && npm install && npm run build"
+}

.dockerignore

@@ -0,0 +1,27 @@
+# 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.
+
+.cache
+.git
+.github
+docs
+material/.overrides
+node_modules
+src

.editorconfig

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+# 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
@@ -29,3 +29,12 @@ indent_size = 2
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
+
+# Markdown
+[*.md]
+trim_trailing_whitespace = false
+
+# Python
+[*.py]
+indent_style = space
+indent_size = 4

.eslintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+# 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
@@ -18,7 +18,38 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+# -----------------------------------------------------------------------------
+# Node, TypeScript, Python
+# -----------------------------------------------------------------------------
+
+# Dependencies
+node_modules
+__pycache__
+venv
+
 # Build files
-/build
-/material
-/site
+build
+MANIFEST
+manifest.json
+site
+
+# Configuration
+typings
+webpack.config.ts
+
+# Distribution files
+dist
+mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.eslintcache
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Temporary files
+tmp

.eslintrc

@@ -1,199 +1,350 @@
 {
-  "extends": "eslint:recommended",
-  "ecmaFeatures": {
-    "arrowFunctions": true,
-    "binaryLiterals": true,
-    "blockBindings": true,
-    "classes": true,
-    "defaultParams": true,
-    "destructuring": true,
-    "forOf": true,
-    "generators": true,
-    "globalReturn": true,
-    "modules": true,
-    "objectLiteralComputedProperties": true,
-    "objectLiteralDuplicateProperties": true,
-    "objectLiteralShorthandMethods": true,
-    "objectLiteralShorthandProperties": true,
-    "octalLiterals": true,
-    "regexUFlag": true,
-    "regexYFlag": true,
-    "spread": true,
-    "superInFunctions": false,
-    "templateStrings": true,
-    "unicodeCodePointEscapes": true
-  },
-  "env": {
-    "browser": true,
-    "es6": true,
-    "node": true
-  },
-  "globals": {
-    "Modernizr": true,
-    "navigator": true
-  },
-  "parser": "babel-eslint",
+  "root": true,
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
-    "ecmaVersion": 6,
-    "impliedStrict": true,
-    "sourceType": "module"
+    "project": "tsconfig.json"
+  },
+  "plugins": [
+    "@typescript-eslint",
+    "eslint-plugin-eslint-comments",
+    "eslint-plugin-import",
+    "eslint-plugin-jsdoc",
+    "eslint-plugin-no-null"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "settings": {
+    "import/extensions": [
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".json"
+    ],
+    "import/parsers": {
+      "@typescript-eslint/parser": [
+        ".ts",
+        ".tsx"
+      ]
+    }
   },
-  "plugins": [],
   "rules": {
-    "array-callback-return": 2,
-    "array-bracket-spacing": 2,
-    "arrow-parens": [2, "as-needed"],
-    "arrow-spacing": 2,
-    "block-scoped-var": 2,
-    "block-spacing": 2,
-    "brace-style": 2,
-    "camelcase": [2, {
-      "properties": "always"
-    }],
-    "comma-dangle": [2, "never"],
-    "comma-style": [2, "last"],
-    "complexity": 2,
-    "computed-property-spacing": 2,
-    "consistent-this": 2,
-    "dot-notation": 2,
-    "eol-last": 2,
-    "eqeqeq": 2,
-    "func-call-spacing": 2,
-    "func-names": [2, "never"],
-    "func-style": 2,
-    "generator-star-spacing": 2,
-    "indent": [2, 2, {
-      "FunctionDeclaration": {
-        "body": 1,
-        "parameters": 2
-      },
-      "FunctionExpression": {
-        "body": 1,
-        "parameters": 2
-      },
-      "MemberExpression": 1,
-      "VariableDeclarator": {
-        "var": 2,
-        "let": 2,
-        "const": 3
-      },
-      "SwitchCase": 1
-    }],
-    "init-declarations": 2,
-    "key-spacing": 2,
-    "keyword-spacing": 2,
-    "linebreak-style": 2,
-    "lines-around-comment": 2,
-    "lines-around-directive": 2,
-    "max-depth": 2,
-    "max-len": [1, {
-      "ignorePattern": "\/\/ TODO"
-    }],
-    "max-nested-callbacks": 2,
-    "max-params": 2,
-    "max-statements-per-line": 2,
-    "new-cap": 2,
-    "newline-per-chained-call": 2,
-    "no-array-constructor": 2,
-    "no-alert": 2,
-    "no-caller": 2,
-    "no-confusing-arrow": [2, {
-      "allowParens": false
-    }],
-    "no-console": 1,
-    "no-duplicate-imports": 2,
-    "no-eq-null": 2,
-    "no-eval": 2,
-    "no-extend-native": 2,
-    "no-extra-bind": 2,
-    "no-floating-decimal": 2,
-    "no-global-assign": 2,
-    "no-invalid-this": 2,
-    "no-labels": 2,
-    "no-lone-blocks": 2,
-    "no-loop-func": 2,
-    "no-multiple-empty-lines": [1, {
-      "max": 1
-    }],
-    "no-nested-ternary": 2,
-    "no-new": 0,
-    "no-new-object": 2,
-    "no-param-reassign": 2,
-    "no-prototype-builtins": 2,
-    "no-shadow": 2,
-    "no-tabs": 2,
-    "no-template-curly-in-string": 2,
-    "no-throw-literal": 2,
-    "no-trailing-spaces": 2,
-    "no-undefined": 2,
-    "no-underscore-dangle": [2, {
-      "allowAfterThis": true,
-      "allowAfterSuper": true
-    }],
-    "no-unneeded-ternary": 2,
-    "no-unsafe-negation": 2,
-    "no-unused-expressions": 2,
-    "no-unused-vars": 1,
-    "no-use-before-define": 2,
-    "no-useless-call": 2,
-    "no-useless-computed-key": 2,
-    "no-useless-constructor": 2,
-    "no-useless-rename": 2,
-    "no-var": 2,
-    "no-whitespace-before-property": 2,
-    "no-with": 2,
-    "object-curly-spacing": [2, "always"],
-    "object-shorthand": 2,
-    "one-var-declaration-per-line": 2,
-    "operator-assignment": 2,
-    "prefer-arrow-callback": 2,
-    "prefer-const": 2,
-    "prefer-numeric-literals": 2,
-    "prefer-spread": 2,
-    "prefer-template": 2,
-    "quotes": [2, "double"],
-    "radix": 2,
-    "require-jsdoc": [1, {
-      "require": {
-        "FunctionDeclaration": true,
-        "MethodDefinition": true,
-        "ClassDeclaration": false
+    "array-bracket-spacing": "warn",
+    "arrow-parens": [
+      "warn",
+      "as-needed"
+    ],
+    "block-spacing": "warn",
+    "brace-style": [
+      "warn",
+      "1tbs",
+      {
+        "allowSingleLine": true
       }
-    }],
-    "rest-spread-spacing": 2,
-    "semi": [2, "never"],
-    "semi-spacing": 2,
-    "space-before-function-paren": [2, "never"],
-    "space-in-parens": 2,
-    "space-infix-ops": 2,
-    "space-unary-ops": 2,
-    "spaced-comment": [2, "always", {
-      "line": {
-        "markers": ["/"],
-        "exceptions": ["-", "+"]
-      },
-      "block": {
-        "markers": ["!"],
-        "exceptions": ["*"],
-        "balanced": true
+    ],
+    "comma-dangle": [
+      "error",
+      "never"
+    ],
+    "comma-spacing": "warn",
+    "comma-style": "error",
+    "computed-property-spacing": "warn",
+    "curly": "off",
+    "eqeqeq": [
+      "error",
+      "smart"
+    ],
+    "func-call-spacing": "warn",
+    "keyword-spacing": "warn",
+    "lines-around-comment": [
+      "error",
+      {
+        "allowBlockStart": true,
+        "allowBlockEnd": true,
+        "beforeBlockComment": true,
+        "ignorePattern": "@ts-ignore"
       }
-    }],
-    "strict": 2,
-    "template-curly-spacing": 2,
-    "unicode-bom": 2,
-    "valid-jsdoc": [1, {
-      "prefer": {
-        "arg": "param",
-        "argument": "param",
-        "class": "constructor",
-        "returns": "return",
-        "virtual": "abstract"
+    ],
+    "lines-between-class-members": "warn",
+    "max-classes-per-file": "error",
+    "new-parens": "error",
+    "no-caller": "error",
+    "no-case-declarations": "off",
+    "no-console": "error",
+    "no-duplicate-imports": "error",
+    "no-eval": "error",
+    "no-extra-bind": "error",
+    "no-multiple-empty-lines": [
+      "error",
+      {
+        "max": 1
+      }
+    ],
+    "no-new-func": "error",
+    "no-new-wrappers": "error",
+    "no-restricted-globals": [
+      "error",
+      {
+        "name": "fdescribe",
+        "message": "Did you mean 'describe'?"
       },
-      "requireParamDescription": true,
-      "requireReturn": false,
-      "requireReturnDescription": true
-    }],
-    "yield-star-spacing": 2
-  },
-  "root": true
+      {
+        "name": "xdescribe",
+        "message": "Did you mean 'describe'?"
+      },
+      {
+        "name": "fit",
+        "message": "Did you mean 'it'?"
+      },
+      {
+        "name": "xit",
+        "message": "Did you mean 'xit'?"
+      }
+    ],
+    "no-return-await": "error",
+    "no-sequences": "error",
+    "no-shadow": "off",
+    "no-tabs": "error",
+    "no-template-curly-in-string": "error",
+    "no-throw-literal": "off",
+    "no-trailing-spaces": "warn",
+    "no-undef-init": "error",
+    "no-underscore-dangle": "error",
+    "no-var": "error",
+    "no-whitespace-before-property": "warn",
+    "object-shorthand": "error",
+    "one-var": [
+      "error",
+      "never"
+    ],
+    "prefer-exponentiation-operator": "error",
+    "prefer-object-spread": "error",
+    "prefer-template": "error",
+    "quote-props": [
+      "error",
+      "consistent-as-needed"
+    ],
+    "quotes": [
+      "error",
+      "double",
+      {
+        "avoidEscape": true
+      }
+    ],
+    "radix": "error",
+    "semi": "off",
+    "sort-imports": [
+      "error",
+      {
+        "ignoreDeclarationSort": true
+      }
+    ],
+    "space-before-blocks": "warn",
+    "space-before-function-paren": [
+      "warn",
+      {
+        "anonymous": "always",
+        "named": "never",
+        "asyncArrow": "always"
+      }
+    ],
+    "space-in-parens": "warn",
+    "space-infix-ops": "warn",
+    "space-unary-ops": "warn",
+    "spaced-comment": "warn",
+    "switch-colon-spacing": "warn",
+    "template-tag-spacing": "warn",
+
+    /* Plugin: @typescript-eslint */
+    "@typescript-eslint/array-type": "off",
+    "@typescript-eslint/await-thenable": "error",
+    "@typescript-eslint/ban-ts-comment": "off",
+    "@typescript-eslint/ban-types": "off",
+    "@typescript-eslint/consistent-type-assertions": "error",
+    "@typescript-eslint/dot-notation": "error",
+    "@typescript-eslint/explicit-member-accessibility": "error",
+    "@typescript-eslint/indent": [
+      "warn",
+      2,
+      {
+        "FunctionDeclaration": {
+          "parameters": 1,
+          "body": 1
+        },
+        "FunctionExpression": {
+          "parameters": 1,
+          "body": 1
+        },
+        "MemberExpression": "off",
+        "ObjectExpression": 1,
+        "SwitchCase": 1,
+        "ignoreComments": true,
+        "ignoredNodes": [
+          "ArrowFunctionExpression > *",
+          "CallExpression > ObjectExpression",
+          "ConditionalExpression > ConditionalExpression",
+          "TSTypeReference > *"
+        ],
+        "offsetTernaryExpressions": true
+      }
+    ],
+    "@typescript-eslint/member-delimiter-style": [
+      "error",
+      {
+        "multiline": {
+          "delimiter": "none"
+        },
+        "singleline": {
+          "delimiter": "comma",
+          "requireLast": false
+        }
+      }
+    ],
+    "@typescript-eslint/naming-convention": [
+      "error",
+      {
+        "selector": "enumMember",
+        "format": [
+          "UPPER_CASE"
+        ]
+      }
+    ],
+    "@typescript-eslint/no-empty-interface": "off",
+    "@typescript-eslint/no-extraneous-class": "error",
+    "@typescript-eslint/no-misused-promises": "off",
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "@typescript-eslint/no-parameter-properties": "off",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-shadow": [
+      "error",
+      {
+        "hoist": "never"
+      }
+    ],
+    "@typescript-eslint/no-throw-literal": "error",
+    "@typescript-eslint/no-unnecessary-type-assertion": "error",
+    "@typescript-eslint/no-unused-expressions": "error",
+    "@typescript-eslint/no-unused-vars": "off",
+    "@typescript-eslint/no-var-requires": "off",
+    "@typescript-eslint/prefer-for-of": "off",
+    "@typescript-eslint/prefer-function-type": "error",
+    "@typescript-eslint/semi": [
+      "error",
+      "never"
+    ],
+    "@typescript-eslint/triple-slash-reference": "off",
+    "@typescript-eslint/type-annotation-spacing": "error",
+    "@typescript-eslint/unbound-method": "error",
+    "@typescript-eslint/unified-signatures": "error",
+    /* Plugin: eslint-plugin-eslint-comments */
+    "eslint-comments/no-unused-disable": "error",
+    "eslint-comments/no-unused-enable": "error",
+    "eslint-comments/no-use": [
+      "warn",
+      {
+        "allow": [
+          "eslint-disable-line",
+          "eslint-disable-next-line"
+        ]
+      }
+    ],
+
+    /* Plugin: eslint-plugin-import */
+    "import/first": "error",
+    "import/newline-after-import": "error",
+    "import/no-default-export": "error",
+    "import/no-duplicates": "error",
+    "import/no-mutable-exports": "error",
+    "import/no-self-import": "error",
+    "import/order": [
+      "error",
+      {
+        "alphabetize": {
+          "order": "asc"
+        },
+        "newlines-between": "always",
+        "groups": [
+          [
+            "builtin",
+            "external"
+          ],
+          [
+            "internal"
+          ],
+          [
+            "index"
+          ],
+          [
+            "parent"
+          ],
+          [
+            "sibling"
+          ]
+        ],
+        "pathGroups": [
+          {
+            "pattern": "~/**",
+            "group": "index",
+            "position": "before"
+          },
+          {
+            "pattern": "_/**",
+            "group": "index",
+            "position": "after"
+          }
+        ],
+        "pathGroupsExcludedImportTypes": [
+          "builtin"
+        ]
+      }
+    ],
+
+    /* Plugin: eslint-plugin-jsdoc */
+    "jsdoc/check-alignment": "warn",
+    "jsdoc/check-param-names": [
+      "warn",
+      {
+        "checkDestructured": false
+      }
+    ],
+    "jsdoc/check-syntax": "warn",
+    "jsdoc/check-tag-names": [
+      "warn",
+      {
+        "definedTags": [
+          "internal"
+        ]
+      }
+    ],
+    "jsdoc/empty-tags": "warn",
+    "jsdoc/no-bad-blocks": "warn",
+    "jsdoc/no-defaults": "warn",
+    "jsdoc/no-types": "warn",
+    "jsdoc/require-hyphen-before-param-description": "warn",
+    "jsdoc/require-jsdoc": "warn",
+    "jsdoc/require-param-description": "warn",
+    "jsdoc/require-param-name": "warn",
+    "jsdoc/require-param": [
+      "warn",
+      {
+        "checkDestructured": false,
+        "checkDestructuredRoots": true
+      }
+    ],
+    "jsdoc/require-returns-check": "warn",
+    "jsdoc/require-returns-description": "warn",
+    "jsdoc/require-returns": [
+      "warn",
+      {
+        "checkGetters": false,
+        "forceReturnsWithAsync": true
+      }
+    ],
+
+    /* Plugin: eslint-plugin-no-null */
+    "no-null/no-null": "error"
+  }
 }

.gitattributes

@@ -0,0 +1,2 @@
+# Enforce Unix newlines
+* text=auto eol=lf

.githooks/post-merge/npm-update.sh

@@ -1,30 +0,0 @@
-#!/bin/bash
-
-# Copyright (c) 2016-2017 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.
-
-# Check, if all changes are added to the index
-CHANGED="$(git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD)"
-
-# Perform install and prune of NPM dependencies if package.json changed
-if $(echo "$CHANGED" | grep --quiet package.json); then
-  echo "Hook[post-merge]: Updating dependencies..."
-  npm install && npm prune
-fi

.githooks/pre-commit/branch.sh

@@ -1,34 +0,0 @@
-#!/bin/bash
-
-# Copyright (c) 2016-2017 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.
-
-# Determine current branch
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-echo "Hook[pre-commit]: Checking branch..."
-
-# If we're on master, abort commit
-if [[ "$BRANCH" == "master" ]]; then
-	echo "Commits on master are only allowed via Pull Requests. Aborting."
-	exit 1
-fi
-
-# We're good
-exit 0

.githooks/pre-commit/lint.sh

@@ -1,51 +0,0 @@
-#!/bin/bash
-
-# Copyright (c) 2016-2017 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.
-
-# Patch file to store unindexed changes
-PATCH_FILE=".working-tree.patch"
-
-# Revert changes that have been registered in the patch file
-function cleanup {
-  EXIT_CODE=$?
-  if [ -f "$PATCH_FILE" ]; then
-    git apply "$PATCH_FILE" 2> /dev/null
-    rm "$PATCH_FILE"
-  fi
-	exit $EXIT_CODE
-}
-
-# Register signal handlers
-trap cleanup EXIT SIGINT SIGHUP
-
-# Cancel any changes to the working tree that are not going to be committed
-git diff > "$PATCH_FILE"
-git checkout -- .
-
-# Filter relevant files for linting
-FILES=$(git diff --cached --name-only --diff-filter=ACMR | \
-  grep "\.\(js\|jsx\|scss\)$")
-
-# Run the check and print indicator
-if [ "$FILES" ]; then
-  echo "Hook[pre-commit]: Running linter..."
-  npm run lint --silent || exit 1
-fi

.github/FUNDING.yml

@@ -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.
+
+github: squidfunk

.github/ISSUE_TEMPLATE.md

@@ -1,28 +0,0 @@
-## Description
-
-[Description of the bug]
-
-### Expected behavior
-
-[What you expected to happen]
-
-### Actual behavior
-
-[What is actually happening]
-
-### Steps to reproduce the bug
-
-1. [First step]
-2. [Second step]
-3. [and so on...]
-
-### Package versions
-
-- Python: `python --version`
-- MkDocs: `mkdocs --version`
-- Material: `pip show mkdocs-material | grep -E ^Version`
-
-### System information
-
-- OS: [The operating system you're running]
-- Browser: [The browser used, if relevant]

.github/assets/logo.svg

@@ -0,0 +1,236 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 320">
+  <foreignObject width="100%" height="100%">
+    <div xmlns="http://www.w3.org/1999/xhtml">
+      <style>
+        @keyframes backdrop {
+          0% {
+            transform: scale(0.9) rotateZ(45deg);
+            opacity: 0.1;
+          }
+
+          10% {
+            opacity: 1;
+          }
+
+          15% {
+            transform: scale(1.1) rotateZ(35deg);
+          }
+
+          50% {
+            transform: scale(1) rotateZ(0deg);
+          }
+
+          75% {
+            transform: scale(1.1) rotateZ(-35deg);
+            opacity: 1;
+          }
+
+          100% {
+            transform: scale(0.9) rotateZ(-45deg);
+            opacity: 0.1;
+          }
+        }
+
+        .container {
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          width: 320px;
+          height: 320px;
+          font-family:
+            system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
+            sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
+          letter-spacing: -1px;
+          border-radius: 2px;
+        }
+
+        .logo {
+          position: relative;
+          width: 40%;
+        }
+
+        .logo svg {
+          position: relative;
+          display: block;
+          margin: 20%;
+          fill: #FFFFFF;
+        }
+
+        .backdrop {
+          position: absolute;
+          width: 100%;
+          height: 100%;
+          background-image: linear-gradient(#22272e, #526cfe);
+          border-radius: 100%;
+          animation: backdrop infinite both 10s 1s cubic-bezier(0.7, 0, 0.3, 1);
+        }
+
+        h1 {
+          margin: 24px 0 4px;
+          color: #526cfe;
+          font-weight: bold;
+          font-size: 24px;
+        }
+
+        h2 {
+          margin: 4px 0;
+          color: #5E5E5E;
+          font-size: 14px;
+        }
+
+      </style>
+      <div class="container">
+        <div class="logo">
+          <div class="backdrop"></div>
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 89 89">
+            <polygon id="p1">
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="1s;p1o.end+1s" id="p1i"
+                keyTimes="0;1" keySplines="0.16 1 0.3 1"
+                values="
+                  3.136 17.387, 3.136 60.319,  3.136 60.319, 3.136 60.319;
+                  3.136 17.387, 3.136 60.319, 46.068 81.786, 3.136 17.387
+                "
+              />
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="p1i.end+5s" id="p1o"
+                keyTimes="0;1" keySplines="0.7 0 0.84 0"
+                values="
+                  3.136 17.387, 3.136 60.319, 46.068 81.786, 3.136 17.387;
+                  3.136 17.387, 3.136 60.319,  3.136 60.319, 3.136 60.319
+                "
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="5s" begin="p1i.end"
+                from="1" to="0.5"
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="0.1s" begin="p1o.end"
+                from="0.5" to="1"
+              />
+            </polygon>
+            <polygon id="p2" style="fill-opacity: 0.5;">
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="1s;p2o.end+1s" id="p2i"
+                keyTimes="0;1" keySplines="0.16 1 0.3 1"
+                values="
+                  21.910 50.932, 21.910 50.932,  3.136 60.319, 3.136 60.319;
+                  21.910  8.000, 64.843 72.398, 46.068 81.786, 3.136 17.387
+                "
+              />
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="p2i.end+5s" id="p2o"
+                keyTimes="0;1" keySplines="0.7 0 0.84 0"
+                values="
+                  21.910  8.000, 64.843 72.398, 46.068 81.786, 3.136 17.387;
+                  21.910 50.932, 21.910 50.932,  3.136 60.319, 3.136 60.319
+                "
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="5s" begin="p1i.end"
+                from="0.5" to="1"
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="0.1s" begin="p2o.end"
+                from="1" to="0.5"
+              />
+            </polygon>
+            <clipPath id="clip">
+              <polygon id="p3">
+                <animate
+                  attributeName="points" calcMode="spline" fill="freeze"
+                  dur="2s" begin="1s;p3o.end+1s" id="p3i"
+                  keyTimes="0;1" keySplines="0.16 1 0.3 1"
+                  values="
+                    21.910 50.932, 21.910 50.932, 89 89, 89 0;
+                    21.910  8.000, 64.843 72.398, 89 89, 89 0
+                  "
+                />
+                <animate
+                  attributeName="points" calcMode="spline" fill="freeze"
+                  dur="2s" begin="p3i.end+5s" id="p3o"
+                  keyTimes="0;1" keySplines="0.7 0 0.84 0"
+                  values="
+                    21.910  8.000, 64.843 72.398, 89 89, 89 0;
+                    21.910 50.932, 21.910 50.932, 89 89, 89 0
+                  "
+                />
+              </polygon>
+            </clipPath>
+            <polygon id="p4" clip-path="url(#clip)">
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="1.25s;p4o.end+1s" id="p4i"
+                keyTimes="0;1" keySplines="0.16 1 0.3 1"
+                values="
+                  67.535 71.052, 67.535 71.052, 62.151 68.361, 67.535 71.052;
+                  67.535 17.387, 21.509  48.04, 62.151 68.361, 67.535 71.052
+                "
+              />
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="p4i.end+5s" id="p4o"
+                keyTimes="0;1" keySplines="0.7 0 0.84 0"
+                values="
+                  67.535 17.387, 21.509  48.04, 62.151 68.361, 67.535 71.052;
+                  67.535 71.052, 67.535 71.052, 62.151 68.361, 67.535 71.052
+                "
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="5s" begin="p1i.end"
+                from="1" to="0.5"
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="0.1s" begin="p4o.end"
+                from="0.5" to="1"
+              />
+            </polygon>
+            <polygon id="p5" clip-path="url(#clip)" style="fill-opacity: 0.25;">
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="1.25s;p5o.end+1s" id="p5i"
+                keyTimes="0;1" keySplines="0.16 1 0.3 1"
+                values="
+                  67.535 71.053, 86.309 61.665, 86.309 61.665, 67.535 71.053;
+                  67.535 71.053, 86.309 61.665, 86.309  8.000, 67.535 17.387
+                "
+              />
+              <animate
+                attributeName="points" calcMode="spline" fill="freeze"
+                dur="2s" begin="p5i.end+5s" id="p5o"
+                keyTimes="0;1" keySplines="0.7 0 0.84 0"
+                values="
+                  67.535 71.053, 86.309 61.665, 86.309  8.000, 67.535 17.387;
+                  67.535 71.053, 86.309 61.665, 86.309 61.665, 67.535 71.053
+                "
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="5s" begin="p1i.end"
+                from="0.25" to="1"
+              />
+              <animate
+                attributeName="fill-opacity" fill="freeze"
+                dur="0.1s" begin="p5o.end"
+                from="1" to="0.25"
+              />
+            </polygon>
+          </svg>
+        </div>
+        <h1>Material for MkDocs</h1>
+        <h2>Documentation that simply works</h2>
+      </div>
+    </div>
+  </foreignObject>
+</svg>

.github/workflows/build.yml

@@ -0,0 +1,145 @@
+# 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.
+
+name: build
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  release:
+    types:
+      - published
+
+env:
+  NODE_VERSION: 18.x
+  PYTHON_VERSION: 3.x
+
+permissions:
+  contents: read
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js runtime
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Set up Node.js dependency cache
+        uses: actions/cache@v3
+        id: cache
+        with:
+          key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          path: node_modules
+
+      - name: Set up Node.js dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm install
+
+      - name: Check project
+        run: npm run check
+
+      - name: Build project
+        run: |
+          npm run build
+          git diff --name-only
+
+  docker:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == true
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # - name: Set up QEMU
+      #   uses: docker/setup-qemu-action@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name == 'release'
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Generate Docker tags and labels
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: ghcr.io/${{ github.event.repository.full_name }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=ref,event=pr
+          flavor: |
+            latest=${{ github.event.release.prerelease == false }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Check Docker image
+        working-directory: /tmp
+        env:
+          REPO_FULL_NAME: '${{ github.event.repository.full_name }}'
+        run: |
+          docker run --rm -i --user $(id -u):$(id -g) -e GH_TOKEN=${GH_TOKEN} -v ${PWD}:/docs ghcr.io/${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} new .
+          docker run --rm -i --user $(id -u):$(id -g) -e GH_TOKEN=${GH_TOKEN} -v ${PWD}:/docs ghcr.io/${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} build
+
+      - name: Set platforms
+        if: github.event_name == 'release'
+        run: |
+          echo "PLATFORMS=linux/amd64" >> $GITHUB_ENV
+        # echo "PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7" >> $GITHUB_ENV
+
+      - name: Publish Docker image
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          platforms: ${{ env.PLATFORMS }}
+          push: ${{ github.event_name == 'release' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      # - name: Check manifest
+      #   if: github.event_name == 'release'
+      #   run: |
+      #     docker buildx imagetools inspect ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+
+      # - name: Inspect image
+      #   if: github.event_name == 'release'
+      #   run: |
+      #     docker pull ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+      #     docker image inspect ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}

.gitignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+# 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
@@ -18,19 +18,53 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+# -----------------------------------------------------------------------------
+# Node, TypeScript, Python
+# -----------------------------------------------------------------------------
+
+# Dependencies
+node_modules
+__pycache__
+venv
+.venv
+
+# Build files
+build
+site
+
+# Distribution files
+dist
+mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.cache
+.eslintcache
+__pycache__
+
+# Examples
+example
+example.zip
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Never ignore .gitkeep files
+!**/.gitkeep
+
+# Husky hooks
+.husky/.gitignore
+.husky/_
+
 # macOS internals
 .DS_Store
 
-# NPM-related
-/node_modules
-/npm-debug.log
+# Temporary files
+TODO
+tmp
 
-# Build files
-/build
-/manifest.json
-/MANIFEST
-/site
-
-# Distribution files
-/dist
-/mkdocs_material.egg-info
+# IDEs
+.idea

.stylelintignore

@@ -0,0 +1,28 @@
+# 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.
+
+# Distribution files
+docs
+material
+src/**/*.html
+
+# Prevent stylelint from constantly complaining
+*.css
+*.ts

.stylelintrc

@@ -1,191 +1,164 @@
 {
-  "extends": "stylelint-config-standard",
+  "extends": [
+    "stylelint-config-recess-order",
+    "stylelint-config-recommended",
+    "stylelint-config-standard-scss"
+  ],
   "plugins": [
-    "stylelint-order",
     "stylelint-scss"
   ],
   "rules": {
-    "at-rule-empty-line-before": null,
-    "at-rule-no-vendor-prefix": true,
-    "block-opening-brace-space-before": null,
-    "block-closing-brace-newline-after": ["always", {
-      "ignoreAtRules": [
-        "if",
-        "else",
-        "elseif"
-      ]
-    }],
-    "color-hex-case": "upper",
+    "alpha-value-notation": "number",
+    "annotation-no-unknown": null,
+    "at-rule-empty-line-before": [
+      "always",
+      {
+        "except": [
+          "blockless-after-same-name-blockless",
+          "first-nested"
+        ],
+        "ignore": [
+          "after-comment"
+        ],
+        "ignoreAtRules": [
+          "if",
+          "each",
+          "else",
+          "elseif",
+          "for",
+          "import",
+          "return"
+        ]
+      }
+    ],
+    "at-rule-no-unknown": null,
+    "block-closing-brace-newline-after": [
+      "always",
+      {
+        "ignoreAtRules": [
+          "if",
+          "else",
+          "elseif"
+        ]
+      }
+    ],
+    "color-function-notation": null,
     "color-hex-length": "long",
     "color-named": "never",
-    "comment-empty-line-before": ["always", {
-      "ignore": ["stylelint-commands"]
-    }],
+    "comment-empty-line-before": [
+      "always",
+      {
+        "ignore": [
+          "stylelint-commands"
+        ]
+      }
+    ],
+    "custom-property-empty-line-before": null,
+    "custom-property-pattern": null,
+    "declaration-colon-space-after": null,
+    "declaration-no-important": true,
+    "declaration-block-single-line-max-declarations": 0,
+    "function-calc-no-unspaced-operator": null,
+    "function-no-unknown": null,
+    "function-url-no-scheme-relative": true,
+    "function-url-quotes": "always",
     "font-family-name-quotes": "always-where-recommended",
     "font-weight-notation": "numeric",
-    "function-url-quotes": "always",
+    "hue-degree-notation": "number",
+    "length-zero-no-unit": [
+      true,
+      {
+        "ignore": ["custom-properties"]
+      }
+    ],
+    "linebreaks": "unix",
+    "media-feature-name-no-unknown": null,
+    "media-feature-range-notation": null,
+    "no-descending-specificity": null,
+    "no-empty-first-line": true,
     "no-unknown-animations": true,
-    "order/declaration-block-order": [
-      "custom-properties",
-      "declarations"
+    "property-no-unknown": null,
+    "property-no-vendor-prefix": [
+      true,
+      {
+        "ignoreProperties": [
+          "line-clamp",
+          "box-orient"
+        ]
+      }
     ],
-    "order/declaration-block-properties-specified-order": [
-      "display",
-      "position",
-      "top",
-      "right",
-      "bottom",
-      "left",
-
-      "flex",
-      "flex-basis",
-      "flex-direction",
-      "flex-flow",
-      "flex-grow",
-      "flex-shrink",
-      "flex-wrap",
-      "align-content",
-      "align-items",
-      "align-self",
-      "justify-content",
-      "order",
-
-      "width",
-      "min-width",
-      "max-width",
-
-      "height",
-      "min-height",
-      "max-height",
-
-      "margin",
-      "margin-top",
-      "margin-right",
-      "margin-bottom",
-      "margin-left",
-
-      "padding",
-      "padding-top",
-      "padding-right",
-      "padding-bottom",
-      "padding-left",
-
-      "float",
-      "clear",
-      "clip",
-
-      "columns",
-      "column-gap",
-      "column-fill",
-      "column-rule",
-      "column-span",
-      "column-count",
-      "column-width",
-
-      "transform",
-      "transform-box",
-      "transform-origin",
-      "transform-style",
-
-      "transition",
-      "transition-delay",
-      "transition-duration",
-      "transition-property",
-      "transition-timing-function",
-
-      "border",
-      "border-top",
-      "border-right",
-      "border-bottom",
-      "border-left",
-      "border-width",
-      "border-top-width",
-      "border-right-width",
-      "border-bottom-width",
-      "border-left-width",
-
-      "border-style",
-      "border-top-style",
-      "border-right-style",
-      "border-bottom-style",
-      "border-left-style",
-
-      "border-radius",
-      "border-top-left-radius",
-      "border-top-right-radius",
-      "border-bottom-left-radius",
-      "border-bottom-right-radius",
-
-      "border-color",
-      "border-top-color",
-      "border-right-color",
-      "border-bottom-color",
-      "border-left-color",
-
-      "outline",
-      "outline-color",
-      "outline-offset",
-      "outline-style",
-      "outline-width",
-
-      "background",
-      "background-attachment",
-      "background-clip",
-      "background-color",
-      "background-image",
-      "background-repeat",
-      "background-position",
-      "background-size",
-
-      "color",
-
-      "font",
-      "font-family",
-      "font-size",
-      "font-smoothing",
-      "font-style",
-      "font-variant",
-      "font-weight",
-
-      "letter-spacing",
-      "line-height",
-      "list-style",
-
-      "text-align",
-      "text-decoration",
-      "text-indent",
-      "text-overflow",
-      "text-rendering",
-      "text-shadow",
-      "text-transform",
-      "text-wrap",
-
-      "white-space",
-      "word-spacing",
-
-      "border-collapse",
-      "border-spacing",
-      "box-shadow",
-      "caption-side",
-      "content",
-      "cursor",
-      "empty-cells",
-      "opacity",
-      "overflow",
-      "quotes",
-      "speak",
-      "table-layout",
-      "vertical-align",
-      "visibility",
-      "z-index"
-    ],
-    "property-no-vendor-prefix": true,
-    "root-no-standard-properties": true,
-    "selector-class-pattern": "^[a-z0-9]+(-[a-z0-9]+)*(__[a-z]+)?(--[a-z]+)?$",
+    "selector-class-pattern": null,
+    "selector-combinator-space-before": null,
     "selector-descendant-combinator-no-non-space": null,
+    "selector-id-pattern": null,
+    "selector-max-empty-lines": 0,
+    "selector-max-id": 0,
+    "selector-no-qualifying-type": null,
+    "selector-pseudo-class-no-unknown": null,
+    "selector-pseudo-element-no-unknown": null,
     "string-quotes": "double",
-    "unit-whitelist": ["rem", "em", "deg", "s", "%", "mm", "vh"],
-    "value-keyword-case": "lower",
-    "value-no-vendor-prefix": true
+    "unicode-bom": "never",
+    "unit-allowed-list": [
+      "%",
+      "ch",
+      "dppx",
+      "deg",
+      "em",
+      "fr",
+      "mm",
+      "ms",
+      "px",
+      "vh",
+      "vw"
+    ],
+    "value-keyword-case": [
+      "lower",
+      {
+        "ignoreProperties": [
+          "/^--/"
+        ]
+      }
+    ],
+    "value-list-comma-newline-after": null,
+    "value-no-vendor-prefix": [
+      true,
+      {
+        "ignoreValues": [
+          "box"
+        ]
+      }
+    ],
+    "scss/at-each-key-value-single-line": true,
+    "scss/at-else-closing-brace-newline-after": "always-last-in-chain",
+    "scss/at-function-parentheses-space-before": "never",
+    "scss/at-function-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+    "scss/at-if-closing-brace-newline-after": "always-last-in-chain",
+    "scss/at-if-no-null": true,
+    "scss/at-import-no-partial-leading-underscore": true,
+    "scss/at-import-partial-extension": "never",
+    "scss/at-mixin-argumentless-call-parentheses": "always",
+    "scss/at-mixin-parentheses-space-before": "never",
+    "scss/at-mixin-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+    "scss/at-rule-conditional-no-parentheses": true,
+    "scss/comment-no-empty": null,
+    "scss/comment-no-loud": true,
+    "scss/declaration-nested-properties": "never",
+    "scss/dimension-no-non-numeric-values": true,
+    "scss/dollar-variable-colon-newline-after": "always-multi-line",
+    "scss/dollar-variable-colon-space-after": "always-single-line",
+    "scss/dollar-variable-colon-space-before": "never",
+    "scss/dollar-variable-first-in-block": null,
+    "scss/dollar-variable-no-missing-interpolation": true,
+    "scss/dollar-variable-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+    "scss/double-slash-comment-empty-line-before": null,
+    "scss/double-slash-comment-whitespace-inside": "always",
+    "scss/at-extend-no-missing-placeholder": null,
+    "scss/no-duplicate-mixins": true,
+    "scss/no-global-function-names": null,
+    "scss/operator-no-newline-after": null,
+    "scss/operator-no-unspaced": true,
+    "scss/partial-no-import": true,
+    "scss/percent-placeholder-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+    "scss/selector-no-redundant-nesting-selector": true
   }
 }

.travis.yml

@@ -1,41 +0,0 @@
-# Copyright (c) 2016-2017 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.
-
-language: node_js
-sudo: false
-
-# Node.js versions
-node_js:
-  - 4
-  - 5
-  - 6
-
-# Cache dependencies
-cache:
-  pip: true
-  directories:
-    - node_modules
-
-# Install dependencies
-before_script:
-  - pip install --user -r requirements.txt
-
-# Perform build and tests
-script: npm run build

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Application",
+      "type": "chrome",
+      "request": "launch",
+      "runtimeArgs": [
+        "--disable-features=Translate",
+        "--incognito"
+      ],
+      "url": "http://localhost:8000/mkdocs-material/",
+      "webRoot": "${workspaceFolder}",
+      "smartStep": true
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "git.ignoreLimitWarning": true,
+  "search.exclude": {
+    "**/material": true,
+    "**/node_modules": true,
+    "**/package-lock.json": true
+  },
+  "search.followSymlinks": false,
+  "stylelint.validate": ["css", "scss"],
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "yaml.schemas": {
+    "docs/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [
+    "!ENV scalar",
+    "!ENV sequence",
+    "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.slugs.uslugify",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Build",
+      "type": "shell",
+      "command": "npm run build",
+      "group": "build",
+      "presentation": {
+        "reveal": "silent"
+      },
+      "problemMatcher": [
+        "$tsc"
+      ]
+    },
+    {
+      "label": "Start and watch for changes",
+      "type": "shell",
+      "command": "npm start",
+      "isBackground": true,
+      "group": "build",
+      "presentation": {
+        "reveal": "silent"
+      }
+    }
+  ]
+}

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience, 
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject 
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of 
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed 
+representative at an online or offline event. Representation of a project may be 
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at
+https://gitter.im/squidfunk/mkdocs-material. The project team will review and 
+investigate all complaints, and will respond in a way that it deems appropriate
+to the circumstances. The project team is obligated to maintain confidentiality
+with regard to the reporter of an incident. Further details of specific
+enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTING.md

@@ -1,60 +1,90 @@
 # Contributing
 
-Interested in contributing to the Material theme? Want to report a bug? Before
-you do, please read the following guidelines.
+Interested in contributing to the Material for MkDocs? Have a question? Want to 
+report a bug? Before you do, please read the following guidelines.
 
 ## Submission context
 
 ### Got a question or problem?
 
 For quick questions there's no need to open an issue as you can reach us on
-[gitter.im][1].
+[gitter.im].
 
-  [1]: https://gitter.im/mkdocs-material/general
+  [gitter.im]: https://gitter.im/squidfunk/mkdocs-material
 
 ### Found a bug?
 
 If you found a bug in the source code, you can help us by submitting an issue
-to the [issue tracker][2] in our GitHub repository. Even better, you can submit
+to the [issue tracker] in our GitHub repository. Even better, you can submit
 a Pull Request with a fix. However, before doing so, please read the
-[submission guidelines][3].
+[submission guidelines].
 
-  [2]: https://github.com/squidfunk/mkdocs-material/issues
-  [3]: #submission-guidelines
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+  [submission guidelines]: #submission-guidelines
 
 ### Missing a feature?
 
 You can request a new feature by submitting an issue to our GitHub Repository.
 If you would like to implement a new feature, please submit an issue with a
-proposal for your work first, to be sure that it is of use for everyone, as
-the Material theme is highly opinionated. Please consider what kind of change
+proposal for your work first to be sure that it is of use to everyone, as
+Material for MkDocs is highly opinionated. Please consider what kind of change
 it is:
 
-* For a **Major Feature**, first open an issue and outline your proposal so
+* For a **major feature**, first open an issue and outline your proposal so
   that it can be discussed. This will also allow us to better coordinate our
   efforts, prevent duplication of work, and help you to craft the change so
   that it is successfully accepted into the project.
 
-* **Small Features** and bugs can be crafted and directly submitted as a Pull
+* **Small features and bugs** can be crafted and directly submitted as a Pull
   Request. However, there is no guarantee that your feature will make it into
-  the master, as it's always a matter of opinion whether if benefits the
-  overall functionality of the theme.
+  the `master`, as it's always a matter of opinion whether if benefits the
+  overall functionality of the project.
+
+### Missing translations?
+
+Material for MkDocs supports 60+ languages with the help of community
+contributions. When new features are added, sometimes, new translations are
+necessary as well. It's impossible for the maintainers of the project to update
+all translations (we just don't speak 60+ languages), so we have to rely on
+our contributors to update translations incrementally. This process is pretty
+simple, so if you find a translation missing in your language, follow these
+guidelines:
+
+1.  Fork the repository.
+
+2.  Open up the [translation file for your language] as well as the
+    [English translations], as they are always up-to-date. Compare them
+    side-by-side and add the missing translations. __Important__: only add the
+    translations that are different from the defaults, e.g. if your language
+    is left-to-right, don't add the `direction` translation, as English is
+    left-to-right as well. The following translations are for technical
+    purposes and should not be updated, so if they're missing from your
+    language, it's for good reason:
+
+    - `search.config.lang`
+    - `search.config.pipeline`
+    - `search.config.separator`
+
+3.  Create a PR (see below) with your changes.
+
+  [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+  [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
 
 ## Submission guidelines
 
 ### Submitting an issue
 
 Before you submit an issue, please search the issue tracker, maybe an issue for
-your problem already exists and the discussion might inform you of workarounds
+your problem already exists, and the discussion might inform you of workarounds
 readily available.
 
-We want to fix all the issues as soon as possible, but before fixing a bug we
-need to reproduce and confirm it. In order to reproduce bugs we will
+We want to fix all the issues as soon as possible, but before fixing a bug, we
+need to reproduce and confirm it. In order to reproduce bugs, we will
 systematically ask you to provide a minimal reproduction scenario using the
 custom issue template. Please stick to the issue template.
 
-Unfortunately we are not able to investigate / fix bugs without a minimal
-reproduction scenario, so if we don't hear back from you we may close the issue.
+Unfortunately, we are not able to investigate / fix bugs without a minimal
+reproduction scenario, so if we don't hear back from you, we may close the issue.
 
 ### Submitting a Pull Request (PR)
 
@@ -62,20 +92,21 @@ Search GitHub for an open or closed PR that relates to your submission. You
 don't want to duplicate effort. If you do not find a related issue or PR,
 go ahead.
 
-1. **Development**: Fork the project, set up the [development environment][4],
-  make your changes in a separate git branch and add descriptive messages to
-  your commits.
+1.  **Development**: Fork the project, set up the [development environment],
+    make your changes in a separate git branch and add descriptive messages to
+    your commits.
 
-2. **Build**: Before submitting a pull requests, build the theme. This is a
-  mandatory requirement for your PR to get accepted, as the theme should at
-  all times be installable through GitHub.
+2.  **Build**: Before submitting a pull request, [build the theme]. This is
+    a mandatory requirement for your PR to get accepted, as the theme should be 
+    installable through GitHub at all times.
 
-3. **Pull Request**: After building the theme, commit the compiled output, push
-  your branch to GitHub and send a PR to `mkdocs-material:master`. If we
-  suggest changes, make the required updates, rebase your branch and push the
-  changes to your GitHub repository, which will automatically update your PR.
+3.  **Pull Request**: After building the theme, commit the compiled output,
+    push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
+    suggest changes, make the required updates, rebase your branch and push the
+    changes to your GitHub repository, which will automatically update your PR.
 
 After your PR is merged, you can safely delete your branch and pull the changes
 from the main (upstream) repository.
 
-  [4]: http://localhost:8000/customization/#theme-development
+  [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
+  [build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme

Dockerfile

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+# 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
@@ -18,20 +18,90 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-FROM jfloff/alpine-python:2.7-slim
-MAINTAINER Martin Donath <martin.donath@squidfunk.com>
+FROM python:3.11-alpine3.18
+
+# Build-time flags
+ARG WITH_PLUGINS=true
+
+# Environment variables
+ENV PACKAGES=/usr/local/lib/python3.11/site-packages
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Set build directory
+WORKDIR /tmp
+
+# Copy files necessary for build
+COPY material material
+COPY package.json package.json
+COPY pyproject.toml pyproject.toml
+COPY README.md README.md
+COPY *requirements.txt ./
+
+# Perform build and cleanup artifacts and caches
+RUN \
+  apk upgrade --update-cache -a \
+&& \
+  apk add --no-cache \
+    cairo \
+    freetype-dev \
+    git \
+    git-fast-import \
+    jpeg-dev \
+    libxml2 \
+    libxslt \
+    openssh \
+    zlib-dev \
+&& \
+  apk add --no-cache --virtual .build \
+    gcc \
+    libffi-dev \
+    libxml2-dev \
+    libxslt-dev \
+    musl-dev \
+&& \
+  pip install --no-cache-dir --upgrade pip \
+&& \
+  pip install --no-cache-dir . \
+&& \
+  if [ "${WITH_PLUGINS}" = "true" ]; then \
+    pip install --no-cache-dir \
+      "mkdocs-git-committers-plugin-2==1.1.1" \
+      "mkdocs-git-revision-date-localized-plugin==1.2.0" \
+      "mkdocs-minify-plugin==0.5.0" \
+      "mkdocs-redirects==1.2.0" \
+      "mkdocs-rss-plugin==1.6.0" \
+      "pillow>=9.0" \
+      "cairosvg>=2.5"; \
+  fi \
+&& \
+  if [ -e user-requirements.txt ]; then \
+    pip install -U -r user-requirements.txt; \
+  fi \
+&& \
+  apk del .build \
+&& \
+  for theme in mkdocs readthedocs; do \
+    rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
+    ln -s \
+      ${PACKAGES}/material \
+      ${PACKAGES}/mkdocs/themes/$theme; \
+  done \
+&& \
+  rm -rf /tmp/* /root/.cache \
+&& \
+  find ${PACKAGES} \
+    -type f \
+    -path "*/__pycache__/*" \
+    -exec rm -f {} \;
+
+# Trust directory, required for git >= 2.35.2
+RUN git config --global --add safe.directory /docs &&\
+    git config --global --add safe.directory /site
 
 # Set working directory
 WORKDIR /docs
 
-# Install packages
-COPY requirements.txt .
-RUN \
-  pip install -r requirements.txt && \
-  pip install mkdocs-material && \
-  rm requirements.txt
-
-# Expose MkDocs default port
+# Expose MkDocs development server port
 EXPOSE 8000
 
 # Start development server by default

Gulpfile.babel.js

@@ -1,343 +0,0 @@
-/*
- * Copyright (c) 2016-2017 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.
- */
-
-import gulp from "gulp"
-import notifier from "node-notifier"
-import plumber from "gulp-plumber"
-import util from "gulp-util"
-import yargs from "yargs"
-
-/* ----------------------------------------------------------------------------
- * Configuration and arguments
- * ------------------------------------------------------------------------- */
-
-const config = {
-  assets: {
-    src: "src/assets",                 /* Source directory for assets */
-    build: "material/assets"           /* Target directory for assets */
-  },
-  lib: "lib",                          /* Libraries */
-  views: {
-    src: "src",                        /* Source directory for views */
-    build: "material"                  /* Target directory for views */
-  }
-}
-
-const args = yargs
-  .default("clean",      false)        /* Clean before build */
-  .default("karma",      true)         /* Karma watchdog */
-  .default("lint",       true)         /* Lint sources */
-  .default("mkdocs",     true)         /* MkDocs watchdog */
-  .default("optimize",   false)        /* Optimize sources */
-  .default("revision",   false)        /* Revision assets */
-  .default("sourcemaps", false)        /* Create sourcemaps */
-  .argv
-
-/* ----------------------------------------------------------------------------
- * Overrides and helpers
- * ------------------------------------------------------------------------- */
-
-/*
- * Override gulp.src() for nicer error handling.
- */
-const src = gulp.src
-gulp.src = (...glob) => {
-  return src.apply(gulp, glob)
-    .pipe(
-      plumber(function(error) {
-        util.log(util.colors.red(
-          `Error (${error.plugin}): ${error.message}`
-        ))
-
-        /* Extract file where error happened, if existent */
-        const file = error.relativePath
-          ? error.relativePath.split("/").pop()
-          : ""
-
-        /* Dispatch system-level notification */
-        notifier.notify({
-          title: `Error (${error.plugin}): ${file}`,
-          message: error.messageOriginal
-        })
-
-        // eslint-disable-next-line no-invalid-this
-        this.emit("end")
-
-        /* Throw error and abort, if not in watch mode */
-        if (args._[0] !== "watch")
-          throw error
-      }))
-}
-
-/*
- * Helper function to load a task
- */
-const load = task => {
-  return require(`./${config.lib}/tasks/${task}`)(gulp, config, args)
-}
-
-/* ----------------------------------------------------------------------------
- * Images
- * ------------------------------------------------------------------------- */
-
-/*
- * Copy favicon
- */
-gulp.task("assets:images:build:ico",
-  load("assets/images/build/ico"))
-
-/*
- * Copy and minify vector graphics
- */
-gulp.task("assets:images:build:svg",
-  load("assets/images/build/svg"))
-
-/*
- * Copy images
- */
-gulp.task("assets:images:build", args.clean ? [
-  "assets:images:clean"
-] : [], () => {
-  return gulp.start([
-    "assets:images:build:ico",
-    "assets:images:build:svg"
-  ])
-})
-
-/*
- * Clean images generated by build
- */
-gulp.task("assets:images:clean",
-  load("assets/images/clean"))
-
-/* ----------------------------------------------------------------------------
- * JavaScript
- * ------------------------------------------------------------------------- */
-
-/*
- * Build application logic
- */
-gulp.task("assets:javascripts:build:application",
-  load("assets/javascripts/build/application"))
-
-/*
- * Build custom modernizr
- */
-gulp.task("assets:javascripts:build:modernizr", [
-  "assets:stylesheets:build"
-], load("assets/javascripts/build/modernizr"))
-
-/*
- * Build application logic and modernizr
- */
-gulp.task("assets:javascripts:build", (args.clean ? [
-  "assets:javascripts:clean"
-] : []).concat(args.lint ? [
-  "assets:javascripts:lint"
-] : []), () => {
-  return gulp.start([
-    "assets:javascripts:build:application",
-    "assets:javascripts:build:modernizr"
-  ])
-})
-
-/*
- * Clean JavaScript generated by build
- */
-gulp.task("assets:javascripts:clean",
-  load("assets/javascripts/clean"))
-
-/*
- * Lint JavaScript
- */
-gulp.task("assets:javascripts:lint",
-  load("assets/javascripts/lint"))
-
-/* ----------------------------------------------------------------------------
- * Stylesheets
- * ------------------------------------------------------------------------- */
-
-/*
- * Build stylesheets from SASS source
- */
-gulp.task("assets:stylesheets:build", (args.clean ? [
-  "assets:stylesheets:clean"
-] : []).concat(args.lint ? [
-  "assets:stylesheets:lint"
-] : []),
-  load("assets/stylesheets/build"))
-
-/*
- * Clean stylesheets generated by build
- */
-gulp.task("assets:stylesheets:clean",
-  load("assets/stylesheets/clean"))
-
-/*
- * Lint SASS sources
- */
-gulp.task("assets:stylesheets:lint",
-  load("assets/stylesheets/lint"))
-
-/* ----------------------------------------------------------------------------
- * Assets
- * ------------------------------------------------------------------------- */
-
-/*
- * Build assets
- */
-gulp.task("assets:build", [
-  "assets:images:build",
-  "assets:javascripts:build",
-  "assets:stylesheets:build"
-])
-
-/*
- * Clean files generated by build
- */
-gulp.task("assets:clean", [
-  "assets:images:clean",
-  "assets:javascripts:clean",
-  "assets:stylesheets:clean"
-])
-
-/* ----------------------------------------------------------------------------
- * Views
- * ------------------------------------------------------------------------- */
-
-/*
- * Minify views
- */
-gulp.task("views:build", (args.revision ? [
-  "assets:images:build",
-  "assets:stylesheets:build",
-  "assets:javascripts:build"
-] : []).concat(args.clean ? [
-  "views:clean"
-] : []), load("views/build"))
-
-/*
- * Clean views
- */
-gulp.task("views:clean",
-  load("views/clean"))
-
-/* ----------------------------------------------------------------------------
- * MkDocs
- * ------------------------------------------------------------------------- */
-
-/*
- * Build documentation
- */
-gulp.task("mkdocs:build", [
-  "assets:build",
-  "views:build",
-  "mkdocs:clean"
-], load("mkdocs/build"))
-
-/*
- * Clean documentation build
- */
-gulp.task("mkdocs:clean",
-  load("mkdocs/clean"))
-
-/*
- * Restart MkDocs server
- */
-gulp.task("mkdocs:serve",
-  load("mkdocs/serve"))
-
-/* ----------------------------------------------------------------------------
- * Tests
- * ------------------------------------------------------------------------- */
-
-/*
- * Start karma test runner
- */
-gulp.task("tests:unit:watch",
-  load("tests/unit/watch"))
-
-/* ----------------------------------------------------------------------------
- * Interface
- * ------------------------------------------------------------------------- */
-
-/*
- * Build assets and documentation
- */
-gulp.task("build", [
-  "assets:build",
-  "views:build"
-].concat(args.mkdocs
-  ? "mkdocs:build"
-  : []))
-
-/*
- * Clean assets and documentation
- */
-gulp.task("clean", [
-  "assets:clean",
-  "views:clean",
-  "mkdocs:clean"
-])
-
-/*
- * Watch for changes and rebuild assets on the fly
- */
-gulp.task("watch", [
-  "assets:build",
-  "views:build"
-], () => {
-  process.env.WATCH = true
-
-  /* Start MkDocs server */
-  if (args.mkdocs)
-    gulp.start("mkdocs:serve")
-
-  /* Start karma test runner */
-  // if (args.karma)
-  //   gulp.start("tests:unit:watch")
-
-  /* Rebuild stylesheets */
-  gulp.watch([
-    `${config.assets.src}/stylesheets/**/*.scss`
-  ], ["assets:stylesheets:build"])
-
-  /* Rebuild JavaScript */
-  gulp.watch([
-    `${config.assets.src}/javascripts/**/*.{js,jsx}`
-  ], ["assets:javascripts:build:application"])
-
-  /* Copy images */
-  gulp.watch([
-    `${config.assets.src}/images/**/*`
-  ], ["assets:images:build"])
-
-  /* Minify views */
-  gulp.watch([
-    `${config.views.src}/**/*.html`
-  ], ["views:build"])
-})
-
-/*
- * Build assets by default
- */
-gulp.task("default", ["build"])

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+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
@@ -16,4 +16,4 @@ 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.
+IN THE SOFTWARE.

MANIFEST.in

@@ -1,5 +0,0 @@
-recursive-include material *.ico *.js *.css *.html *.svg
-recursive-exclude site *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-include LICENSE

README.md

@@ -1,49 +1,279 @@
-[![Travis][travis-image]][travis-link]
-[![Dependencies][deps-image]][deps-link]
-[![Codacy][codacy-image]][codacy-link]
-[![Docker][docker-image]][docker-link]
-[![PyPI][pypi-image]][pypi-link]
+<p align="center">
+  <a href="https://squidfunk.github.io/mkdocs-material/">
+    <img src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/logo.svg" width="320" alt="Material for MkDocs">
+  </a>
+</p>
 
-  [travis-image]: https://travis-ci.org/squidfunk/mkdocs-material.svg
-  [travis-link]: https://travis-ci.org/squidfunk/mkdocs-material
-  [deps-image]: https://david-dm.org/squidfunk/mkdocs-material/dev-status.svg
-  [deps-link]: https://david-dm.org/squidfunk/mkdocs-material?type=dev
-  [codacy-image]: https://api.codacy.com/project/badge/Grade/fe07aa1fa91d453cb69711d3885c5d7e
-  [codacy-link]: https://www.codacy.com/app/squidfunk/mkdocs-material?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=squidfunk/mkdocs-material&amp;utm_campaign=Badge_Grade
-  [docker-image]: https://img.shields.io/docker/pulls/squidfunk/mkdocs-material.svg
-  [docker-link]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [pypi-image]: https://img.shields.io/pypi/v/mkdocs-material.svg
-  [pypi-link]: https://pypi.python.org/pypi/mkdocs-material
+<p align="center">
+  <strong>
+    A 
+    <a href="https://material.io/">Material Design</a> 
+    theme for 
+    <a href="https://www.mkdocs.org/">MkDocs</a>
+  </strong>
+</p>
 
+<p align="center">
+  <a href="https://github.com/squidfunk/mkdocs-material/actions"><img
+    src="https://github.com/squidfunk/mkdocs-material/workflows/build/badge.svg?branch=master"
+    alt="Build"
+  /></a>
+  <a href="https://pypistats.org/packages/mkdocs-material"><img
+    src="https://img.shields.io/pypi/dm/mkdocs-material.svg" 
+    alt="Downloads"
+  /></a>
+  <a href="https://gitter.im/squidfunk/mkdocs-material"><img 
+    src="https://badges.gitter.im/squidfunk/mkdocs-material.svg" 
+    alt="Chat on Gitter"
+  /></a>
+  <a href="https://pypi.org/project/mkdocs-material"><img 
+    src="https://img.shields.io/pypi/v/mkdocs-material.svg" 
+    alt="Python Package Index"
+  /></a>
+  <a href="https://hub.docker.com/r/squidfunk/mkdocs-material/"><img 
+    src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material" 
+    alt="Docker Pulls"
+  /></a>
+</p>
 
-# Material for MkDocs
+<p align="center">
+  Write your documentation in Markdown and create a professional static site for
+  your Open Source or commercial project in minutes – searchable, customizable,
+  more than 60 languages, for all devices.
+</p>
 
-A Material Design theme for [MkDocs](http://www.mkdocs.org).
+<p align="center">
+  <a href="https://squidfunk.github.io/mkdocs-material/getting-started/">
+    <img src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/screenshot.png" width="700" />
+  </a>
+</p>
 
-[![Material for MkDocs](docs/images/material.png)](http://squidfunk.github.io/mkdocs-material/)
+<p align="center">
+  <em>
+    Check out the demo – 
+    <a
+      href="https://squidfunk.github.io/mkdocs-material/"
+    >squidfunk.github.io/mkdocs-material</a>.
+  </em>
+</p>
+
+<h2></h2>
+<p id="premium-sponsors">&nbsp;</p>
+<p align="center"><strong>Silver sponsors</strong></p>
+<p align="center">
+  <a href="https://fastapi.tiangolo.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-fastapi.png" height="120"
+  /></a>
+</p>
+<p>&nbsp;</p>
+<p align="center"><strong>Bronze sponsors</strong></p>
+<p align="center">
+  <a href="https://cirrus-ci.org/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cirrus-ci.png" height="58"
+  /></a>
+  <a href="https://docs.baslerweb.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-basler.png" height="58"
+  /></a>
+  <a href="https://kx.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kx.png" height="58"
+  /></a>
+  <a href="https://www.manticoregames.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-manticore-games.png" height="58"
+  /></a>
+  <a href="https://orion-docs.prefect.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-prefect.png" height="58"
+  /></a>
+  <a href="https://datadoghq.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-datadog.png" height="58"
+  /></a>
+  <a href="https://www.zenoss.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-zenoss.png" height="58"
+  /></a>
+  <a href="https://docs.posit.co" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-posit.png" height="58"
+  /></a>
+  <a href="https://n8n.io" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-n8n.png" height="58"
+  /></a>
+  <a href="https://www.dogado.de" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-dogado.png" height="58"
+  /></a>
+  <a href="https://wwt.com" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-wwt.png" height="58"
+  /></a>
+  <a href="https://coda.io" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-coda.png" height="58"
+  /></a>
+  <a href="https://elastic.co" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-elastic.png" height="58"
+  /></a>
+  <a href="https://ipfabric.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-ip-fabric.png" height="58"
+  /></a>
+  <a href="https://www.apex.ai/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-apex-ai.png" height="58"
+  /></a>
+  <a href="https://jitterbit.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-jitterbit.png" height="58"
+  /></a>
+  <a href="https://sparkfun.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sparkfun.png" height="58"
+  /></a>
+  <a href="https://eccenca.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-eccenca.png" height="58"
+  /></a>
+  <a href="https://neptune.ai/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png" height="58"
+  /></a>
+  <a href="https://cash.app/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58"
+  /></a>
+  <a href="https://rackn.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png" height="58"
+  /></a>
+  <a href="https://civicactions.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-civic-actions.png" height="58"
+  /></a>
+  <a href="https://bitcrowd.net/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-bitcrowd.png" height="58"
+  /></a>
+  <a href="https://getscreen.me/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-getscreenme.png" height="58"
+  /></a>
+  <a href="https://botcity.dev/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-botcity.png" height="58"
+  /></a>
+  <a href="https://www.springernature.com/gp" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sn-technology.png" height="58"
+  /></a>
+  <a href="https://kolena.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kolena.png" height="58"
+  /></a>
+  <a href="https://www.evergiving.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-evergiving.png" height="58"
+  /></a>
+  <a href="https://koor.tech/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-koor.png" height="58"
+  /></a>
+  <a href="https://astral.sh/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-astral.png" height="58"
+  /></a>
+</p>
+<p>&nbsp;</p>
+
+## Everything you would expect
+
+### It's just Markdown
+
+Focus on the content of your documentation and create a professional static site
+in minutes. No need to know HTML, CSS or JavaScript – let Material for MkDocs do
+the heavy lifting for you.
+
+### Works on all devices
+
+Serve your documentation with confidence – Material for MkDocs automatically
+adapts to perfectly fit the available screen estate, no matter the type or size
+of the viewing device. Desktop. Tablet. Mobile. All great.
+
+### Made to measure
+
+Make it yours – change the colors, fonts, language, icons, logo, and more with
+a few lines of configuration. Material for MkDocs can be easily extended and
+provides many options to alter appearance and behavior.
+
+### Fast and lightweight
+
+Don't let your users wait – get incredible value with a small footprint by using
+one of the fastest themes available with excellent performance, yielding optimal
+search engine rankings and happy users that return.
+
+### Built for everyone
+
+Make accessibility a priority – users can navigate your documentation with touch
+devices, keyboards, and screen readers. Semantic markup ensures that your
+documentation works for everyone.
+
+### Open Source
+
+Trust 20,000+ users – choose a mature and actively maintained solution built
+with state-of-the-art Open Source technologies. Keep ownership of your content
+without fear of vendor lock-in. Licensed under MIT.
 
 ## Quick start
 
-Install with `pip`:
+Material for MkDocs can be installed with `pip`:
 
 ``` sh
 pip install mkdocs-material
 ```
 
-Add the following line to your `mkdocs.yml`:
+Add the following lines to `mkdocs.yml`:
 
 ``` yaml
-theme: 'material'
+theme:
+  name: material
 ```
 
-For detailed installation instructions and a demo, visit
-http://squidfunk.github.io/mkdocs-material/
+For detailed installation instructions, configuration options, and a demo, visit
+[squidfunk.github.io/mkdocs-material][Material for MkDocs]
+
+  [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+
+## Trusted by ...
+
+### ... industry leaders
+
+[Atlassian](https://atlassian.github.io/data-center-helm-charts/),
+[AWS](https://aws.github.io/copilot-cli/),
+[Bloomberg](https://bloomberg.github.io/selekt/),
+[CERN](http://abpcomputing.web.cern.ch/),
+[Datadog](https://datadoghq.dev/integrations-core/),
+[Google](https://google.github.io/accompanist/),
+[Hewlett Packard](https://hewlettpackard.github.io/squest/),
+[ING](https://ing-bank.github.io/baker/),
+[Intel](https://open-amt-cloud-toolkit.github.io/docs/),
+[JetBrains](https://jetbrains.github.io/projector-client/mkdocs/),
+[LinkedIn](https://linkedin.github.io/school-of-sre/),
+[Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
+[Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
+[Netflix](https://netflix.github.io/titus/),
+[Salesforce](https://policy-sentry.readthedocs.io/en/latest/),
+[SoundCloud](https://intervene.dev/),
+[Square](https://square.github.io/okhttp/),
+[Zalando](https://opensource.zalando.com/skipper/)
+
+### ... and successful Open Source projects
+
+[Arduino](https://arduino.github.io/arduino-cli/),
+[AutoKeras](https://autokeras.com/),
+[BFE](https://www.bfe-networks.net/),
+[CentOS](https://docs.infra.centos.org/),
+[Crystal](https://crystal-lang.org/reference/),
+[Electron](https://www.electron.build/),
+[FastAPI](https://fastapi.tiangolo.com/),
+[GoReleaser](https://goreleaser.com/),
+[Knative](https://knative.dev/docs/),
+[Kubernetes](https://kops.sigs.k8s.io/),
+[kSQL](https://docs.ksqldb.io/),
+[MindsDB](https://docs.mindsdb.com/),
+[Nokogiri](https://nokogiri.org/),
+[OpenFaaS](https://docs.openfaas.com/),
+[Percona](https://docs.percona.com/percona-monitoring-and-management/),
+[Pi-Hole](https://docs.pi-hole.net/),
+[Pydantic](https://pydantic-docs.helpmanual.io/),
+[Renovate](https://docs.renovatebot.com/),
+[Traefik](https://docs.traefik.io/),
+[Trivy](https://github.com/aquasecurity/trivy)
+[Vapor](https://docs.vapor.codes/),
+[ZeroNet](https://zeronet.io/docs/),
+[WebKit](https://docs.webkit.org/),
+[WTF](https://wtfutil.com/)
 
 ## License
 
 **MIT License**
 
-Copyright (c) 2016-2017 Martin Donath
+Copyright (c) 2016-2023 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

docs/alternatives.md

@@ -0,0 +1,112 @@
+# Alternatives
+
+There are tons of static site generators and themes out there and choosing the
+right one for your tech stack is a tough decision. If you're unsure if Material
+for MkDocs is the right solution for you, this section should help you evaluate
+alternative solutions.
+
+## Docusaurus
+
+[Docusaurus] by Facebook is a very popular documentation generator and a good
+choice if you or your company are already using [React] to build your site.
+It will generate a [single page application] which is fundamentally different
+from the site Material for MkDocs generates for you.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Provides many components that aid in technical writing
+- Large and rich ecosystem, backed by Facebook
+
+__Challenges__
+
+- High learning curve, JavaScript knowledge mandatory
+- JavaScript ecosystem is very volatile, rather high maintenance
+- More time needed to get up and running
+
+While [Docusaurus] is one of the best choices when it comes to documentation
+sites that output a single page application, there are many more solutions,
+including [Docz], [Gatsby], [Vuepress] and [Docsify] that approach
+this problem similarly.
+
+  [Docusaurus]: https://docusaurus.io/
+  [React]: https://reactjs.org/
+  [single page application]: https://en.wikipedia.org/wiki/Single-page_application
+  [Docz]: https://www.docz.site/
+  [Gatsby]: https://www.gatsbyjs.com/
+  [VuePress]: https://vuepress.vuejs.org/
+  [Docsify]: https://docsify.js.org/
+
+## Jekyll
+
+[Jekyll] is probably one of the most mature and widespread static site
+generators and is written in [Ruby]. It is not specifically geared towards
+technical project documentation and has many themes to choose from, which
+can be challenging.
+
+__Advantages__
+
+- Battle-tested, rich ecosystem, many themes to choose from
+- Brings great capabilities for blogging  (permalinks, tags, etc.)
+- Generates a SEO-friendly site, similar to Material for MkDocs
+
+__Challenges__
+
+- Not specifically geared towards technical project documentation
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- More time needed to get up and running
+
+  [Jekyll]: https://jekyllrb.com/
+  [Ruby]: https://www.ruby-lang.org/de/
+
+## Sphinx
+
+[Sphinx] is an alternative static site generator specifically geared towards
+generating reference documentation, offering powerful capabilities that are
+lacking in MkDocs. It uses [reStructured text], a format similar to Markdown,
+which some users find harder to use.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Generates reference documentation from [Python docstrings]
+- Large and rich ecosystem, used by many Python projects
+
+__Challenges__
+
+- High learning curve, [reStructured text] syntax might be challenging
+- Search is less powerful than the one provided by MkDocs
+- More time needed to get up and running
+
+If you're considering using Sphinx because you need to generate reference
+documentation, you should give [mkdocstrings] a try – an actively maintained
+and popular framework building on top of MkDocs, implementing Sphinx-like
+functionality.
+
+  [Sphinx]: https://www.sphinx-doc.org/
+  [reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText
+  [Python docstrings]: https://www.python.org/dev/peps/pep-0257/
+  [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
+
+## GitBook
+
+[GitBook] offers a hosted documentation solution that generates a beautiful and
+functional site from Markdown files in your GitHub repository. However, it was
+once Open Source, but turned into a closed source solution some time ago.
+
+__Advantages__
+
+- Hosted solution, minimal technical knowledge required
+- Custom domains, authentication and other enterprise features
+- Great collaboration features for teams
+
+__Challenges__
+
+- Closed source, not free for proprietary projects
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- Many Open Source projects moved away from GitBook
+
+Many users switched from [GitBook] to Material for MkDocs, as they want to keep
+control and ownership of their documentation, favoring an Open Source solution.
+
+  [GitBook]: https://www.gitbook.com/