Skip to content
Astro Docs Docs (AD²)

GitHub Issues

You can file an new issue to let us know of outdated, confusing, or incorrect documentation without attempting to fix anything. You can also let us know of any problems you encounter on the site itself.

You can also choose to work on an existing issue that has been triaged and has the “help wanted” label.

These issues are separate from Astro core issues and are only read and managed by Docs Maintainers. Issues must be about problems or suggestions for the documentation site only and not feature requests, feedback about Astro itself, or requests for support.

We decide to add new content and rework existing content in response to GitHub Issues, so submitting an Issue is usually the first step to making a change. After an Issue has been considered by the community, we often reach out to community members to encourage them to submit PRs based on existing Issues.

Larger contributions to the docs are encouraged only after participating in Issues, as unsolicited material may not fit into our existing plans.

Examples of Helpful GitHub New Issues

  • a particular explanation is confusing (with explanation)
  • a code example is wrong (with or without a proposed fix)
  • accessibility (a11y) issues discovered
  • missing content
  • a request for an example of how to implement a specific feature (e.g. responsive nav bar)

Writing an Issue

Helpful issues usually include:

  • Clear descriptive titles
  • Links to relevant pages/files
  • Explanations as to why (or for whom) this is a problem
  • Optional: proposed solutions

How to file an issue

  1. Visit the new issue page and choose the appropriate kind of issue you want to file.

  2. Fill out the template, providing all the requested information.

  3. Wait! 😅 A maintainer will “triage” your issue by assigning it a label. They may or may not leave a comment at this time. This doesn’t mean anything is wrong. It probably means that a maintainer does not have time to consider your issue at this time, and is only checking for the kind of issue you submitted, or determining which maintainer will be responsible for the issue.

  4. A maintainer may also “assign” an issue to themselves or another maintainer. Assigning an issue means choosing which maintainer is ultimately responsible for overseeing the issue, guiding the discussion, and making the final decision about whether or not to ask for a community contribution or whether to close it. It does not mean that they are working on a solution themselves.

  5. Feel free to ask other members of the community (in Discord, on social media, etc.) to comment on your issue. Commenting on issues helps us understand the nature of the problem, how many people are experiencing or feel the same, and gives us more perspectives as we consider the issue. (While you are waiting for comments on your issue, consider commenting on other issues, too!)

  6. If you indicated that you were willing to make a PR with a solution to the issue, wait for approval from a maintainer. Then, create a pull request by editing a single page for a smaller contribution or by using one of the methods suggested for making a larger contributions.

How to help with existing issues

Docs issues will be triaged by a maintainer who will add one or more labels to an issue. These labels will indicate the type of issue (e.g. new content, site infrastructure) and may also include labels to describe the issue in other ways (e.g. priority, difficulty, community invovlement wanted).

Issues not labeled “help wanted”

tl/dr: Comment and discuss, but do not work on these!

These have not yet been approved by a maintainer. Our maintainers may have not yet decided whether this is a valid issue. Or, maintainers may already know that an issue will be fixed by some upcoming planned work. It is not appropriate to start working on a solution to this issue. But it is helpful to comment on this issue, letting maintainers know if this is an issue you also have or agree with.

If you see an issue that interests you and that you could fix, but it is not labeled “help wanted”, then you are welcome to commment in the issue! Tell us that you think you have a way to address it, and that you’d be willing to work on it! The maintainers will provide feedback in the issue, and will let you know whether they’d like you to work on a solution.

You are always welcome and encouraged to comment on any existing issue to help the maintainers evaluate it, and provide any extra context or information you have!

Note: authors may add labels to their own issues, but this does not mean the issue has been triaged by a maintainer. Just because an issue has a label does not mean the issue is approved for working on it.

Triaged issues with the “help wanted” label

tl/dr: If you see “help wanted”, go right ahead!

If an issue has been triaged and a maintainer has added the “help wanted” label then it has been acknowledged as an issue we’d like help fixing! We would love it if you would work on these issues, implementing a solution as described in the issue!

You do not require permission to work on a “help wanted” issue. If you would like to work on one of these issues, please leave a comment saying that you are working on it to let other community contributors know.

We do not assign issues to community contributors. In some cases, issues may be assigned to a maintainer to let the community know which maintainer they should ask for any help or clarification on this issue, not to indicate who is actually working on it.