Merge branch 'master' of github.com:squidfunk/mkdocs-material

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

@@ -31,7 +31,7 @@ body:
       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
+        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)
@@ -54,7 +54,7 @@ body:
         .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 .zip file with minimal reproduction here.
+        Drag and drop the .zip file with minimal reproduction here.
     validations:
       required: true
 

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

@@ -12,7 +12,7 @@ body:
         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., it's impact on you and potentially
+        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:

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

@@ -17,8 +17,8 @@ body:
     attributes:
       label: Description
       description: >-
-        Please provide a detailed description of your idea in 2-3 sentences, so
+        Please provide a detailed description of your idea in 2-3 sentences so
-        that we maintainers can fully understand what change, feature, or
+        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)
@@ -31,7 +31,7 @@ body:
       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)
+        [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
@@ -50,8 +50,8 @@ body:
       label: Use Cases
       description: >-
         Please explain how your idea will work from an author's and user's
-        perspective. Elaborate how the change would positively impact not only
+        perspective. Elaborate on how the change would positively impact not only
-        you, but the community, and how it aligns with the goals and [philopsophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+        you but the 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:
@@ -87,9 +87,9 @@ body:
             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 knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
+            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)
+            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

.github/ISSUE_TEMPLATE/04-add-a-translation.yml

@@ -17,7 +17,7 @@ body:
     id: translations
     attributes:
       label: Translations
-      description: Please translate the labels on the right, e.g. "Copy to clipboard", etc.
+      description: Please translate the labels on the right, e.g., "Copy to clipboard", etc.
       value: |-
         {% macro t(key) %}{{ {
           "language": "en",
@@ -73,7 +73,7 @@ body:
       options:
         - label: I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
           required: true
-        - label: I assure that the translations are accurate to my best knowledge.
+        - label: I assure that the translations are accurate to the best of my knowledge.
           required: true
         - label: >-
             __Optional__: I want to integrate this translation myself and create a

docs/contributing/index.md

@@ -9,8 +9,8 @@ bugs, a lot of work from us maintainers is required.
 
 We have invested quite a lot of time in creating better templates for our
 [issue tracker], optimizing the processes for our users to report bugs, request
-features or changes, contribute to the project or exchange with our community. This section of
+features or changes, contribute to the project, or exchange with our community. 
-the documentation explains each process.
+This section of the documentation explains each process.
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 

docs/contributing/reporting-a-bug.md

@@ -50,7 +50,7 @@ adjusted all partials you have overridden.
 
     A handful of the features Material for MkDocs offers can only be implemented
     with customizations. If you find a bug in any of the customizations [that
-    our documentation explicitly mentions], you are of course encouraged to
+    our documentation explicitly mentions], you are, of course, encouraged to
     report it.
 
 __Don't be shy to ask on our [discussion board] for help if you run into
@@ -74,7 +74,7 @@ problems.__
 
 At this stage, we know that the problem persists in the latest version and is
 not caused by any of your customizations. However, the problem might result from
-a small typo or a syntactical error in a configuration file, e.g. `mkdocs.yml`.
+a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
 
 Now, before you go through the trouble of creating a bug report that is answered
 and closed right away with a link to the relevant documentation section or
@@ -167,7 +167,7 @@ relevant. Don't write about the bug here.
 
 ### Description
 
-Now, to the bug, you want to report. Provide a clear, focused, specific, and
+Now, to the bug you want to report. Provide a clear, focused, specific, and
 concise summary of the bug you encountered. Explain why you think this is a bug
 that should be reported to Material for MkDocs, and not to one of its
 dependencies.[^3] Adhere to the following principles:
@@ -189,7 +189,7 @@ dependencies.[^3] Adhere to the following principles:
     or two sentences, perfect. Don't inflate it – maintainers and future users
     will be grateful for having to read less.
 
--   __One bug at a time__ – if you encountered several unrelated bugs, please
+-   __One bug at a time__ – if you encounter several unrelated bugs, please
     create separate issues for them. Don't report them in the same issue, as
     this makes attribution difficult.
 
@@ -247,7 +247,7 @@ After you have created the reproduction, you should have a .zip file, ideally no
 larger than 1 MB. Just drag and drop the .zip file into this field, which will
 automatically upload it to GitHub.
 
-> __Why we need this__: if an issue contains no minimal reproduction, or just
+> __Why we need this__: if an issue contains no minimal reproduction or just
 > a link to a repository with thousands of files, the maintainers would need to
 > invest a lot of time into trying to recreate the right conditions to even
 > inspect the bug, let alone fix it.
@@ -269,14 +269,14 @@ automatically upload it to GitHub.
 ### Steps to reproduce
 
 At this point, you provided us with enough information to understand the bug,
-and you gave us a reproduction that we can run and inspect. However, when we
+and you gave us a reproduction that we could run and inspect. However, when we
 run your reproduction, it might not be immediately apparent how we can see
 the bug in action.
 
 Next, please list the specific steps we should follow when running your
 reproduction to observe the bug. Keep the steps short and concise, and make sure
 not to leave anything out. Use simple language as you would explain it to a
-five-year-old and focus on continuity.
+five-year-old, and focus on continuity.
 
 > __Why we need this__: we must know how to navigate your reproduction in order
 > to observe the bug, as some bugs only occur at certain viewports or in
@@ -301,8 +301,8 @@ only relevant when the bug you are reporting does not involve a crash when
 
 Thanks for following the guide and creating a high-quality and complete bug
 report – you are almost done. This section ensures that you have read this guide
-and have worked to your best knowledge to provide us with everything we need to
+and have worked to the best of your knowledge to provide us with everything we 
-know to help you.
+need to know to help you.
 
 __We'll take it from here.__
 

docs/contributing/reporting-a-docs-issue.md

@@ -1,7 +1,7 @@
 # Reporting a docs issue
 
-In the past 7 years, our documentation has grown to more than 60 pages. With a
+In the past seven years, our documentation has grown to more than 60 pages. With
-site being this large, inconsistencies can occur. If you found an inconsistency
+a site being this large, inconsistencies can occur. If you find an inconsistency
 or see room for clarification or improvement, please submit an issue to
 our public [issue tracker] by following this guide.
 
@@ -50,7 +50,7 @@ describe the severity of the issue:
     precisely explained in one or two sentences, perfect. Maintainers and
     future users will be grateful for having to read less.
 
--   __One issue at a time__ – if you encountered several unrelated inconsistencies,
+-   __One issue at a time__ – if you encounter several unrelated inconsistencies,
     please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
 
 > __Why we need this__: in order for us to understand the problem, we need a
@@ -73,7 +73,7 @@ where possible, as it simplifies discovery.
 Now that you have provided us with the description and links to the
 documentation sections, you can help us, maintainers, and the community by
 proposing an improvement. You can sketch out rough ideas or write a concrete
-proposal. This field is optional, but very helpful.
+proposal. This field is optional but very helpful.
 
 > __Why we need this__: improvement proposal can be beneficial for other users 
 > who encounter the same issue, as they offer solutions before we maintainers
@@ -83,7 +83,7 @@ proposal. This field is optional, but very helpful.
 
 Thanks for following the guide and creating a high-quality and complete issue 
 report – you are almost done. This section ensures that you have read this guide
-and have worked to your best knowledge to provide us with every piece of
+and have worked to the best of your knowledge to provide us with every piece of
 information we need to improve our documentation.
 
 __We'll take it from here.__

docs/contributing/requesting-a-change.md

@@ -1,6 +1,6 @@
 # Requesting a change
 
-Material for MkDocs is a powerful tool to create beautiful and functional
+Material for MkDocs is a powerful tool for creating beautiful and functional
 project documentation. With more than 20,000 users, we understand that our
 project serves a wide range of use cases, which is why we have created the
 following guide.
@@ -12,7 +12,7 @@ to maintain existing functionality while constantly adding new features at the
 same time. We highly value every idea or contribution from our community, and
 we kindly ask you to take the time to read the following guidelines before 
 submitting your change request in our public [issue tracker]. This will help us 
-better understand the proposed change, and how it will benefit the community.
+better understand the proposed change and how it will benefit the community.
 
 This guide is our best effort to explain the criteria and reasoning behind our
 decisions when evaluating change requests and considering them for
@@ -33,7 +33,7 @@ __Please find answers to the following questions before creating an issue.__
 
 ### It's not a bug, it's a feature
 
-Change requests are intended for suggesting minor adjustments, ideas for new
+Change requests are intended to suggest minor adjustments, ideas for new
 features, or to influence the project's direction and vision. It is important
 to note that change requests are not intended for reporting bugs, as they're
 missing essential information for debugging.
@@ -65,8 +65,8 @@ that benefits a large number of users.
 
 Now that you have taken the time to do the necessary preliminary work and ensure 
 that your idea meets our requirements, you are invited to create a change
-request. The following guide will walk you through all necessary steps to help
+request. The following guide will walk you through all the necessary steps to 
-you submit a comprehensive and useful issue:
+help you submit a comprehensive and useful issue:
 
 - [Title]
 - [Context] <small>optional</small>
@@ -105,7 +105,7 @@ in which you're using Material for MkDocs, and what you _think_ might be
 relevant. Don't write about the change request here.
 
 > __Why this might be helpful__: some ideas might only benefit specific
-> settings, environments or edge cases, for example, when your documentation
+> settings, environments, or edge cases, for example, when your documentation
 > contains thousands of documents. With a little context, change requests
 > can be prioritized more accurately.
 
@@ -120,7 +120,7 @@ in one of its dependencies:[^1]
     our upstream dependencies, including [MkDocs], [Python Markdown],
     [Python Markdown Extensions] or third-party plugins. It's a good idea to
     think about whether your idea is beneficial to other themes, upstreaming
-    change requests for bigger impact.
+    change requests for a bigger impact.
 
 -   __Explain the <u>what</u>, not the <u>why</u>__ – don't explain
     [the benefits of your idea][Use cases] here, we're getting there.
@@ -137,7 +137,7 @@ together, please open separate change requests for each of those ideas.
 
 :material-run-fast: __Stretch goal__ – if you have a customization or another
 way to add the proposed change, you can help other users by sharing it here
-before we  maintainers can add it to our code base.
+before we maintainers can add it to our code base.
 
 > __Why we need this__: To understand and evaluate your proposed change, we
 > need to have a clear understanding of your idea. By providing a detailed and 
@@ -164,7 +164,7 @@ the link to the discussion as well.
 ### Use cases
 
 Explain how your change request would work from an author's and user's
-perspective – what's the expected impact and why does it not only benefit you,
+perspective – what's the expected impact, and why does it benefit not only you
 but other users? How many of them? Furthermore, would it potentially break
 existing functionality?
 
@@ -198,7 +198,7 @@ it and describing how it was implemented and incorporated.
 
 Thanks for following the change request guide and creating a high-quality 
 change request. This section ensures that you have read this guide and have
-worked to your best knowledge to provide us with every piece of information to 
+worked to the best of your knowledge to provide us with every piece of 
-review your idea for Material for MkDocs.
+information to review your idea for Material for MkDocs.
 
 __We'll take it from here.__

docs/setup/index.md

@@ -2,14 +2,14 @@
 
 Material for MkDocs offers a wide range of options for customizing your
 documentation. In this section, we will explain how you can create a meaningful
-structure for your site, change the look and feel, add a blog and comment system
+structure for your site, change the look and feel, add a blog and comment system,
 and build a highly optimized site.
 
 ## Site structure
 
 Set up and customize the structure of your documentation by configuring the
 header and footer to your taste, choosing among many modes of navigation,
-setting up site search and more.
+setting up site search, and more.
 
 <div class="grid cards" markdown>
 
@@ -52,8 +52,8 @@ configuration or alter the appearance.
 
 ## Content
 
-Create a blog, integrate a comment system, connect a git repository and set up
+Create a blog, integrate a comment system, connect a git repository, and set up
-versioned documentation that matches your project's versioning metholodogy.
+versioned documentation that matches your project's versioning methodology.
 
 <div class="grid cards" markdown>
 
@@ -72,7 +72,7 @@ versioned documentation that matches your project's versioning metholodogy.
 ## Optimization
 
 Add site analytics and build an optimized site by adding automatic image
-compression, complying with GDPR data privacy regulations and make it
+compression, complying with GDPR data privacy regulations, and making it
 offline-capable.
 
 <div class="grid cards" markdown>
@@ -84,7 +84,7 @@ offline-capable.
 
 </div>
 
-  [Site analytics]: site-analytics.md
+  [Site analytics]: setting-up-site-analytics.md
   [Optimized site]: building-an-optimized-site.md
   [Data Privacy]: ensuring-data-privacy.md
   [Offline usage]: building-for-offline-usage.md