Merge pull request #5320 from squidfunk/docs/guides

Updated guides

Author: squidfunk

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

@@ -51,7 +51,7 @@ body:
       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 the community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+        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:

.github/ISSUE_TEMPLATE/04-add-a-translation.yml renamed to .github/ISSUE_TEMPLATE/04-add-translations.yml

@@ -7,17 +7,21 @@ body:
 
   - type: markdown
     attributes:
-      value: >-
-        **Important**: Before creating a new translation, please make sure that
-        Material for MkDocs does not already include support for your language.
-        Please check the list of all [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language)
-        and help us by adding missing translations.
+      value: |-
+        **Important**: Before creating a new translation, please check if
+        Material for MkDocs already supports your language. Review the list of
+        [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
+        pick your language to add new or improve existing translations.
 
   - type: textarea
     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. For new languages, translate
+        each line. For existing languages, only translate lines containing the
+        icon :arrow_left: and remove the icon before submitting.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-a-translation/#translations)
       value: |-
         {% macro t(key) %}{{ {
           "language": "en",
@@ -76,13 +80,25 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: country-flag
+    attributes:
+      label: Country flag icon
+      description: >-
+        Please add the flag of the country when adding a new language. Select
+        it on our [Icons, Emojis site](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
+        by entering `flag` in the search field. If your flag is not provided by
+        Twemoji, please choose the closest matching flag.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-a-translation/#country-flag)
+      placeholder: |-
+        Post the flag of the country here.
+
   - type: checkboxes
     id: checklist
     attributes:
       label: Before submitting
       description: >-
-        Please ensure that your translation fulfills the following
-        requirements.
+        Please ensure that your translation fulfills the following requirements.
       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
@@ -91,4 +107,3 @@ body:
         - label: >-
             __Optional__: I want to integrate this translation myself and create a
             pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
-

.github/ISSUE_TEMPLATE/config.yml

@@ -22,4 +22,6 @@ blank_issues_enabled: false
 contact_links:
   - name: Ask a question
     url: https://github.com/squidfunk/mkdocs-material/discussions
-    about: Have a question or need help? Connect with the community on our discussion board
+    about: >
+      Have a question or need help? Connect with our community on the
+      discussion board

CODE_OF_CONDUCT.md

@@ -5,7 +5,7 @@
 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, 
+size, disability, ethnicity, gender identity and expression, level of experience,
 nationality, personal appearance, race, religion, or sexual identity and
 orientation.
 
@@ -16,7 +16,7 @@ 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
+* Focusing on what is best for our community
 * Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
@@ -36,7 +36,7 @@ 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 
+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,
@@ -45,21 +45,21 @@ 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 
+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 
+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.
+reported by contacting the project team privately at [email protected]. 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

CONTRIBUTING.md

@@ -1,112 +1,61 @@
 # Contributing
 
-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].
-
-  [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] in our GitHub repository. Even better, you can submit
-a Pull Request with a fix. However, before doing so, please read the
-[submission guidelines].
-
+Material for MkDocs is an actively maintained and constantly improved project
+that serves a diverse user base with varying backgrounds and needs. In order to
+effectively address the needs of all our users, evaluate change requests, and
+fix bugs, we maintainers need to put in a lot of work. We have devoted
+significant effort to 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.
+
+Given the wealth of valuable knowledge contained in numerous issues and
+discussions, we consider our [issue tracker] and [discussion board] to serve as
+a crucial __knowledge base__ that is an important addition to our [documentation]
+and brings value to both new and experienced users of Material for MkDocs.
+
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
   [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 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
-  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
-  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 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.
+  [documentation]: https://squidfunk.github.io/mkdocs-material/
 
-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:
+## How to contribute
 
-    - `search.config.lang`
-    - `search.config.pipeline`
-    - `search.config.separator`
+### Creating an issue
 
-3.  Create a PR (see below) with your changes.
+-   #### [Report a bug]
 
-  [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
+    __Something is not working?__ Report a bug in Material for MkDocs by
+    creating an issue with a reproduction
 
-## Submission guidelines
+-   #### [Report a docs issue]
 
-### Submitting an issue
+    __Missing information in our docs?__ Report missing information or
+    potential inconsistencies in our documentation
 
-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
-readily available.
+-   #### [Request a change]
 
-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.
+    __Want to submit an idea?__ Propose a change, feature request, or
+    suggest an improvement
 
-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.
+-   #### [Ask a question]
 
-### Submitting a Pull Request (PR)
+    __Have a question or need help?__ Ask a question on our [discussion board]
+    and get in touch with our community
 
-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.
+### Contributing
 
-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.
+-   #### [Add a translation]
 
-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.
+    __Missing support for your language?__ Add missing translations for a new
+    or already supported language
 
-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.
+-   #### [Create a pull request]
 
-After your PR is merged, you can safely delete your branch and pull the changes
-from the main (upstream) repository.
+    __Want to create a pull request?__ Learn how to create a comprehensive
+    and useful pull request (PR)s
 
-  [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
-  [build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme
+  [Report a bug]: reporting-a-bug.md
+  [Report a docs issue]: reporting-a-docs-issue.md
+  [Request a change]: requesting-a-change.md
+  [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+  [Add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
+  [Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls

README.md

@@ -17,19 +17,15 @@
     alt="Build"
   /></a>
   <a href="https://pypistats.org/packages/mkdocs-material"><img
-    src="https://img.shields.io/pypi/dm/mkdocs-material.svg" 
+    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" 
+  <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" 
+  <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>
@@ -48,7 +44,7 @@
 
 <p align="center">
   <em>
-    Check out the demo – 
+    Check out the demo –
     <a
       href="https://squidfunk.github.io/mkdocs-material/"
     >squidfunk.github.io/mkdocs-material</a>.