Material for MkDocs 9

.github/ISSUE_TEMPLATE/bug.yml

@@ -1,77 +1,119 @@
 name: Bug Report
-description: Report a bug
+description: Something is not working? Report a bug in Material for MkDocs.
+
 body:
-  - type: checkboxes
-    attributes:
-      label: Contribution guidelines
-      description: Please read the contribution guidelines before proceeding.
-      options:
-        - label: I've read the [contribution guidelines](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md) and wholeheartedly agree
-          required: true
-  - type: checkboxes
+  - type: textarea
+    id: context
     attributes:
-      label: I've found a bug and checked that ...
-      description: Make sure that your request fulfills all of the following requirements. If one requirement cannot be satisfied, explain in detail why.
-      options:
-      - label: ... the problem doesn't occur with the `mkdocs` or `readthedocs` themes
-        required: true
-      - label: ... the problem persists when all overrides are removed, i.e. `custom_dir`, `extra_javascript` and `extra_css`
-      - label: ... the documentation does not mention anything about my problem
-      - label: ... there are no open or closed issues that are related to my problem
+      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/bug-report/#context)
+    validations:
+      required: false
+
   - type: textarea
+    id: bug-description
     attributes:
-      label: Description
-      description: Please provide a brief description of the bug in 1-2 sentences.
+      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/bug-report/#bug-description)
     validations:
       required: true
+
   - type: textarea
+    id: related-links
     attributes:
-      label: Expected behaviour
-      description: Please describe precisely what you'd expect to happen.
+      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 issues
+        or discussions you encountered when searching our issue tracker.
+        [More](https://squidfunk.github.io/mkdocs-material/bug-report/#related-links)
+      value: |-
+        - [Bug reporting](https://squidfunk.github.io/mkdocs-material/bug-report/)
+        -
     validations:
       required: true
+
   - type: textarea
+    id: reproduction
     attributes:
-      label: Actual behaviour
-      description: Please describe precisely what is actually happening.
+      label: Reproduction
+      description: >-
+        Please create a __minimal reproduction__ for the bug. First, read our
+        [reproduction guide](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/)
+        that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#creating-a-zip-file) (mandatory) to create a self-contained
+        .zip file with the reproduction. Without a reproduction, it can be
+        challenging to fix the bug. [More](https://squidfunk.github.io/mkdocs-material/bug-report/#reproduction)
+      placeholder: |-
+        Drag and drop .zip file with reproduction here.
     validations:
       required: true
+
   - type: textarea
+    id: steps-to-reproduce
     attributes:
       label: Steps to reproduce
-      description: Please describe the steps to reproduce the bug.
+      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/bug-report/reproduction/#steps-to-reproduce)
       placeholder: |-
         1. ...
         2. ...
         3. ...
     validations:
       required: true
-  - type: textarea
-    attributes:
-      label: Package versions
-      description: Please provide all package versions, i.e. run the commands in backticks on a shell.
-      value: |-
-        - Python: `python --version`
-        - MkDocs: `mkdocs --version`
-        - Material: `pip show mkdocs-material | grep -E ^Version`
-    validations:
-      required: true
-  - type: textarea
+
+  - type: dropdown
+    id: browser
     attributes:
-      label: Configuration
-      description: Please provide a minimal (!) `mkdocs.yml` to reproduce the bug.
-      placeholder: |-
-        site_name: My Docs
-        site_url: https://example.com/docs
-      render: yaml
-    validations:
-      required: true
-  - type: textarea
+      label: Browser
+      description: >-
+        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/bug-report/reproduction/#browser)
+      multiple: true
+      options:
+        - Chrome
+        - Safari
+        - Edge
+        - Firefox
+        - Opera
+        - Other
+
+  - type: checkboxes
+    id: checklist
     attributes:
-      label: System information
-      description: Please provide your operating system and browser type and version.
-      value: |-
-        - Operating system: ...
-        - Browser: ...
-    validations:
-      required: true
+      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/bug-report/).
+          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)
+            or [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/bug-report/#remove-customizations)
+            before submitting this bug report.
+          required: true
+        - label: >-
+            I have attached a [minimal reproduction](https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/).
+          required: true

.github/ISSUE_TEMPLATE/translate.yml

@@ -24,13 +24,15 @@ body:
         {% macro t(key) %}{{ {
           "language": "en",
           "direction": "ltr",
+          "action.edit": "Edit this page",
+          "action.skip": "Skip to content",
+          "action.view": "View source of this page",
           "announce.dismiss": "Don't show this again",
           "clipboard.copy": "Copy to clipboard",
           "clipboard.copied": "Copied to clipboard",
           "consent.accept": "Accept",
           "consent.manage": "Manage settings",
           "consent.reject": "Reject",
-          "edit.link": "Edit this page",
           "footer": "Footer",
           "footer.next": "Next",
           "footer.previous": "Previous",
@@ -52,10 +54,9 @@ body:
           "search.result.term.missing": "Missing",
           "select.language": "Select language",
           "select.version": "Select version",
-          "skip.link": "Skip to content",
+          "source": "Go to repository",
           "source.file.date.created": "Created",
           "source.file.date.updated": "Last update",
-          "source.link": "Go to repository",
           "tabs": "Tabs",
           "toc": "Table of contents",
           "top": "Back to top"

.gitignore

@@ -45,6 +45,10 @@
 .eslintcache
 __pycache__
 
+# Examples
+example
+example.zip
+
 # -----------------------------------------------------------------------------
 # General
 # -----------------------------------------------------------------------------

.stylelintrc

@@ -103,6 +103,7 @@
       "dppx",
       "deg",
       "em",
+      "fr",
       "mm",
       "ms",
       "px",

.vscode/launch.json

@@ -10,7 +10,7 @@
         "--incognito"
       ],
       "url": "http://localhost:8000/mkdocs-material/",
-      "webRoot": ".",
+      "webRoot": "${workspaceFolder}",
       "smartStep": true
     }
   ]

CHANGELOG

@@ -1,3 +1,46 @@
+mkdocs-material-9.0.0 (2023-01-02)
+
+  Additions and improvements
+
+  * Added support for rich search previews
+  * Added support for tokenizer lookahead
+  * Added support for better search highlighting
+  * Added support for excluding content from search
+  * Added support for configurable search pipeline
+  * Added support for offline search via offline plugin
+  * Added support for multiple instances of built-in tags plugin
+  * Added support for removing copy-to-clipboard button
+  * Added support for removing footer navigation
+  * Added support for button to view the source of a page
+  * Improved readability of query string for search sharing
+  * Improved stability of search plugin when using --dirtyreload
+  * Improved search result group button, now sticky and stable
+  * Updated Norwegian translations
+  * Updated MkDocs to 1.4.2
+
+  Removals
+
+  * Removed deprecated alternative admonition qualifiers
+  * Removed :is() selectors (in output) for easier overriding
+  * Removed .title suffix on translations
+  * Removed legacy method for providing page title in feedback URL
+  * Removed support for indexing only titles in search
+  * Removed support for custom search transforms
+  * Removed support for custom search workers
+  * Removed temporary snow feature (easter egg)
+
+  Fixes
+
+  * Fixed Norwegian and Korean language code
+  * Fixed detection of composition events in search interface
+  * Fixed search plugin not using title set via front matter
+  * Fixed search highlighting of tags
+  * Fixed search sharing URL using post transformed string
+  * Fixed theme-color meta tag getting out-of-sync with palette toggle
+  * Fixed prev/next page keyboard navigation when footer is not present
+  * Fixed overflowing navigation tabs not being scrollable
+  * Fixed inclusion of code block line numbers from search
+
 mkdocs-material-8.5.11+insiders-4.27.0 (2022-12-20)
 
   * Added built-in typeset plugin to preserve formatting in sidebars

docs/blog/posts/blog-support-just-landed.md

@@ -64,7 +64,7 @@ mkdocs new .
 
 This will create the following structure:
 
-```
+``` { .sh .no-copy }
 .
 ├─ docs/
 │  └─ index.md
@@ -118,7 +118,7 @@ first post. All blog posts are written with the [exact same Markdown flavor] as
 already included with Material for MkDocs. First, create a folder called `posts`
 with a file called `hello-world.md`:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ docs/
 │  ├─ posts/