Larger contributions with a fork

Editing a single page on GitHub.com is convenient for small text changes, but does not allow you to see a live preview of the site while you are working. It also does not let you easily edit multiple files at once, such as a guide and a reference page or a sidebar entry.

Contribute PRs using an online code editor

(e.g. StackBlitz, CodeSpaces CodeSandbox, Gitpod)

You can instead open a fork in an online IDE (integrated development environment) for a code editor and live preview without needing to set up any local development environment. Each online IDE has its own shortcut URL for opening an existing repository, and will allow you to create pull requests after you have made changes.

See specific instructions for opening an existing repository in CodeSandbox, StackBlitz, and Gitpod on their respective websites.

Note that CodeSandbox and StackBlitz provide Astro syntax highlighting in their custom code editors, while Gitpod supports the full Astro VSCode extension.

Contribute PRs by Developing Locally

To begin developing locally, checkout this project from your machine.

git clone git@github.com:withastro/docs.git

You can install and run the project locally using pnpm. Head to the pnpm installation guide to get that set up. Then, run the following from your terminal:

pnpm install

pnpm start

If you’re copying these instructions, remember to configure this project as a fork.

git remote add upstream git@github.com:withastro/docs.git

At any point, create a branch for your contribution. We are not strict about branch names.

git checkout -b add/partial-hydration-typo-fix

Helpful information about Forks

On GitHub you’ll need a “fork” of this repository to work on. This is your own copy where you can make changes. Read more about forks in GitHub’s docs.

Not sure how to get started with GitHub, forks, pull requests, or want a quick refresher? You might want to check out this free video series:

How to Contribute to an Open Source Project on GitHub

Creating a fork

To create your copy, click the Fork button at the top right of any page in this repository.

Maintaining a fork

When you first create your fork, it will be an exact copy of this repository. Over time, withastro/docs will change as the docs are updated, but your fork won’t automatically stay up-to-date. Here are some ways to keep your fork in sync with this repo.

Manually via the GitHub UI

1. Navigate to your fork on GitHub

2. Click Sync fork and then Update branch

Manually from the command line

In the terminal on your computer:

1. Make sure you’re on the main branch: git checkout main

2. Fetch and merge updates: git pull upstream main

3. Push the updates back to your fork on GitHub: git push origin main

Automatically with a GitHub app

1. Go to the “Pull” GitHub app page

2. Click Install

3. Follow the instructions to select your fork

Page content source location

The English content of our website is written in .mdx files located within src/content/docs/en/.

Please check the very top of the file as there may be additional instructions specific to that page! For example, the source content for that page may be generated in a different file and you should not make a change directly to this file.

CHANGING EXISTING DOCUMENTATION

All changes to the documentation (rewording existing documentation, adding new sections etc.) occur in English only, by modifying only .mdx files located within src/content/docs/en/. All new or changed content is approved in English first, and then is translated separately.

By default, when you edit an English page, our Translation Tracker updates every other language with a “needs updating” status. Normally, this is what we want! If an explanation has changed, or a code sample has been updated, then the other languages should make the appropriate change, too.

However, if your change is an English-only correction (e.g. a typo fix to an English word) that does not otherwise alter the documentation, then please be sure to title your pull request appropriately when you create a pull request.

Documentation for every other language is located in a separate folder within src/content/docs/. The page content of these documents is never generated from outside sources, and is always changed in these files. To fix a small error in these pages, use the same procedure as editing an English page. However, always keep the content an exact representation of the English docs. Do not revise wording or sections here, and only match the English content.

If editing a translated page makes you notice a problem with the current English documentation, or you would like to suggest an improvement, please file an issue and let us know! Our translators often spot things that could be better in our docs, and we appreciate the help!

See our i18n guide for translators for more information about translating the docs!

Pages generated from outside sources

Some of our English-language pages are generated from outside sources and maintained in another repo. Currently, these files are configuration-reference.md and all of our error messages.

Note

All of these English generated pages in the docs repo will have a dev-only warning at the top and the githubURLfrontmatter property. Please do look at the top of the file before you make changes and submit a pull request, as there are additional instructions there when necessary.

Translated pages are always edited directly in the docs repo.

Creating a pull request

1. Choose a title that is short, but descriptive of your change. If your change does not require translating or a similar update to the other language pages (e.g. fixing an English typo), please include [i18nIgnore] in your subject. If you are translating a non-English page, please indicate the language in the subject. For example, to propose an edit to a French page, include i18n(fr) in the PR title.

2. Choose and fill out the appropriate template. Be sure to include any useful information or extra content, such as a linked Issue.

3. Submit your changes for review.

Every pull request needs to be reviewed by our contributors and approved by a maintainer.

The docs site will be automatically updated whenever pull requests are merged.