diff --git a/.github/ISSUE_TEMPLATE/01-report-a-bug.yml b/.github/ISSUE_TEMPLATE/01-report-a-bug.yml index 6cd2bee3e..f9d126129 100644 --- a/.github/ISSUE_TEMPLATE/01-report-a-bug.yml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml b/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml index 648d5bb98..c62ef41bb 100644 --- a/.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml +++ b/.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: diff --git a/.github/ISSUE_TEMPLATE/03-request-a-change.yml b/.github/ISSUE_TEMPLATE/03-request-a-change.yml index 3fa6a0322..68508c9ff 100644 --- a/.github/ISSUE_TEMPLATE/03-request-a-change.yml +++ b/.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 - that we maintainers can fully understand what change, feature, or + 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) @@ -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 - you, but the community, and how it aligns with the goals and [philopsophy](https://squidfunk.github.io/mkdocs-material/philosophy/) + perspective. Elaborate on how the change would positively impact not only + 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 diff --git a/.github/ISSUE_TEMPLATE/04-add-a-translation.yml b/.github/ISSUE_TEMPLATE/04-add-a-translation.yml index a49acf395..63f32a933 100644 --- a/.github/ISSUE_TEMPLATE/04-add-a-translation.yml +++ b/.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 diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 4c3ed1064..130c02745 100644 --- a/docs/contributing/index.md +++ b/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 -the documentation explains each process. +features or changes, contribute to the project, or exchange with our community. +This section of the documentation explains each process. [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md index acb6a933d..812c98838 100644 --- a/docs/contributing/reporting-a-bug.md +++ b/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 -know to help you. +and have worked to the best of your knowledge to provide us with everything we +need to know to help you. __We'll take it from here.__ diff --git a/docs/contributing/reporting-a-docs-issue.md b/docs/contributing/reporting-a-docs-issue.md index ce6cf853c..ac81d67aa 100644 --- a/docs/contributing/reporting-a-docs-issue.md +++ b/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 -site being this large, inconsistencies can occur. If you found an inconsistency +In the past seven years, our documentation has grown to more than 60 pages. With +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.__ diff --git a/docs/contributing/requesting-a-change.md b/docs/contributing/requesting-a-change.md index cf4ba03f8..25b7e55f0 100644 --- a/docs/contributing/requesting-a-change.md +++ b/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 -you submit a comprehensive and useful issue: +request. The following guide will walk you through all the necessary steps to +help you submit a comprehensive and useful issue: - [Title] - [Context] optional @@ -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 what, not the why__ – 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 -review your idea for Material for MkDocs. +worked to the best of your knowledge to provide us with every piece of +information to review your idea for Material for MkDocs. __We'll take it from here.__