Good First Contributions

There are lots of ways to contribute to the Astro Docs website!

The Astro Docs website is … an Astro website! Maintaining it requires not only written content but also maintaining Astro code and addressing a11y, CSS, UI, and UX concerns. We also make our documentation available in several languages, so we need help translating the entire site.

We do need and want your help! But, it is important to consider the needs of the project when contributing. Some contributions are difficult to make if you’re unfamiliar with our project. Some contributions are needed more than others, and so even if your contribution may be a good one, we may not have time to review it when other tasks are more urgent.

Types of Contributions

There are many ways to contribute and be helpful to Astro Docs, and they mostly fall into one of these categories:

• Contributing a change to the Astro Docs website by creating a pull request (PR).
• Filing an issue to let us know of something incorrect in our existing documentation.
• Participating in Github Discussions where we evaluate possible docs changes and improvements.
• Leaving comments on existing issues or pull requests to help us verify and evaluate proposed solutions.

Pull Requests (PRs)

We encourage you to make a PR directly for:

• Very obvious documentation fixes like typos or broken links.
• Adding community resources and links to existing sections.
• Instructions that are outdated because a third-party changed something about their process.
• Contributing a solution as described in an existing issue labeled help wanted by a maintainer.
• Creating a page for a new third-party service guide in an existing category (e.g. CMS, Deploy, Backend).
• Translating existing content into one of our currently supported languages.

These types of contributions are helpful because they either fix inaccurate content or add more of our existing, established content. These are good first contributions because they generally do not require any decisions about whether the contribution is appropriate, or how it will fit in with existing docs.

However, pull requests are the most challenging contributions to make. There is a process to follow and you will need to understand how to make changes to our documentation site code, even to fix a typo. You may wish to start with one of the other types of contributions if you are just getting started in open source contributions or learning about Astro docs.

We typically only accept PRs for the above contributions, and do not encourage making a PR for suggested improvements to our documentation. Improvements to the Astro docs can be suggested through GitHub Discussions.

Issues

You can look at our existing issues (especially those labelled help wanted and good first issue) for contributions that we are actively seeking. You do not need to ask permission to work on an issue, and we do not monitor who is working on an issue. Please just make a PR directly if you would like to contribute a solution to the issue.

Note

Do not ask to be “assigned” an issue! Unlike other some projects, Astro docs does not assign issues to contributors. Only Astro maintainers are “assigned” issues. This means that they are taking responsibility for overseeing this issue and any community contributions.

You can also file an issue to let us know of outdated, or incorrect documentation, even without making a PR to attempt to fix anything! Filing an issue to alert us to incorrect content is very helpful, and this provides opportunities for others to contribute by solving the problem.

You can also let us know of any bugs or problems you encounter on the site itself, with or without a proposed solution.

We do not encourage filling a GitHub Issue for suggested improvements to our documentation content or website. Improvements to the Astro docs can be suggested through discussions.

Discussions

For anything that is not an “issue” (e.g. inaccurate content, website bugs), please check our GitHub Discussions to see if there is already a conversation happening. If not, feel free to create a new GitHub Discussion for ideas or thoughts for improvements! If an idea is popular with the community and approved by the team, then we will create a GitHub Issue to indicate that this is a problem we want to tackle.

Most issues begin as discussion threads. GitHub Discussions allows not only conversation, but also voting and ranking of ideas. This is helpful for prioritizing improvements we could choose to make to the docs, and allows us to keep our GitHub Issues as a team inbox for necessary fixes that we know we want to make.

Review comments

You can also make a huge contribution by getting involved and leaving review comments on PRs, adding ideas in existing GitHub Issues and participating in our “Pinned” issue maintenance tasks!

Every PR, especially translation PRs, needs reviewers! Reviewing PRs and leaving comments, suggestions, or an approving “LGTM!” (“Looks Good To Me!”) is a great way to get started on Team Docs, and to learn more about Astro.