OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
squidfunk 2023-04-17 11:25:53 +02:00
commit b5ffb1916c
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
9 changed files with 45 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/ISSUE_TEMPLATE/01-report-a-bug.yml vendored
View File

@ -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

2
.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml vendored
View File

@ -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:

14
.github/ISSUE_TEMPLATE/03-request-a-change.yml vendored
View File

@ -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

4
.github/ISSUE_TEMPLATE/04-add-a-translation.yml vendored
View File

@ -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

4
docs/contributing/index.md
View File

@ -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

18
docs/contributing/reporting-a-bug.md
View File

@ -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.__

10
docs/contributing/reporting-a-docs-issue.md
View File

@ -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.__

22
docs/contributing/requesting-a-change.md
View File

@ -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] <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
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.__

12
docs/setup/index.md
View File

@ -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
versioned documentation that matches your project's versioning metholodogy.
Create a blog, integrate a comment system, connect a git repository, and set up
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