Merge https://github.com/squidfunk/mkdocs-material

.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

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <[email protected]>
+# Copyright (c) 2016-2023 Martin Donath <[email protected]>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -22,6 +22,6 @@
 .git
 .github
 docs
-material/.overrides
+material/overrides
 node_modules
 src

.editorconfig

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <[email protected]>
+# Copyright (c) 2016-2023 Martin Donath <[email protected]>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -30,10 +30,6 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-# Markdown
-[*.md]
-trim_trailing_whitespace = false
-
 # Python
 [*.py]
 indent_style = space

.eslintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <[email protected]>
+# Copyright (c) 2016-2023 Martin Donath <[email protected]>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.eslintrc

@@ -320,7 +320,6 @@
       }
     ],
     "jsdoc/empty-tags": "warn",
-    "jsdoc/newline-after-description": "warn",
     "jsdoc/no-bad-blocks": "warn",
     "jsdoc/no-defaults": "warn",
     "jsdoc/no-types": "warn",

.github/ISSUE_TEMPLATE/01-report-a-bug.yml

@@ -0,0 +1,124 @@
+name: Report a bug
+description: Something is not working? Report a bug
+body:
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: >-
+        This field is optional. You may provide additional context for the bug
+        you want to report, helping us to understand what you are working on and
+        what you are trying to achieve. If the context is not relevant, you can
+        leave this field empty.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#context)
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug description
+      description: >-
+        Please give a detailed description of the bug. Explain where Material
+        for MkDocs does not behave as you would expect it to. Be as specific as
+        possible. If you have found a workaround or a fix for the problem,
+        please let us maintainers (and all other users) know.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#bug-description)
+    validations:
+      required: true
+
+  - type: textarea
+    id: related-links
+    attributes:
+      label: Related links
+      description: >-
+        Please list all links to the sections of
+        [our documentation](https://squidfunk.github.io/mkdocs-material/) that
+        are relevant to the bug in order to show that you have consulted and
+        thoroughly read it. Additionally, list links to possibly related open
+        and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
+        and [discussions](https://github.com/squidfunk/mkdocs-material/discussions)
+        you encountered when searching our issue tracker.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#related-links)
+      value: |-
+        - [Reporting a bug](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/)
+        -
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: >-
+        Please create a __.zip file__ with a __minimal reproduction__ for the
+        bug. First, read our [reproduction guide](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/)
+        that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/plugins/info/) (mandatory) to create a self-contained
+        .zip file with the reproduction. We reserve the right to close issues
+        without .zip files.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
+      placeholder: |-
+        Drag and drop the .zip file with the minimal reproduction here.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to reproduce
+      description: >-
+        Please provide a detailed list of instructions, guiding us maintainers
+        through the required steps, helping us to recreate the problem using the
+        minimal reproduction you provided. Be as specific as possible and as
+        verbose as necessary – try not to leave anything out.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#steps-to-reproduce)
+      placeholder: |-
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      description: >-
+        This field is optional. If the bug only happens in __specific browsers__,
+        please select them from the dropdown below. If your browser is not
+        listed or the version is relevant, you may select _Other_ and provide
+        more details in the field above.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#browser)
+      multiple: true
+      options:
+        - Chrome
+        - Safari
+        - Edge
+        - Firefox
+        - Opera
+        - Other
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before submitting
+      description: >-
+        Please ensure your bug report fulfills all of the following requirements.
+        If you are not sure what a specific requirement means, follow the link
+        to learn about it and understand why it is necessary before ticking the
+        box. This will save the maintainers and you valuable time.
+      options:
+        - label: >-
+            I have read and followed the [bug reporting guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/).
+          required: true
+        - label: >-
+            I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material/),
+            and possibly related [issues](https://github.com/squidfunk/mkdocs-material/issues)
+            and [discussions](https://github.com/squidfunk/mkdocs-material/discussions).
+          required: true
+        - label: >-
+            I assure that I have [removed all customizations](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#remove-customizations)
+            before submitting this bug report.
+          required: true
+        - label: >-
+            I have attached a __.zip file__ with a [minimal reproduction](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/).
+          required: true

.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml

@@ -0,0 +1,65 @@
+name: Report a documentation issue
+description: Missing information in our docs? Report a documentation issue
+labels:
+  - documentation
+body:
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >-
+        Please describe the inconsistency or issue you have found in
+        [our documentation](https://squidfunk.github.io/mkdocs-material/)
+        or indicate where you feel there is a need for improvement. Furthermore,
+        explain the severity of the issue, i.e., its impact on you and potentially
+        other users.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#description)
+    validations:
+      required: true
+
+  - type: textarea
+    id: related-links
+    attributes:
+      label: Related links
+      description: >-
+        Please list all links to the sections of [our documentation](https://squidfunk.github.io/mkdocs-material/)
+        that are impacted by the issue you described above. If applicable,
+        add screenshots. Additionally, list links to possibly related open
+        and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
+        and [discussions](https://github.com/squidfunk/mkdocs-material/discussions)
+        you encountered when searching our issue tracker.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+      value: |-
+        - [Reporting a docs issue](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/)
+        -
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-change
+    attributes:
+      label: Proposed change
+      description: >-
+        This field is optional. You may provide an improvement proposal for our
+        documentation by describing your suggestion in the text field below or
+        creating a pull request after reporting this issue referencing the issue.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#proposed-change)
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before submitting
+      description: >-
+        Please ensure your documentation issue report fulfills all of the
+        following requirements. If you need clarification on a specific
+        requirement, follow the link to learn about it and understand why it is
+        necessary before ticking the box. This will save the maintainers and you
+        valuable time.
+      options:
+        - label: >-
+            I have read and followed the [documentation issue guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
+          required: true
+        - label: >-
+            I have attached the links to the affected sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+          required: true

.github/ISSUE_TEMPLATE/03-request-a-change.yml

@@ -0,0 +1,95 @@
+name: Request a change
+description: Want to submit an idea? Propose a change or feature request
+body:
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: >-
+        This field is optional. You may provide additional context for the idea
+        you want to propose, helping us to understand what you are working on
+        and what you are trying to achieve. If the context is not relevant, you
+        can leave this field empty.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#context)
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >-
+        Please provide a detailed description of your idea in 2-3 sentences so
+        that we maintainers can fully understand what change, feature, or the
+        improvement you are proposing. Don't yet explain the benefits of your
+        idea, we'll come to that. Focus on functionality.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#description)
+    validations:
+      required: true
+
+  - type: textarea
+    id: related-links
+    attributes:
+      label: Related links
+      description: >-
+        Please list all links to open and closed [issues](https://github.com/squidfunk/mkdocs-material/issues),
+        [discussions](https://github.com/squidfunk/mkdocs-material/discussions),
+        or to [documentation sections](https://squidfunk.github.io/mkdocs-material/)
+        that are relevant to your idea. If you discussed your idea with the
+        community on our [discussion board](https://github.com/squidfunk/mkdocs-material/discussions)
+        prior to creating this change request, please link the discussion here as well.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#related-links)
+      value: |-
+        - [Requesting a change](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/)
+        -
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: Use Cases
+      description: >-
+        Please explain how your idea will work from an author's and user's
+        perspective. Elaborate on how the change would positively impact not only
+        you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+        of the project.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
+    validations:
+      required: true
+
+  - type: textarea
+    id: visuals
+    attributes:
+      label: Visuals
+      description: >-
+        This field is optional. You may provide sketches, screenshots, mockups,
+        or external assets to illustrate your idea. If you have seen this change,
+        feature, or improvement used in other static site generators or themes,
+        please describe how it is implemented and advertised.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#visuals)
+      placeholder: |-
+        Drag and drop images here or link external assets.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before submitting
+      description:
+        Please ensure your idea fulfills all of the following requirements. If
+        you need clarification on a specific requirement, follow the link to
+        learn about it and understand why it is necessary before ticking the box.
+        This will save the maintainers and you valuable time.
+      options:
+      - label: >-
+            I have read and followed the [change request guidelines](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/).
+        required: true
+      - label: >-
+            I have verified that [my idea is a change request and not a bug report](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#its-not-a-bug-its-a-feature).
+        required: true
+      - label: >-
+            I have ensured that, to the best of my knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
+        required: true
+      - label: >-
+            I have included relevant links to [the documentation](https://squidfunk.github.io/mkdocs-material/), related [issues](https://github.com/squidfunk/mkdocs-material/issues),
+            and [discussions](https://github.com/squidfunk/mkdocs-material/discussions) to underline the need for my idea.
+        required: true