Everyone participating in this project is expected to follow our [Code of Conduct](https://github.com/mdn/content/blob/main/CODE_OF_CONDUCT.md), which means adhering to [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/).
There are a few things to keep in mind about content on MDN and how it is maintained:
- A document's content is written in an `index.md` file.
- A document's `index.md` starts with "front-matter" described in [Front-matter](#front-matter).
- Documents have corresponding folders (the JavaScript page's `index.md` is in [`files/en-us/web/javascript`](files/en-us/web/javascript), for example).
- Document folders may contain images referenced by the `index.md` file in that folder.
- A document folder may contain child folders with child documents (e.g., [`files/en-us/web/javascript/reference/index.md`](files/en-us/web/javascript/reference/index.md)).
The [`git` cheat sheet](https://training.github.com/) and [Using Git](https://docs.github.com/en/get-started) guide are useful resources for beginners and advanced users.
From there, the GitHub UI will walk you through the rest by creating a [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and a branch to commit your changes to.
After you have made changes to your branch, open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) with your changes to be incorporated.
If you want to make changes to more than one file, the GitHub UI is not very efficient because you have to make separate pull requests for each file you want to change.
Instead of using the GitHub UI, you need to use `git` or a client like the [GitHub Desktop](https://docs.github.com/en/get-started/using-github/github-desktop) or [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli).
The following examples are using plain `git` commands, but you can use any of the clients mentioned above to perform the equivalent actions.
To fork and clone the repository:
1. [Create a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the `mdn/content` repository to freely experiment with branches and changes.
Assuming your GitHub username is `octocat`, your fork would be a copy of the `mdn/content` repository in your account at `https://github.com/octocat/content`.
Assuming your GitHub username is `octocat`, you would do something like this:
```bash
# starting in a directory of your choice
cd ~/repos
# clone your fork of the repository
git clone git@github.com:octocat/content.git
```
3. [Create a `remote`](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to keep your clone and fork (`https://github.com/octocat/content`) up-to-date.
This example adds a remote named `upstream`, but you can name it `mdn` or any other name you like.
When you run `git remote -v`, you'll see that you have two remotes: `upstream` and `origin`.
The `origin` remote is your fork (`https://github.com/octocat/content`) and the `upstream` remote is the `mdn/content` repository.
4. Keep your fork up-to-date often.
You can do this by fetching the latest changes from the `mdn/content` repository and merging them into your fork.
```bash
cd ~/repos/content
# checkout your local clone's main branch
git checkout main
git fetch upstream
# merge the latest content from the main branch of the mdn repository
git merge upstream/main
```
5. Create a branch for your changes.
This example creates a branch named `fix-typo`:
```bash
cd ~/repos/content
# checkout your local clone's main branch
git checkout main
# create a new branch named fix-typo
git checkout -b fix-typo
```
## Contributing to MDN
The previous sections describe how to get started using the GitHub UI to make small changes to a single file and how to create a fork and clone the repository to prepare for making larger changes.
This section describes how to build the project locally and how to prepare your changes for submission.
If you changed `files/en-us/web/javascript/index.md`, you would navigate to `http://localhost:5042/en-US/docs/Web/JavaScript` in your browser, for example.
To ensure that all MDN documents follow the same formatting, we use both [Prettier](https://prettier.io/) and [MarkdownLint](https://github.com/DavidAnson/markdownlint) to format and lint Markdown files. This helps us enforce uniform styling across all documents with minimal reviewer intervention.
If you have a [local checkout](#forking-and-cloning-the-repository) of the repository and have [installed the dependencies](#preparing-the-project), or you are using [github.dev](https://github.dev/), a pre-commit hook will be installed which automatically runs while making a commit. To save some headache and improve your work flow while authoring, you may wish to [configure your editor to automatically run Prettier](https://prettier.io/docs/editors.html). Alternatively, you may run `npm run fix:md` in the command line to manually format all Markdown files.
> Automatically formatting changes does not work for pull requests opened using the GitHub Web UI as described in the ["Simple changes" section](#simple-changes).
Adding a new document is relatively straightforward, especially if you can start by copying the `index.md` of a similar document.
There are a few things to keep in mind:
- Documents must be written in Markdown.
- A document is represented by an `index.md` file.
- If you're creating a new CSS document for a property called `foo`, create a new folder `files/en-us/web/css/foo/` and put the Markdown file in this folder (`files/en-us/web/css/foo/index.md`).
To use `npm run content move`, provide the slug of the document you'd like to move (e.g., `Learn/Accessibility`), and the slug of its new location (e.g., `Learn/A11y`).
If the document you'd like to move contains child documents (i.e., it represents a document tree), the `npm run content move` command will move the entire tree.
3. Once files are moved we need to update references to those files in the other content files as well. Use following command to update all the references automatically in one go:
```bash
node scripts/update-moved-file-links.js
```
4. Commit all the changes and push your branch to the remote:
> Don't delete files or directories from the repository manually; the `npm run content delete` command handles the necessary changes such as updating the `_wikihistory.json` file.
To use `npm run content delete`, provide the slug of the document you'd like to delete (e.g., `Learn/Accessibility`), and the locale as an optional second argument (this defaults to `en-US`).
If the document has child documents (i.e., the document represents a document tree), you must specify the `-r, --recursive` option, else the command will fail.
Say you want to delete the entire `/en-US/Learn/Accessibility` tree and redirect all the deleted documents to `Web/Accessibility`. You can perform the following steps:
git commit -m "Adding redirect after deleting Learn/Accessibility pages"
git push
# or git push --set-upstream origin deleting-a11y
```
### Creating a pull request
Once you've made your changes and pushed them to a branch on your fork, you can [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to propose your changes to the `mdn/content` repository.
Someone from the MDN team or the MDN Web Docs community will review your changes and provide feedback.
For details on what to do next, see the [pull request etiquette section](#pull-request-etiquette) to see how to handle pull requests and get your content merged successfully.
#### Pull request etiquette
This is the exciting part of contributing to MDN as you're almost done with the contribution process!
Here are some things to keep in mind at this point:
- Your pull request must be **reviewed and approved** before it's merged into the `main` branch.
- **You do not need to request a review**; one or more reviewers will be selected for you automatically.
If one or more of these tests fail, you must fix them.
Your pull request will not be approved and merged if there are failing tests.
If you don't know how to resolve the underlying issue(s), you can ask for help.
2. **Resolve conflicts** if your pull request has merge conflicts with the `main` branch.
This is usually done by merging the `main` branch into your feature branch (`git pull upstream main`), and then pushing the updated branch to your fork (`git push`).
3. **Group logical changes** in each pull request so that it contains a single change or a related set of changes.
If a pull request becomes too large or contains too many unrelated changes, a reviewer may close your pull request and ask you to submit a new pull request for each set of changes.
4. **Don't re-open pull requests** closed by a reviewer.
5. **Don't use `git rebase`** of `main` over your branch.
Your changes are replayed on top of the current main branch at that point in time.
This might confuse reviewers as notifications on GitHub lead to nowhere.
## License
When contributing to the content you agree to license your contributions
