This article describes how to create, move, delete, or edit a page.In all these instances, it's a good idea to check our guidelines forWhat we write to confirm if any of these actions should be taken and discuss it with the team in one of the MDN Web Docscommunication channels before proceeding.

Creating pages

All pages on MDN Web Docs are authored in Markdown format. The content is written in a file namedindex.md, which is stored in its own unique directory. The directory name represents the name of the page. For example, ifalign-content is a new CSS property for which you want to create a new reference page, you'd create a folder inen-us/web/css namedalign-content and create a file calledindex.md inside it.

There are a lot of differentpage types with certain structures and supporting page templates for them, which you can copy to get you started.

A document'sindex.md file must start with front matter that defines thetitle,slug, andpage-type. All of this front matter information can be found in the aforementioned page templates. Alternatively, you might find it helpful to refer to the front matter within a similar document'sindex.md.

The general step-by-step process for creating a page would be:

1. Start a fresh, up-to-date branch to work in.

   bash

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

2. Create one or more new document folders, each with their ownindex.md files.

3. Add and commit your new files as well as push your new branch to your fork.

   bash

   git add files/en-us/folder/you/createdgit commit -m "appropriate message about your changes"git push -u origin my-add

4. Create your pull request.

Moving pages

Moving one or more documents or an entire tree of documents is easybecause 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 liketo move (e.g.,Web/HTTP/Guides/Authentication), as well as the slug of its newlocation (e.g.,Web/HTTP/Guides/Auth), optionally followed by the locale of theexisting document (defaults toen-US).

If the existing document that you'd like to move has child documents (i.e.,it represents a document tree), theyarn content move command will movethe entire tree.

For example, let's say you want to move the entire/en-US/Web/HTTP/Guides/Authentication tree to/en-US/Web/HTTP/Guides/Auth, you'd perform the following steps:

1. You'll start a fresh branch to work in.

   bash

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

2. Perform the move (which will delete and modify existing files as well as create new files).

   bash

   yarn content move Web/HTTP/Guides/Authentication Web/HTTP/Guides/Auth

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. Add and commit all the deleted, created, and modified files as well as push your branch to your fork.

   bash

   git add .git commit -m "Move Web/HTTP/Guides/Authentication to Web/HTTP/Guides/Auth"git push -u origin my-move

5. Create your pull request.

Deleting pages

Documents should only be removed from MDN Web Docs under special circumstances. If you are thinking about deleting pages, please discuss it with the MDN Web Docs team on theMDN Web Docs chat rooms first.

Deleting one or more documents or an entire tree of documents is easy, just like moving pages, because we've created a special command that takes care of thedetails for you:

yarn content delete <document-slug> [locale]

You just have to specify the slug of the existing document that you'd liketo delete (e.g.,Web/HTTP/Guides/Authentication), optionally followed by the localeof the existing document (defaults toen-US).

If the existing document that you'd like to delete has child documents (i.e., it represents adocument tree), you must also specify the-r, --recursive option, otherwisethe command will fail.

For example, if you want to delete theentire/en-US/Web/HTTP/Guides/Authentication tree, you'd perform the following steps:

1. You'll start a fresh branch to work in.

   bash

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

2. Perform the delete.

   bash

   yarn content delete Web/HTTP/Guides/Authentication --recursive

3. Add a redirect. The target page can be an external URL or another page on MDN Web Docs.

   bash

   yarn content add-redirect /en-US/path/of/deleted/page /en-US/path/of/target/page

4. Add and commit all the deleted files as well as push your branch to your fork.

   bash

   git commit -agit push -u origin my-delete

5. Create your pull request.

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

Removing content from MDN Web Docs will inevitably result in updating the existing content as well. As a lot of articles link to others, the removed content will likely be referenced elsewhere. Adding the redirect will mitigate the impact of removing content; however, it's best practice to edit content to reflect the change and include the content edits along with the removal pull request.

Editing existing pages

To edit a page, you need to find the page source in ourcontent repository. The easiest way to find it is to navigate to the page you want to edit, go to the bottom of the page, and click on the "View the source on GitHub" link.

Preview changes

If you are editing the page locally, to see what your changes look like you can go to the content repo folder, execute the CLI commandyarn start, go tolocalhost:5042 in your browser, and navigate to the page and view it. Enter the title in the search box to find it easily. The previewed page will update in the browser as you edit the source.

Attach files

To attach a file to your article, you just need to include it in the same directory as the article'sindex.md file. Include the file in your page, typically via an<a> element.