Contributing to the content of MDN Web Docs

🎉 First of all, thanks for taking the time to contribute to MDN Web Docs! 🎉

The following is a set of guidelines for contributing to the content of MDN Web Docs, which is hosted within the MDN Organization on GitHub.

Note: Just want to find a task and jump in? See Getting started on MDN for an overview of how to join, and Contributing to MDN for a filtered list of tasks.

Code of Conduct

Everyone participating in this project is expected to follow our Code of Conduct.

License

When contributing to the content you agree to license your contributions according to our license.

Making contributions

A good place to learn about general guidelines for contributing to MDN Web Docs is the Guidelines document. For example, you can find out more about MDN's writing-style guidelines via the Writing style guide.

Prerequisite knowledge

We expect contributors to MDN to have a certain amount of prerequisite knowledge before they start working on the content. If you are new to the following topics, we'd advise you to look at the provided links to help you get up to speed:

Web technologies: If you are new to HTML, CSS, JavaScript, etc., check out our Learn web development tutorials.
Open source: If you've never contributed to an open source project before, have a read of Basic etiquette for open source projects.
Git and GitHub: If you are unfamiliar with these tools, GitHub for complete beginners will get you started.
MDN's repo structures: If you are not sure what repos to edit to make changes to the different parts of MDN's content, Where is everything on MDN? will point you towards the correct places.

Setup

No matter how you wish to contribute, you'll need a GitHub account if you don't have one already. If you're not familiar with git and GitHub, you might find the MDN Git and GitHub document helpful.

There are several ways forward from this point. It's up to you. Here are some options:

Go to https://github.com/mdn/content and just use the GitHub UI. This is the easiest approach if you just want to make a simple change to a single file, like fixing a typo.
Install and use the GitHub Desktop
Install and use the GitHub CLI
Install git and use it from the command line. You might find these resources helpful:
- Using Git
- git cheatsheet

If you choose an option other than the GitHub UI, you want to install Node.js (version >=12.11) and yarn.

Fundamental concepts

These are some important things to keep in mind about the MDN content.

A document's main content is written in an index.html or an index.md file -- We're currently in the process of converting our content from HTML into Markdown. Pages that are in HTML have their content in a file called "index.html". Pages that are in Markdown have their content in a file called "index.md".
Documents are folders -- Documents are always represented by a folder (e.g., files/en-us/web/javascript), and that folder will contain the content of that specific document as an index.html or index.md file (e.g., files/en-us/web/javascript/index.md).
Documents are hierarchical - A document folder may contain other folders, where those folders would represent child documents (e.g., files/en-us/web/javascript/closures/index.md).
Document folders may contain image files -- A document folder may also contain image files, which are referenced within that document's index.html or index.md file.
All redirects are specified in a single file -- All of the redirects are specified within files/en-us/_redirects.txt, one redirect per line. Each line specifies a from and to URI separated by whitespace. When you move a document, you'll need to add a redirect to this file specifying that its old URI now redirects to its new URI. Both of these tasks are done using the yarn content move tool — see Moving one or more documents.
Don't edit the _redirects.txt file manually! If both an index.html or index.md file and a redirect exist for a document, the document takes precedence and the redirect is ignored.
A document's index.html or index.md starts with "front-matter" -- Each document's index.html or index.md file must begin with some YAML called front-matter that defines some important information about the document: title, slug, and tags (if any). Here's an example that shows the front-matter from the JavaScript landing page:
```
---
title: JavaScript
slug: Web/JavaScript
tags:
  - JavaScript
  - Landing
  - Landing page
  - Learn
  - 'l10n:priority'
---
```

Simple changes

If you just want to make a simple change to a single file, like fixing a typo, the GitHub UI is the simplest way to do that. For example, if you've found a typo within the JavaScript landing page, you can sign into GitHub, go to https://github.com/mdn/content, navigate to the source file files/en-us/web/javascript/index.md, and then click on the edit (pencil) button.

Tip: Click the Source on GitHub link in the footer of any MDN page to jump to its source file on GitHub.

From there the GitHub UI will take your hand and walk you through the rest, like automatically creating a fork and branch to commit your changes to, as well as helping you reach the ultimate goal, a pull request. Your pull request represents the work you want to be reviewed, hopefully approved, and then merged into the main branch of this repository.

Note: See the pull request etiquette section for more details on creating and handling pull requests successfully.

If you're not certain of the changes that you want to make, get in touch with us first! You can chat with us or file an issue.

You may be asked to further edit files in your pull request. To open a file for editing, select the Files changed tab on the PR, scroll down to the section for the file you want to edit, and then select the "three dots" icon (at the top right of the section). Choose Edit file from the popup menu to start editing the file. After editing, your changes will result in a new commit.

More substantial changes

If you need to do some work that requires changes to more than one file, like moving one or more documents, the GitHub UI is not very efficient. You'd have to make a separate pull request for every page you want to change. Instead, you're going to have to use git or one of the other git-based approaches like the GitHub Desktop.

Pull request etiquette

Here are some important rules of etiquette to remember when working with pull requests.

When you submit a pull request, a number of tests are automatically run as GitHub Actions (see .github/workflows). If one or more of these tests fail, it is your responsibility to try and resolve the underlying issue(s). If you don't know how to resolve the underlying issue(s), you can ask for help. Your pull request will not be approved and merged if these tests are failing.
If your pull request has merge conflicts with the main branch (GitHub checks for this automatically and notifies you), you are responsible for resolving them. You can do this by merging the main branch into your branch (git pull mdn main), and then pushing the updated branch to your fork (git push).
An alternative strategy is git rebase of main on your branch. This will rewrite the git history and might confuse reviewers as notifications from GitHub lead to nowhere. Your changes are replayed on top of the current main branch at that point in time.
Each pull request should contain a single logical change, or related set of changes that make sense to submit together. If a pull request becomes too large or contains too many unrelated changes, it becomes too difficult to review, and may begin to look suspicious (it is easier to hide malicious changes in a large pull request). In such cases, the reviewer has the right to close your pull request, and ask that you submit a separate pull request for each logical set of changes that belong together.
If your pull request contains any kind of significant complexity (it contains technical changes, and isn't just a typo fix, grammatical improvement, or formatting/structural change), please describe why you're making the change and anything else we need to know about it.
- If the pull request is simple (it is really clear what has been changed and why, and the change is obviously a good thing), you can do this in your pull request's description.
- If the pull request is complex (the changes and the reasoning behind them need a bit more explanation), then the requestor should file an issue describing the intended change first, and seek discussion/approval as needed. When the time is right to submit the PR, they should reference the issue (or an existing issue that describes the motivation for the change) in the PR. You can reference an existing issue using # followed by the issue's ID, for example #1234.
- Pull requests should not contain large amounts of grammar updates. Seemingly insignificant changes can change the meaning of technical content, so these need a careful review. Keep in mind that MDN contains technical documentation; you should not report merely basic improvements in the grammar but only cases where the grammar is incorrect.
Do not re-open a pull request that a reviewer has closed.

Adding a new document

Adding a new document is relatively straightforward, especially if you can start by copying the index.html or index.md of a similar document. There are only a few things to keep in mind:

Documents can be authored in either Markdown or HTML. However, we're converting the site to Markdown one section at a time, and don't want to mix authoring formats within a section. At this point we have only converted the JavaScript documentation. So if you are adding a new document under files/en-us/web/javascript, make it a Markdown file. Otherwise make it an HTML file.
Remember that a document is represented by an index.html or index.md file within its own folder.
Determine where in the document hierarchy your document belongs. For example, if you're creating a new CSS document for a new property foo, you'll want to create a new folder files/en-us/web/css/foo/ and its files/en-us/web/css/foo/index.html file.
Remember that a document's index.html or index.md file must start with front-matter that defines the title, slug, and tags (if any) for the document. You might find it helpful to refer to the front-matter within a similar document's index.html or index.md.

As we outlined above, the step-by-step process in general would be:

Start a fresh, up-to-date branch to work within:

cd ~/repos/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
yarn
git checkout -b my-add

Create one or more new document folders, each with their own index.html or index.md file.
Add and commit your new files, as well as push your new branch to your fork:
```
git add files/en-us/folder/you/created
git commit
git push -u origin my-add
```
And finally create your pull request.

Moving one or more documents

Moving one or more documents, or an entire tree of documents is easy, because we've created a special command that takes care of the details for you:

yarn content move <from-slug> <to-slug> [locale]

You just have to specify the slug of the existing document that you'd like to move (e.g., Learn/Accessibility), as well as the slug of its new location (e.g., Learn/A11y), optionally followed by the locale of the existing document (defaults to en-US). If the existing document that you'd like to move has child documents (i.e. it represents a document tree), the yarn content move command will move the entire tree. For example, let's say you want to move the entire /en-US/Learn/Accessibility tree to /en-US/Learn/A11y:

First, as we've outlined above, you'll start a fresh branch to work within:

cd ~/repos/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
yarn
git checkout -b my-move

Perform the move (which will delete and modify existing files, as well as create new files):
```
yarn content move Learn/Accessibility Learn/A11y
```
Add and commit all of the deleted, created, and modified files, as well as push your branch to your fork:
```
git commit -a
git push -u origin my-move
```
Now you're ready to create your pull request.

Important: yarn content move automatically adds the necessary redirect information to the _redirects.txt file so that the old location will redirect to the new one. Don't edit the _redirects.txt file manually! mistakes can easily creep in if you do. If you need to add a redirect without moving a file, talk to us about it.

Deleting a document

Deleting one or more documents, or an entire tree of documents is also easy, again because we've created a special command that takes care of the details for you:

yarn content delete <document-slug> [locale]

You just have to specify the slug of the existing document that you'd like to delete (e.g., Learn/Accessibility), optionally followed by the locale of the existing document (defaults to en-US). If the existing document that you'd like to delete has child documents (i.e. it represents a document tree), you must also specify the -r, --recursive option, or the command will fail.

Important: you need to use the delete command to delete MDN documents. Don't just delete their directories from the repo, as delete also handles other necessary changes such as updating the _wikihistory.json file.

For example, let's say you want to delete the entire /en-US/Learn/Accessibility tree:

First, as we've outlined above, you'll start a fresh branch to work in:

cd ~/repos/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
yarn
git checkout -b my-delete

Perform the delete:

yarn content delete Learn/Accessibility --recursive

Add a redirect (if needed).
Add and commit all of the deleted files, as well as push your branch to your fork:
```
git commit -a
git push -u origin my-delete
```
Now you're ready to create your pull request.

Note: If the slug of the page you wish to delete contain special characters, include it in quotes:

yarn content delete "Mozilla/Add-ons/WebExtensions/Debugging_(before_Firefox_50)"

Redirecting a document

If you are moving a document as shown above you don't need to create a redirect. However, you may need to when deleting a document or otherwise fixing up a broken link.

The best way to do this is to use the yarn content add-redirect command:

Start a fresh branch to work in:

cd ~/repos/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
yarn
git checkout -b my-delete

Perform the redirect:
```
yarn content add-redirect /en-US/path/of/deleted/page /en-US/path/of/target/page
```
Note that the target page can be an external URL or another page.
Commit all of the changed files, as well as pushing your branch to your fork:
```
git commit -a
git push -u origin my-delete
```

Learn more

You can learn more about contributing to MDN on the MDN Web Docs for Contributors site.

License

onlinedeal4unow/content

ErrorLooks like something went wrong!

About

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages