diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index cf70d9056aa7898..9511d4b677e99b9 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -184,6 +184,13 @@ "searchPattern": "/- :(\\w)/g", "replace": "- : $1", "skipCode": true + }, + { + "name": "fqdn-moz-links", + "message": "Don't use developer.mozilla.org for links", + "search": "](https://developer.mozilla.org/", + "replace": "](/", + "skipCode": true } ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1b698e2e84cae2..ecbeff6ae2a6f02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,25 +4,25 @@ Thanks for taking the time to contribute to [MDN Web Docs](https://developer.moz This document covers project setup steps along with a set of guidelines for contributing to MDN Web Docs content. Everyone participating in this project is expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). -If you want to jump right in, see [Getting started on MDN](https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started) for an overview of how to join, and the [Contribute page](https://developer.mozilla.org/en-US/docs/MDN/Contribute) on MDN for a filtered list of tasks. +If you want to jump right in, see [Getting started on MDN][] for an overview of how to join, and the [Contribute page][] on MDN for a filtered list of tasks. ## Getting started Before contributing, make sure you're familiar with the project guidelines and conventions: -- [MDN guidelines](https://developer.mozilla.org/en-US/docs/MDN/Guidelines) - This page covers everything from how and what we write to general project guidelines. -- [Writing style guide](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide) - This covers the language and style we use and how we write and format code examples. -- [Guide to writing Markdown for MDN](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN) - Which Markdown features we support and custom extensions we've added. +- [MDN guidelines][] - This page covers everything from how and what we write to general project guidelines. +- [Writing style guide][] - This covers the language and style we use and how we write and format code examples. +- [Guide to writing Markdown for MDN][] - Which Markdown features we support and custom extensions we've added. ### Prerequisite knowledge We expect contributors to MDN to have some knowledge of web technologies before working on content. We've put together relevant resources to get up to speed on specific topics before contributing: -- **Open source:** If you're new to open source projects, see the [open source etiquette](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Open_source_etiquette) page. -- **Git and GitHub:** If you are unfamiliar with these, [GitHub for complete beginners](https://developer.mozilla.org/en-US/docs/MDN/Contribute/GitHub_beginners) is a good primer. -- **Web technologies:** HTML, CSS, JavaScript, and more are covered in our [Learn web development](https://developer.mozilla.org/en-US/docs/Learn) tutorials. -- **MDN repository:** To find out where everything lives, see [Where is everything on MDN?](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Where_is_everything). +- **Open source:** If you're new to open source projects, see the [open source etiquette][] page. +- **Git and GitHub:** If you are unfamiliar with these, [GitHub for complete beginners][] is a good primer. +- **Web technologies:** HTML, CSS, JavaScript, and more are covered in our [Learn web development][] tutorials. +- **MDN repository:** To find out where everything lives, see [Where is everything on MDN?][]. ### Documentation conventions @@ -42,7 +42,7 @@ Each document's `index.md` starts with front-matter, which is written in [YAML]( The YAML is read by the MDN build system and is used to read the metadata of a document. The front-matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines (`---`). -Front-matter defines the document's `title`, `slug`, and optional [`tags`](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Tag). +Front-matter defines the document's `title`, `slug`, and optional [`tags`][]. Here's an example of front-matter from the [JavaScript page](files/en-us/web/javascript/index.md): ```yaml @@ -75,7 +75,7 @@ If you've created a new GitHub account and want to know what to do next, you can ### Simple changes If you want to make a small change like fixing a typo, the GitHub UI is the easiest way to get started. -If you've found a typo on the [JavaScript landing page](https://developer.mozilla.org/en-US/docs/Web/JavaScript), for example, you can propose a fix as follows: +If you've found a typo on the [JavaScript landing page][], for example, you can propose a fix as follows: 1. Sign in to [GitHub](https://github.com/) 2. Navigate to [https://github.com/mdn/content](https://github.com/mdn/content) @@ -226,7 +226,7 @@ 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`). -- A document's `index.md` file must start with front-matter that defines the `title`, `slug`, and optional [`tags`](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Tag). +- A document's `index.md` file must start with front-matter that defines the `title`, `slug`, and optional [`tags`][]. You might find it helpful to refer to the front-matter within a similar document's `index.md`. ### Moving documents @@ -402,3 +402,15 @@ There are some important rules of etiquette to remember that will help during th When contributing to the content you agree to license your contributions according to [our license](LICENSE.md). + +[`tags`]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Tag +[Contribute page]: https://developer.mozilla.org/en-US/docs/MDN/Contribute +[Getting started on MDN]: https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started +[GitHub for complete beginners]: https://developer.mozilla.org/en-US/docs/MDN/Contribute/GitHub_beginners +[Guide to writing Markdown for MDN]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN +[JavaScript landing page]: https://developer.mozilla.org/en-US/docs/Web/JavaScript +[Learn web development]: https://developer.mozilla.org/en-US/docs/Learn +[MDN guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines +[open source etiquette]: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Open_source_etiquette +[Where is everything on MDN?]: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Where_is_everything +[Writing style guide]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide diff --git a/REVIEWING.md b/REVIEWING.md index aa7d497a8f51cf2..28bfee8db5cc09e 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -42,11 +42,11 @@ perfectly in accordance with all of these points immediately. It is more important to make sure the content is readable, useful, correct, and not inappropriate, than it is to follow every guideline to the letter. -1. Familiarize yourself with the [MDN Code example guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) +1. Familiarize yourself with the [MDN Code example guidelines][] and make sure that code examples follow the guidelines. You'll get used to them eventually, and we are intending to automatically lint against our guidelines at some point in the future. -2. Familiarize yourself with the [MDN Writing style guide](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide), +2. Familiarize yourself with the [MDN Writing style guide][], and use it to inform your reviews of new text content. 3. Familiarize yourself with the MDN [pull request guidelines](https://github.com/mdn/content/blob/main/README.md#pull-request-etiquette). The key points here are @@ -134,7 +134,7 @@ then don't review the pull request — just wait for an approval request. The following specific topic areas are being reviewed by the kind souls listed underneath them. Be kind to them, and thank them for all the help they give to this project. If you would like to help with MDN content reviews, -[get in touch with us](https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started#Step_4_Ask_for_help). +[get in touch with us][]. Note that changes to any content areas not explicitly listed below will be handled by the [@core-yari-content](https://github.com/orgs/mdn/teams/core-yari-content) @@ -206,3 +206,7 @@ longer have the time to contribute; we want to give them our sincere thanks for all their help. - [@vkWeb](https://github.com/vkWeb/) + +[get in touch with us]: https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started#Step_4_Ask_for_help +[MDN Code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +[MDN Writing style guide]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md index ef8cbdf5a9ac0f2..6483d40f442ea45 100644 --- a/files/en-us/mdn/community/pull_requests/index.md +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -127,7 +127,7 @@ Don't: ## Deployment timeline -After your pull request is merged to [`mdn/content`](https://github.com/mdn/content), it can take up to 48 hours before your changes are live on the [production site](https://developer.mozilla.org/), but it's usually quicker. +After your pull request is merged to [`mdn/content`](https://github.com/mdn/content), it can take up to 48 hours before your changes are live on the [production site](/), but it's usually quicker. The site build runs every 24 hours at around 19:00 US/Eastern time, and is deployed immediately after. When deploys succeed, it can take up to 24 hours for the CDN to invalidate caches and serve new content. diff --git a/files/en-us/mdn/writing_guidelines/attrib_copyright_license/index.md b/files/en-us/mdn/writing_guidelines/attrib_copyright_license/index.md index cfa861a605828f2..2d0536e60d00098 100644 --- a/files/en-us/mdn/writing_guidelines/attrib_copyright_license/index.md +++ b/files/en-us/mdn/writing_guidelines/attrib_copyright_license/index.md @@ -72,7 +72,7 @@ If someone wants to donate an article to MDN that they previously published on t **If the content is published under an open license:** -- Say what it is, and link to the license so we can check whether it is compatible with [MDN's license](https://developer.mozilla.org/en-US/docs/MDN/About#using_mdn_web_docs_content). +- Say what it is, and link to the license so we can check whether it is compatible with [MDN's license](https://github.com/mdn/content/blob/main/LICENSE.md). ## Linking to MDN Web Docs articles diff --git a/files/en-us/web/html/element/video/index.md b/files/en-us/web/html/element/video/index.md index 91ec7c2b286876f..a3e078717149a25 100644 --- a/files/en-us/web/html/element/video/index.md +++ b/files/en-us/web/html/element/video/index.md @@ -1,5 +1,5 @@ --- -title: '