From 75767ee17cb5d731148a353be70fc13a7b0c6310 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Wed, 12 Oct 2022 14:04:15 +0200 Subject: [PATCH] Remove meta site (#20775) * docs(contributing): details about adding images to video guide * docs(contributing): details about code examples * docs(contributing): add browser-compat-data guide * docs(contributing): add deployment timeline guide * docs(contributing): add external files doc * docs(contributing): add content reuse policy * docs(contributing): add prio list * chore(meta): Delete meta site * chore(URLs): fix URLs to use root-relative format * chore(docs): use md instead of HTML * chore(docs): use slug of previous content * chore(docs): Documentation priorities * chore(docs): Documentation priorities * chore(docs): rename dir to documentation_priorities * chore(docs): remove Netlify.toml config * Apply suggestions from code review Co-authored-by: Dipika Bhattacharya * chore(docs): changes following reviewer feedback * chore(docs): remove redundant code examples page * chore(docs): remove redundant BCD page * chore(docs): merge content reuse notes with attrib page * Update files/en-us/mdn/community/pull_requests/index.md Co-authored-by: Nick Schonning * chore(docs): BCD data page cleanup and reference BCD repo contributing guide * chore(docs) remove docs priorities document * docs(conbtrib): improvements on deploy times for related repos * docs(conbtrib): remove references to unvetted tools * chore(docs) remove external-content.md Co-authored-by: Dipika Bhattacharya Co-authored-by: Nick Schonning --- files/en-us/_redirects.txt | 1 - .../community/issues/issue_triage/index.md | 4 +- .../mdn/community/pull_requests/index.md | 11 +- files/en-us/mdn/contribute/index.md | 8 +- .../attrib_copyright_license/index.md | 28 +- .../howto/images_media/index.md | 69 +- files/en-us/mdn/writing_guidelines/index.md | 5 + .../compatibility_tables/index.md | 472 +---- .../page_structures/index.md | 3 +- meta/.gitignore | 4 - meta/README.md | 26 - meta/config.toml | 93 - meta/content/en/_index.md | 17 - meta/content/en/changelog.md | 9 - meta/content/en/community/_index.md | 10 - meta/content/en/community/etiquette.md | 10 - meta/content/en/community/fora.md | 12 - meta/content/en/community/people.md | 12 - meta/content/en/community/report-cpg-spam.md | 12 - meta/content/en/get-started/_index.md | 8 - .../en/get-started/ways-to-contribute.md | 25 - meta/content/en/get-started/why.md | 10 - meta/content/en/governance/_index.md | 10 - .../en/governance/browser-compatability.md | 73 - meta/content/en/governance/issues/_index.md | 10 - meta/content/en/governance/issues/triage.md | 40 - meta/content/en/governance/meetings.md | 10 - meta/content/en/governance/pulls/_index.md | 10 - meta/content/en/governance/pulls/review.md | 10 - meta/content/en/governance/roadmap.md | 10 - .../governance/roles-and-responsibilities.md | 10 - meta/content/en/legacy/_index.md | 6 - meta/content/en/legacy/adding-images.md | 79 - meta/content/en/legacy/archiving.md | 38 - meta/content/en/legacy/code-examples.md | 31 - meta/content/en/legacy/compat-tables.md | 16 - meta/content/en/legacy/deployment-timeline.md | 20 - .../en/legacy/documentation-priorities.md | 172 -- meta/content/en/legacy/external-content.md | 25 - meta/content/en/legacy/reuse.md | 32 - meta/content/en/related/_index.md | 6 - .../content/en/related/browser-compat-data.md | 5 - meta/content/en/related/repositories.md | 6 - meta/content/en/related/specifications.md | 5 - meta/content/en/related/yari.md | 5 - meta/content/en/writing/_index.md | 10 - meta/content/en/writing/browser-compat.md | 11 - meta/content/en/writing/deployment.md | 11 - .../en/writing/interactive-examples.md | 10 - meta/content/en/writing/markdown/_index.md | 10 - meta/content/en/writing/markdown/code.md | 10 - .../en/writing/markdown/frontmatter.md | 10 - .../en/writing/markdown/live-samples.md | 10 - meta/content/en/writing/markdown/macros.md | 10 - meta/content/en/writing/page-types.md | 10 - meta/content/en/writing/style/_index.md | 6 - .../en/writing/style/external-links.md | 64 - meta/netlify.toml | 7 - meta/package.json | 18 - meta/themes/docsy | 1 - meta/yarn.lock | 1533 ----------------- netlify.toml | 4 - 62 files changed, 117 insertions(+), 3096 deletions(-) delete mode 100644 meta/.gitignore delete mode 100644 meta/README.md delete mode 100644 meta/config.toml delete mode 100755 meta/content/en/_index.md delete mode 100644 meta/content/en/changelog.md delete mode 100644 meta/content/en/community/_index.md delete mode 100644 meta/content/en/community/etiquette.md delete mode 100644 meta/content/en/community/fora.md delete mode 100644 meta/content/en/community/people.md delete mode 100644 meta/content/en/community/report-cpg-spam.md delete mode 100644 meta/content/en/get-started/_index.md delete mode 100644 meta/content/en/get-started/ways-to-contribute.md delete mode 100644 meta/content/en/get-started/why.md delete mode 100644 meta/content/en/governance/_index.md delete mode 100644 meta/content/en/governance/browser-compatability.md delete mode 100644 meta/content/en/governance/issues/_index.md delete mode 100644 meta/content/en/governance/issues/triage.md delete mode 100644 meta/content/en/governance/meetings.md delete mode 100644 meta/content/en/governance/pulls/_index.md delete mode 100644 meta/content/en/governance/pulls/review.md delete mode 100644 meta/content/en/governance/roadmap.md delete mode 100644 meta/content/en/governance/roles-and-responsibilities.md delete mode 100644 meta/content/en/legacy/_index.md delete mode 100644 meta/content/en/legacy/adding-images.md delete mode 100644 meta/content/en/legacy/archiving.md delete mode 100644 meta/content/en/legacy/code-examples.md delete mode 100644 meta/content/en/legacy/compat-tables.md delete mode 100644 meta/content/en/legacy/deployment-timeline.md delete mode 100644 meta/content/en/legacy/documentation-priorities.md delete mode 100644 meta/content/en/legacy/external-content.md delete mode 100644 meta/content/en/legacy/reuse.md delete mode 100644 meta/content/en/related/_index.md delete mode 100644 meta/content/en/related/browser-compat-data.md delete mode 100644 meta/content/en/related/repositories.md delete mode 100644 meta/content/en/related/specifications.md delete mode 100644 meta/content/en/related/yari.md delete mode 100644 meta/content/en/writing/_index.md delete mode 100644 meta/content/en/writing/browser-compat.md delete mode 100644 meta/content/en/writing/deployment.md delete mode 100644 meta/content/en/writing/interactive-examples.md delete mode 100644 meta/content/en/writing/markdown/_index.md delete mode 100644 meta/content/en/writing/markdown/code.md delete mode 100644 meta/content/en/writing/markdown/frontmatter.md delete mode 100644 meta/content/en/writing/markdown/live-samples.md delete mode 100644 meta/content/en/writing/markdown/macros.md delete mode 100644 meta/content/en/writing/page-types.md delete mode 100644 meta/content/en/writing/style/_index.md delete mode 100644 meta/content/en/writing/style/external-links.md delete mode 100644 meta/netlify.toml delete mode 100644 meta/package.json delete mode 160000 meta/themes/docsy delete mode 100644 meta/yarn.lock delete mode 100644 netlify.toml diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 474d6182d558bbe..a4698080cd46238 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -5407,7 +5407,6 @@ /en-US/docs/MDN/Contribute/Content/Specification_tables /en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables /en-US/docs/MDN/Contribute/Content/Style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide /en-US/docs/MDN/Contribute/Creating_and_editing_pages /en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting -/en-US/docs/MDN/Contribute/Documentation_priorities https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/ /en-US/docs/MDN/Contribute/Does_this_belong /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Editor/Live_samples /en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples /en-US/docs/MDN/Contribute/FAQ /en-US/docs/MDN/Contribute diff --git a/files/en-us/mdn/community/issues/issue_triage/index.md b/files/en-us/mdn/community/issues/issue_triage/index.md index 9c41bfe05fc6fe6..23819f83e8b7fb9 100644 --- a/files/en-us/mdn/community/issues/issue_triage/index.md +++ b/files/en-us/mdn/community/issues/issue_triage/index.md @@ -103,9 +103,7 @@ Definitions: - Major issue — Something that could severely affect a page's usefulness, for example a significant amount of out-of-date information, a complex and important code example that doesn't work, a significant amount of prose that is badly written and hard to understand, a large number of broken links, etc. - Minor issue — something that doesn't look great but does not affect learning, or only has a minor effect on learning. Examples — Typos, bad grammar, a broken link, a small amount of out-of-date information or badly-written prose, a small code snippet that doesn't work. -Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. And Tier 1 issues are more important than Tier 2 issues. Folks that are interested in tackling the highest priority MDN issues should always tackle Tier 0 issues if any are available, before moving on to Tier 1 then Tier 2 issues. - -> **Note:** For definitions of Tier 1 and Tier 2, see the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/). +Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. ### Provide further information diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md index 4167a1720a9abd8..ef8cbdf5a9ac0f2 100644 --- a/files/en-us/mdn/community/pull_requests/index.md +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -125,10 +125,11 @@ Don't: - Try to cram multiple fixes into a single pull request. It makes it a lot harder to review, and raises suspicions (some people might think you are trying to hide some malicious code in between the valid changes). -## Opening a pull request +## Deployment timeline -## Reviewing a pull request +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. +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. -## Pull requests we accept - -## Idle pull requests +For embedded browser compatibility data tables, the [browser-compat-data](https://github.com/mdn/browser-compat-data) project is built and deployed every Tuesday. +You can expect to see merged changes on MDN Web Docs the following Wednesday. diff --git a/files/en-us/mdn/contribute/index.md b/files/en-us/mdn/contribute/index.md index 223f984684c69ba..353247cbe8e62ff 100644 --- a/files/en-us/mdn/contribute/index.md +++ b/files/en-us/mdn/contribute/index.md @@ -123,15 +123,9 @@ The links in this section lead to detailed guides explaining how to do a particu We will add more tasks here as time goes on. -#### Priority ratings - -You can also look at priority ratings to give you an idea of what the most important work is to work on — we've started giving content bug issues labels of P0, P1, P2, P3, and P4 to signify how important they are, with lower numbers being more important than higher numbers. - -These are figured out during the regular MDN bug triage process, based on the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/). - ### Other task types -If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skillset. +If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skill set. If you are more interested in words, you could do the following: 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 376322e2f24c6e2..cfa861a605828f2 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 @@ -49,16 +49,30 @@ The rights in the logos, trademarks, and service marks of the Mozilla Foundation ## Using content from elsewhere on MDN Web Docs -Often, there is useful content about a topic somewhere on the web besides MDN Web Docs. However, copying such content can be fraught with difficulties, both technical and legal. +In general, we do not approve of copying content from other sources and putting it on MDN. +MDN should be made up of original content wherever possible. +If we receive a pull request and discover that it contains plagiarized content, we will close it and request that the submitter resubmit the change with the content rewritten into their own words. -On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere. -Therefore, it is preferable to have original content on MDN Web Docs to enhance the search engine ranking of MDN Web Docs' content. -You can link to the existing content from MDN Web Docs. +### If you want to reuse or republish content -On the legal level, you must be authorized to contribute the content, and it must be licensed and attributed in a way that is compatible with MDN's license. +> **Note:** Unless there is a good reason to republish the content, we will probably say "no". +> The MDN writing team's decision is final. -- **If you created the existing content** (for your own purposes and not as work-for-hire), and you are willing to contribute it to MDN Web Docs under MDN's license, this is the easiest case. You are free to contribute the content. -- **If the copyright for the content belongs to someone else**, it must be licensed and attributed compatibly with MDN's license. It is often not easy for someone who is not a lawyer to determine what licenses are compatible. To be on the safe side, contact a member of the [MDN Web Docs team](https://github.com/mdn/mdn-community/discussions), who may consult Mozilla's Legal team for guidance if necessary. +If someone wants to donate an article to MDN that they previously published on their blog or it makes sense to copy a complex reference sheet to MDN, there may be justification for republishing it. For these cases, discuss your plan with the MDN team beforehand: + +- [Create a GitHub issue](https://github.com/mdn/mdn/issues/new/choose) that explains your intention. + - Describe what you would like to copy or republish. + - Provide a URL to the resource. + - Explain why you think it's appropriate. + +**If the content is published under a closed license:** + +- If you hold the rights to the content, state this and your express agreement to republish it on MDN. +- If you do not hold the rights to the content, include the author/publisher on the issue if possible, or include details of how they could be contacted so we can ask them for permission to republish the content. + +**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). ## Linking to MDN Web Docs articles diff --git a/files/en-us/mdn/writing_guidelines/howto/images_media/index.md b/files/en-us/mdn/writing_guidelines/howto/images_media/index.md index 3a51db19fa92c96..29c09e175414025 100644 --- a/files/en-us/mdn/writing_guidelines/howto/images_media/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/images_media/index.md @@ -9,11 +9,76 @@ page-type: mdn-writing-guide {{MDNSidebar}} +## Adding images + +To add an image to a document, add your image file to the document's folder, and then reference the image from within the document's `index.md` file using an `` element or [the equivalent Markdown syntax](https://github.github.com/gfm/#images). + +Let's walk through an example: + +1. Start with a fresh working branch with the latest content from the `main` branch of the `mdn` remote. + + ```sh + cd ~/path/to/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-images + ``` + +2. Add your image to the document folder. For this example, let's assume + we're adding a new image to the `files/en-us/web/css` document. + + ```sh + cd ~/path/to/mdn/content + cp ../some/path/my-cool-image.png files/en-us/web/css/ + ``` + +3. Run `filecheck` on each image, which might complain if something's wrong. + For more details, see the [Compressing images](#compressing-images) section. + + ```sh + yarn filecheck files/en-us/web/css/my-cool-image.png + ``` + +4. Reference your image in the document with an `` element inside `files/en-us/web/css/index.md`: + + ```html + My cool image + ``` + +5. Add and commit all of the deleted, created, and modified files, as well as + push your branch to your fork: + + ```sh + git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html + git commit + git push -u origin my-images + ``` + +6. Now you're ready to create your + [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). + +## Compressing images + +When you add images to a page on MDN Web Docs, you should make sure that they are compressed as much as possible (without degrading quality) to save on the download size for our readers. +In fact, if you don't do this, our CI process will fail and the build results will warn you that some of your images are too big. + +The best way to compress the images is by using the built-in compression tool. +You can compress an image appropriately by using the `filecheck` command with the `--save-compression` option. +This option compresses the image as much as possible and replaces the original with the compressed version. +For example: + +```sh +yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression +``` + +## Adding videos + MDN Web Docs is not a very video-heavy site, but there are certain places where video content makes sense to use as part of an article. This article discusses when including videos in articles is appropriate and provides tips on how to create simple but effective videos on a budget. -## Using video content - There are several arguments against using video content for technical documentation, particularly for reference material and advanced level guides. Some of these are listed below: - Video is linear. diff --git a/files/en-us/mdn/writing_guidelines/index.md b/files/en-us/mdn/writing_guidelines/index.md index 82be32cccbed292..985167f12c5f668 100644 --- a/files/en-us/mdn/writing_guidelines/index.md +++ b/files/en-us/mdn/writing_guidelines/index.md @@ -14,9 +14,14 @@ MDN Web Docs is an open-source project. The sections outlined below describe our - [What we write](/en-US/docs/MDN/Writing_guidelines/What_we_write) - : This section covers what we include on MDN Web Docs and want we don't, as well as a number of other policies, such as when we write about new technologies, the content suggestion process, and whether we accept external links. This is a good place to start if you're considering writing or updating content for us. This section also includes: + - [Inclusion criteria](/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion) + - : Provides an in-depth criteria for content to be included on MDN Web Docs, the application process for getting new documentation added on MDN Web Docs, and the expectations and guidelines for a party applying. + - [Content reuse](/en-US/docs/MDN/Writing_guidelines/Content_reuse) + - : Describes our policy on content reuse and republishing, and how to get permission to republish content on MDN Web Docs. + - [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). diff --git a/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md b/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md index b32bb03e163f28a..58e82f16cc7e76f 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md @@ -10,476 +10,31 @@ browser-compat: api.AbortController {{MDNSidebar}} -MDN has a standard format for compatibility tables for our open web documentation; that is, documentation of technologies such as the DOM, HTML, CSS, JavaScript, SVG, and so forth, that are shared across all browsers. This article is a "getting started" guide to how to add to and maintain the database from which the compatibility tables are generated, as well as how to integrate the tables into articles. - -For more advanced documentation, as well as the very latest changes to the processes and JSON schemas used to represent the data, take a look at the data repository's [contributor guide](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md) as well as the [data guidelines guide](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md). +MDN has a standard format for tables that illustrate compatibility of shared technologies across all browsers, such as DOM, HTML, CSS, JavaScript, SVG, etc. +To make this data available in multiple projects programmatically, a Node.js package is built from the [`browser-compat-data` repository](https://github.com/mdn/browser-compat-data) and published to npm. +To modify the data within these tables, comprehensive documentation along with the most recent details of conventions and JSON schemas used to represent the data can be found in the repository's [contributing guide](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md) as well as the [data guidelines guide](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md). If you have questions or discover problems, you are welcome to [ask for help](/en-US/docs/MDN/Community/Contributing/Getting_started#step_4_ask_for_help). -## How to access the data repository - -The data is stored in a GitHub repository — see . To access it, you need to get a GitHub account, fork the browser-compat-data repo over to your own account, then clone your fork onto your local machine. - -## Preparing to add the data - -Before adding some new data, you should make sure that your fork is up-to-date with the main repo (it contains the same content), create a new branch inside your fork to contain your additions, then pull that branch into your local clone so you can start working inside it: - -Let's look at a simple way to make sure your fork is to-to-date is as follows: - -### Adding the main browser-compat-data repo as a remote - -Go to your local clone of your fork in your terminal/command line, and add a remote pointing to the main (upstream) repo like so (you only need to do this once): - -```bash -git remote add upstream https://github.com/mdn/browser-compat-data.git -``` - -If you are unsure whether you've done this, you can check what remotes your repo has using - -```bash -git remote -v -``` - -### Updating your fork with the remote's content - -Now, whenever you want to update your fork, you can do so by: - -1. Making sure you are in the main branch: - - ```bash - git checkout main - ``` - -2. fetching the up-to-date repo contents using the following: - - ```bash - git fetch upstream - ``` - -3. rebasing the contents of your main branch with the official repo's contents: - - ```bash - git rebase upstream/main - ``` - -4. pushing these updates back to your remote fork using this: - - ```bash - git push - ``` - -### Creating a new branch to do your work in - -Next, go to your remote fork (it will be at `https://github.com/your-username/browser-compat-data`) and create a new branch to store your changes for this data addition. This can be done by: - -1. Clicking on the "Branch: Main" button. -2. Entering a new branch name into the "Find or create a branch…" text field. -3. Pressing the resulting "Create branch _name-of-branch_ from Main" button. - -For example, if you were wanting to add data for the WebVR API, you'd create a branch called something like "webvr". - -### Switching to the new branch - -At this point, go back to your terminal/command line, and update your fork's local clone to include your new branch using the following command: - -```bash -git pull -``` - -Now switch to your new branch using this: - -```bash -git checkout name-of-branch -``` - -You should now be ready to start adding your data! - -## Adding the data - -To add the data, you need to create a new file or files to store your compat data in. The files you need to create differ, depending on what technology you are working on: - -- **[HTML](/en-US/docs/Web/HTML):** One file per HTML element, contained in [browser-compat-data/html/elements](https://github.com/mdn/browser-compat-data/tree/main/html/elements). The file should be called the name of the element, all in lower case, e.g. `div.json`. -- **[CSS](/en-US/docs/Web/CSS):** One file per CSS property or selector, contained in the appropriate directory (see [browser-compat-data/css](https://github.com/mdn/browser-compat-data/tree/main/css)). The file should be called the name of the feature, all in lower case, e.g. `background-color.json`, or `hover.json`. -- **[JS](/en-US/docs/Web/JavaScript):** One file per JS object, contained in [browser-compat-data/javascript/builtins](https://github.com/mdn/browser-compat-data/tree/main/javascript/builtins). The file should be called the exact name of the object, with the casing preserved, e.g. `Date.json` or `InternalError.json`. -- **[APIs](/en-US/docs/Web/API):** One file per interface contained in the API, put in [browser-compat-data/api](https://github.com/mdn/browser-compat-data/tree/main/api). Each file should be called the exact name of the interface, with the casing preserved, e.g. The WebVR API has `VRDisplay.json`, `VRDisplayCapabilities.json`, etc. - -Each file you create has to follow the pattern defined in the schema contained within our repo; you can see the [detailed schema description here](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md). - -### Basic compat data structure - -Let's look at an example. CSS property JSON files for example need the following basic structure: - -```json -{ - "css": { - "properties": { - "border-width": { - "__compat": { - // … - } - } - } - } -} -``` - -You have the `css` object, inside of which is a `properties` object. Inside the `properties` object, you need one member for each of the specific features you want to define the compat data for. Each of these members has a `__compat` member, inside of which the actual data goes. - -The above data is found in the [border-width.json](https://github.com/mdn/browser-compat-data/blob/main/css/properties/border-width.json) file — compare this to the [rendered border-width support table on MDN](/en-US/docs/Web/CSS/border-width#browser_compatibility). - -Other types of features work in the same way, but with different object names: - -- CSS selectors work in basically the same way as CSS properties, except that the top-level object structure is `css.selectors` instead of `css.properties`. See [cue.json](https://github.com/mdn/browser-compat-data/blob/main/css/selectors/cue.json) for an example. -- HTML data works in basically the same way, except that the top-level object structure is `html.elements`. See [article.json](https://github.com/mdn/browser-compat-data/blob/main/html/elements/article.json) for an example. -- The top level object structure for JS built-in objects is `javascript.builtins`; see [Array.json](https://github.com/mdn/browser-compat-data/blob/main/javascript/builtins/Array.json) for an example. - -In HTML, CSS, and JS pages, you'll normally only need one feature. API interfaces work slightly differently — they always have multiple sub-features (see [Sub-features](#sub-features), below). - -### Basic structure inside a feature +## Using BCD data in MDN pages -Inside a feature `__compat` member, you need to include the following members: +Once data has been included in the [`browser-compat-data`](https://github.com/mdn/browser-compat-data) repo, you can start dynamically including browser compatibility and specification tables based on that data within MDN pages. -- `mdn_url`: Contains the URL of the reference page for this feature on MDN. Note that this needs to be written without the locale directory inside, e.g. `/docs/…` not `/en-US/docs/…`. This is added in by the macro when the data is put on the page, for localization purposes. -- `spec_url`: URL or array of URLs to specification(s) in which this feature is defined. -- `support`: Contains members representing the browser support information for this feature in all the different browsers we want to report. -- `status`: Contains members reporting the standards track status of this feature. +To get started with BCD data in MDN pages, use the query string specified in the BCD source file for the relevant data you wish to include. +For example: -The names of the browser members are defined in the schema (see [Browser identifiers](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#browser-identifiers)). You should use the full list of currently defined identifiers. If you wish to add another browser, talk to us first, as this could have a wide-ranging impact and should not be done without careful thought. +- {{domxref("AbortController")}} compatibility data is defined in [api/AbortController.json](https://github.com/mdn/browser-compat-data/blob/main/api/AbortController.json) and can be queried using `api.AbortController`. +- {{HTTPHeader("Content-Type")}} HTTP header compatibility data is defined in [http/headers/content-type.json](https://github.com/mdn/browser-compat-data/blob/main/http/headers/content-type.json) and the query is `http.headers.Content-Type`. +- {{domxref("VRDisplay.capabilities")}} property compatibility data is defined in [api/VRDisplay.json](https://github.com/mdn/browser-compat-data/blob/main/api/VRDisplay.json) and its query is `api.VRDisplay.capabilities`. -In a basic browser compat data file, you'll only need to include "version_added" inside the browser identifier members (we'll cover [Adding data: Advanced cases](#adding_data_advanced_cases) later on). The different values you might want to include are as follows: - -- A version number: If you know the exact version in which a browser started to support your feature, use a string representing the number, e.g. `"47"`. -- `true`: If a browser supports a feature but you don't know the exact version number, use the value `true`. -- `false`: If a browser does not support a feature, use the value `false`. -- `null`: If you don't know whether a browser supports a feature or not, use the value `null`. - -Inside the `status` member, you'll include three submembers: - -- `experimental`: This should be set to `true` if the feature is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental), or `false` otherwise. -- `standard_track`: This should be set to `true` if a feature is on some kind of standards track (most commonly W3C/WHATWG, but there are also other standards efforts such as Khronos, TC39, etc.) or `false` otherwise. -- `deprecated`: This should be set to `true` if the feature is [deprecated](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated_and_obsolete), or `false` otherwise. - -The feature data for [border-width](/en-US/docs/Web/CSS/border-width#browser_compatibility) (also see [border-width.json](https://github.com/mdn/browser-compat-data/blob/main/css/properties/border-width.json)) is shown below as an example: - -```json -"__compat": { - "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width", - "spec_url": "https://drafts.csswg.org/css-backgrounds/#the-border-width", - "support": { - "chrome": { - "version_added": "1" - }, - "webview_android": { - "version_added": "2" - }, - "edge": { - "version_added": true - }, - "edge_mobile": { - "version_added": true - }, - "firefox": { - "version_added": "1" - }, - "firefox_android": { - "version_added": "1" - }, - "ie": { - "version_added": "4" - }, - "ie_mobile": { - "version_added": "6" - }, - "opera": { - "version_added": "3.5" - }, - "opera_android": { - "version_added": "11" - }, - "safari": { - "version_added": "1" - }, - "safari_ios": { - "version_added": "3" - } - }, - "status": { - "experimental": false, - "standard_track": true, - "deprecated": false - } -} -``` - -#### Adding a description - -There is a fourth, optional, member that can go inside the `__compat` member — `description`. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so: - -```json -{ - "api": { - "AbortController": { - "__compat": { - // … - }, - "AbortController": { - "__compat": { - "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController", - "description": "AbortController() constructor", - "support": { - … - } - } - } - - // … - } - } -} -``` - -### Sub-features - -In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was added much later in the specification's life and is only supported in a couple of browsers. - -As an example, see the [compat data](https://github.com/mdn/browser-compat-data/blob/main/css/properties/background-color.json) and [corresponding MDN page](/en-US/docs/Web/CSS/background-color) for the `background-color` property. The basic support exists inside the `__compat` object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own `__compat` object. - -```json -{ - "css": { - "properties": { - "background-color": { - "__compat": { - // … - }, - "alpha_ch_for_hex": { - "__compat": { - // … - }, - } - } - } - } -} -``` - -For an API, you've got the top two levels defined as `api.name-of-the-interface`, then a top-level `__compat` section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this: - -```json -{ - "api": { - "VRDisplay": { - "__compat": { - // … - }, - "cancelAnimationFrame": { - "__compat": { - // … - } - }, - "capabilities": { - "__compat": { - // … - } - }, - - // … - - } - } -} -``` - -See [VRDisplay.json](https://github.com/mdn/browser-compat-data/blob/main/api/VRDisplay.json) for a full example. - -## Adding data: Advanced cases - -There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data. - -### Including a footnote - -Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for {{domxref("VRDisplay.capabilities")}} (see also [VRDisplay.json](https://github.com/mdn/browser-compat-data/blob/main/api/VRDisplay.json)) (at the time of writing) had a footnote "Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this: - -```json -"chrome_android": { - "version_added": true, - "notes": "Currently supported only by Google Daydream." -} -``` - -### Including a vendor prefix - -If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. Imagine you had a feature that was supported with a `-moz-` prefix in Firefox. To specify this in the compat data, you'd need to add a "prefix" submember inside the relevant "firefox" submember. It would look something like this: - -```json -"firefox": { - "version_added": true, - "prefix": "-moz-" -} -``` - -### Including browser preferences or flags - -Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag. - -To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members: - -- `type`: The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using `about:config` in Firefox, or `chrome://flags` in Chrome), but you might also sometimes use a value of "compile_flag", which is a preference set when the browser build is compiled. -- `name`: This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in `chrome://flags`. -- `value_to_set`: This is a string representing the value that needs to be set on the preference, for example "true". - -So to add a preference/flag to the Chrome support for a feature, you'd do something like this: - -```json -"chrome": { - "version_added": "50", - "flags": [ - { - "type": "preference", - "name": "Enable Experimental Web Platform Features", - "value_to_set": "true" - } - ] -}, -``` - -If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example: - -```json -"firefox": { - "version_added": "57", - "flags": [ - { - "type": "preference", - "name": "dom.streams.enabled", - "value_to_set": "true" - }, - { - "type": "preference", - "name": "javascript.options.streams", - "value_to_set": "true" - } - ] -}, -``` - -### Including a version where support was removed - -Sometimes a feature will be added in a certain browser version, but then removed again as the feature is deprecated. This can be easily represented using the "version_removed" submember, which takes as its value a string representing the version number it was removed on. For example: - -```json -"firefox": { - "version_added": "35", - "version_removed": "47", -}, -``` - -### Including multiple support points for the same browser entry - -Sometimes you'll want to add multiple support data points for the same browser inside the same feature. - -As an example, the {{cssxref("text-align-last")}} property (see also [text-align-last.json](https://github.com/mdn/browser-compat-data/blob/main/css/properties/text-align-last.json)) was added to Chrome in version 35, supported behind a pref. - -The support mentioned above was then removed in version 47; also in version 47, support was added for `text-align-last` enabled by default. - -To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object: - -```json -"chrome": [ - { - "version_added": "47" - }, - { - "version_added": "35", - "version_removed": "47", - "flags": [ - { - "type": "preference", - "name": "Enable Experimental Web Platform Features", - "value_to_set": "true" - } - ] - } -], -``` - -> **Note:** You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info. - -### Including an alternative name - -Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized. - -To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member. - -> **Note:** The alternative name might not be an exact alias — it might have differing behavior to the standard version. - -Let's look at an example. The {{cssxref("border-top-right-radius")}} property (see also [border-top-right-radius.json](https://github.com/mdn/browser-compat-data/blob/2a0cc3f6bb17aa4345441bed47a059dffd847793/css/properties/border-top-right-radius.json)) was supported in Firefox: - -- From version 4 onwards with the standard name `border-top-right-radius`. -- From version 49 onwards with a `-webkit-` prefix, for browser compatibility purposes. -- From version 1 onwards with the alternative name `-moz-border-radius-topright`. Support for this alias was removed in version 12. - -To represent this in the data, we used the following JSON: - -```json -"firefox": [ - { - "version_added": "4", - "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if border-style was solid. This has been fixed in Firefox 50.0." - }, - { - "prefix": "-webkit-", - "version_added": "49", - "notes": "From Firefox 44 to 48, the -webkit- prefix was available with the layout.css.prefixes.webkit preference. Starting with Firefox 49, the preference defaults to true." - }, - { - "alternative_name": "-moz-border-radius-topright", - "version_added": "1", - "version_removed": "12" - } -], -``` - -## Pushing a change back to the main repo - -Once you are finished with adding your compat data, you should first test it using the following commands: - -- `npm run lint` — tests all the compat data to make sure the JSON is valid, and is written in the correct style, for example correct indentation, no missing commas, etc. It will print out a long list of file names and test results; if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc. -- `npm run show-errors` — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used. - -If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this: - -```bash -git add . -git commit -m 'adding compat data for name-of-feature' -git push -``` - -Now go to your remote fork (i.e. `https://github.com/your-username/browser-compat-data`) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen. - -At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted. - -## Inserting the data into MDN pages - -Once your new compatibility data has been included in the main [browser-compat-data](https://github.com/mdn/browser-compat-data) repo, you can start dynamically generating browser compatibility and specification tables based on that data on MDN pages. - -First you need to find the query string for the relevant compatibility data you wish to include. This can be determined by inspecting its source file. For example: - -- {{domxref("AbortController")}} compatibility data is defined in [AbortController.json](https://github.com/mdn/browser-compat-data/blob/main/api/AbortController.json) and can be queried using `api.AbortController`. -- {{HTTPHeader("Content-Type")}} HTTP header compatibility data is defined in [content-type.json](https://github.com/mdn/browser-compat-data/blob/main/http/headers/content-type.json) and the query is `http.headers.Content-Type`. -- {{domxref("VRDisplay.capabilities")}} property compatibility data is defined in [VRDisplay.json](https://github.com/mdn/browser-compat-data/blob/main/api/VRDisplay.json) and its query is `api.VRDisplay.capabilities`. - -The compatibility data query should be specified in the page front-matter using the `browser-compat` key. -For example, for the {{domxref("AbortController")}} this would be added as shown below: +The compatibility data query should be specified in the page front-matter in the `browser-compat` key. +For example, {{domxref("AbortController")}} would be added as shown below: ```plain --- - title: AbortController slug: Web/API/AbortController - … - browser-compat: api.AbortController --- @@ -487,7 +42,8 @@ browser-compat: api.AbortController The compatibility and specification tables corresponding to the key are then automatically rendered in place of the `\{{Compat}}` and `\{{Specifications}}` macros in the source. -You can also specify the desired API as the first argument to the macro as shown: `\{{Compat("api.AbortController")}}`. This can be useful if multiple compatibility tables are required on the same page. +You can also specify the desired API as the first argument to the macro as shown: `\{{Compat("api.AbortController")}}`. +This can be useful if multiple compatibility tables are required on the same page. The macro calls generate the following tables (and corresponding set of notes): diff --git a/files/en-us/mdn/writing_guidelines/page_structures/index.md b/files/en-us/mdn/writing_guidelines/page_structures/index.md index 1c80fafeb63f39f..04c2b66c694bbc4 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/index.md @@ -9,6 +9,7 @@ tags: {{MDNSidebar}} -Throughout MDN, there are various document structures that are used repeatedly, to provide consistent presentation of information in MDN articles. Here are articles describing these structures, so that, as an MDN author, you can recognize, apply, and modify them as appropriate for documents you write, edit, or translate. +Throughout MDN there are document structures that are used to provide consistent presentation of information in MDN articles. +This page lists articles describing these structures so that you can modify page content appropriately for the documents you write, edit, or translate. {{LandingPageListSubPages()}} diff --git a/meta/.gitignore b/meta/.gitignore deleted file mode 100644 index 045c9c2aeb8b3a9..000000000000000 --- a/meta/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -.hugo_build.lock -node_modules -public/ -resources/ diff --git a/meta/README.md b/meta/README.md deleted file mode 100644 index 625a4d3ac8ee597..000000000000000 --- a/meta/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# [MDN Web Docs for Contributors site generator](https://github.com/mdn/content/tree/main/meta) - -This directory contains the tools and content for the [MDN Web Docs for Contributors site](https://mdn-contributor-docs.mozilla.org/), also known as the meta documentation. While MDN documents the web platform, this site documents MDN itself. - -If you want to document an MDN tool or process, use this site generator and its content (found in this repository's `/meta/content/en/` directory). If you want to document a web platform technology, see [MDN Web Docs for Contributors](https://mdn-contributor-docs.mozilla.org/) instead. - -## Get started - -Before you author or develop this site, you need: - -- A clone of the mdn/content repository -- Node.js -- Yarn 1 - -To get started: - -1. Switch to the `meta` directory: Run `cd meta`. -2. Install the dependencies: Run `yarn`. -3. Start the development server: Run `yarn run start`. -4. Open the URL provided by the development server's `Web Server is available at` message. - -Edit the Markdown files in the `content/en` subdirectory. - -## Getting help - -If you want to contribute more to this tooling and documentation or to get help, reach out to the MDN contributors via [mdn/content discussions](https://github.com/mdn/content/discussions) or via [Matrix chat](https://chat.mozilla.org/#/room/#mdn:mozilla.org). diff --git a/meta/config.toml b/meta/config.toml deleted file mode 100644 index f02eb6f005e2b34..000000000000000 --- a/meta/config.toml +++ /dev/null @@ -1,93 +0,0 @@ -baseURL = "/" -title = "MDN Web Docs for Contributors" - -enableRobotsTXT = true - -# Hugo allows theme composition (and inheritance). The precedence is from left to right. -theme = ["docsy"] - -# Will give values to .Lastmod etc. -enableGitInfo = true - -# Language settings -contentDir = "content/en" -defaultContentLanguage = "en" -defaultContentLanguageInSubdir = false - -# Useful when translating. -enableMissingTranslationPlaceholders = true - -# Highlighting config -pygmentsCodeFences = true -pygmentsUseClasses = false -# Use the new Chroma Go highlighter in Hugo. -pygmentsUseClassic = false -#pygmentsOptions = "linenos=table" -# See https://help.farbox.com/pygments.html -pygmentsStyle = "tango" - -disableKinds = ["taxonomy", "taxonomyTerm", "tags", "tag"] -[taxonomies] - # tag = 'tags' - -# Configure how URLs look like per section. -[permalinks] -blog = "/:section/:year/:month/:day/:slug/" - -## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday -[blackfriday] -plainIDAnchors = true -hrefTargetBlank = true -angledQuotes = false -latexDashes = true - -[imaging] -resampleFilter = "CatmullRom" -quality = 75 -anchor = "smart" - -[languages] -[languages.en] -title = "MDN Web Docs for Contributors" -description = "Documentation for documenters" -languageName ="English" -weight = 1 - -[markup] - [markup.goldmark] - [markup.goldmark.renderer] - unsafe = true - [markup.highlight] - # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html - style = "tango" - # Uncomment if you want your chosen highlight style used for code blocks without a specified language - # guessSyntax = "true" - -[params] -copyright = "Mozilla and contributors" -privacy_policy = "https://www.mozilla.org/en-US/privacy/websites/" -github_repo = "https://github.com/mdn/content" -github_branch = "main" -prism_syntax_highlighting = false - -# [[params.links.user]] -# name = "Stack Overflow" -# url = "https://example.org/stack" -# icon = "fab fa-stack-overflow" -# desc = "Practical questions and curated answers" -# Developer relevant links. These will show up on right side of footer and in the community page if you have one. -# [[params.links.developer]] -# name = "GitHub" -# url = "https://github.com/google/docsy" -# icon = "fab fa-github" -# desc = "Development takes place here!" -# [[params.links.developer]] -# name = "Slack" -# url = "https://example.org/slack" -# icon = "fab fa-slack" -# desc = "Chat with other project developers" -# [[params.links.developer]] -# name = "Developer mailing list" -# url = "https://example.org/mail" -# icon = "fa fa-envelope" -# desc = "Discuss development issues around the project" diff --git a/meta/content/en/_index.md b/meta/content/en/_index.md deleted file mode 100755 index cdc39b33934bfef..000000000000000 --- a/meta/content/en/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "MDN Web Docs for Contributors" -linkTitle: "Home" -weight: 20 -layout: docs -menu: - main: - weight: 20 - -# forces the whole site to use the "docs" structure in Docsy -cascade: -- type: "docs" - _target: - path: "/**" ---- - -If you want to contribute to MDN Web Docs, then you're in the right place. If you're looking for documentation for CSS, HTML, JavaScript, and other web development topics, go to [`developer.mozilla.org`](https://developer.mozilla.org/). diff --git a/meta/content/en/changelog.md b/meta/content/en/changelog.md deleted file mode 100644 index 1e97d282375db21..000000000000000 --- a/meta/content/en/changelog.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Changelog" -weight: 100 ---- - -## March 2022 - -- Added [guidance for including external links](/writing/style/external-links/). -- Migrated [adding images directions](/legacy/adding-images/) from the README. diff --git a/meta/content/en/community/_index.md b/meta/content/en/community/_index.md deleted file mode 100644 index f4448dc718a04fb..000000000000000 --- a/meta/content/en/community/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Community" -weight: 20 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/community/etiquette.md b/meta/content/en/community/etiquette.md deleted file mode 100644 index 46e4ffe86aa8a88..000000000000000 --- a/meta/content/en/community/etiquette.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Etiquette and expectations for behavior" -weight: 30 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/community/fora.md b/meta/content/en/community/fora.md deleted file mode 100644 index b160168937b08df..000000000000000 --- a/meta/content/en/community/fora.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Where to get help" -weight: 20 -description: > - This page needs a description. ---- - - - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/community/people.md b/meta/content/en/community/people.md deleted file mode 100644 index dc7f6a60392161e..000000000000000 --- a/meta/content/en/community/people.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Who makes MDN?" -weight: 10 -description: > - This page needs a description. ---- - - - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/community/report-cpg-spam.md b/meta/content/en/community/report-cpg-spam.md deleted file mode 100644 index 459b0fe9a99164e..000000000000000 --- a/meta/content/en/community/report-cpg-spam.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Report spam and other community issues" -weight: 40 -description: > - This page needs a description. ---- - - - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/get-started/_index.md b/meta/content/en/get-started/_index.md deleted file mode 100644 index 8e8446dc86a593b..000000000000000 --- a/meta/content/en/get-started/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -categories: ["Examples", "Placeholders"] -tags: ["test","docs"] -title: "Get started" -weight: 2 -description: > - If you're a first-time contributor to MDN Web Docs, start here. ---- diff --git a/meta/content/en/get-started/ways-to-contribute.md b/meta/content/en/get-started/ways-to-contribute.md deleted file mode 100644 index 6579f4a428be4ff..000000000000000 --- a/meta/content/en/get-started/ways-to-contribute.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Ways to contribute" -date: 2017-01-05 -weight: 20 -description: > - You can contribute in many ways, from reporting problems to writing docs to developing the platform. ---- - - - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/get-started/why.md b/meta/content/en/get-started/why.md deleted file mode 100644 index 2b0b8a14d34582d..000000000000000 --- a/meta/content/en/get-started/why.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Why you should contribute to MDN" -weight: 10 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/_index.md b/meta/content/en/governance/_index.md deleted file mode 100644 index bd2d13fc79a49fe..000000000000000 --- a/meta/content/en/governance/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Governance and process" -weight: 30 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/browser-compatability.md b/meta/content/en/governance/browser-compatability.md deleted file mode 100644 index 06fda148bed82b8..000000000000000 --- a/meta/content/en/governance/browser-compatability.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Browser compatibility tables" -linkTitle: "Compatibility tables" -weight: 40 -description: > - How we manage the contents of browser compatibility tables ---- - -Browser compatibility tables on MDN Web Docs are generated from [mdn/browser-compat-data](https://github.com/mdn/browser-compat-data) (also known as _BCD_). While MDN content and BCD are closely related projects, they're not directly tied to each other. This page describes the relationship between MDN content and BCD. - -## MDN Web Docs and BCD are distinct projects - -MDN Web Docs content is managed separately from browser compatibility data. BCD has its own [governance](https://github.com/mdn/browser-compat-data/blob/main/GOVERNANCE.md), [contribution process](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md), and [content guidelines](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md). - -MDN uses browser compatibility data to generate browser compatibility tables (plus some other site content). MDN uses the data as provided, including: - -- Feature descriptions -- Support status and reported version numbers -- Notes -- Experimental, standards track, and deprecation status - -That said, MDN does not necessarily use all compatibility data. For example, some features in BCD don't have corresponding pages on MDN. Historically, certain browsers were part of BCD, but weren't included in compatibility tables on MDN. - -The MDN site is just one of many consumers of BCD. While MDN's needs influence the direction and contents of BCD, they're not determinative. - -## Update data - -To change the details of individual compatibility tables on MDN, [contribute directly to BCD](https://github.com/mdn/browser-compat-data). - -## Add a browser or engine - -From time to time, MDN has added new browsers and engines to compatibility tables. -The MDN team selects browsers and engines to appear, weighing factors including: - -- Relevance to open web platform technologies, both today and in the future -- Reader benefit and interest -- Maintenance requirements and impact on contributors -- Alignment with MDN's mission - -In practice, selecting a browser requires two interdependent decision-making processes: - -- Adding the browser or engine to BCD -- Selecting the browser or engine to appear on MDN - -Since these processes can overlap, it presents something of a [chicken-or-the-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) problem. -To recommend adding a browser to MDN, follow these steps: - -1. Review BCD's [_Addition of browsers_](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md#addition-of-browsers) guideline. - -2. Start [a discussion on the mdn/content repository](https://github.com/mdn/content/discussions) proposing to add the browser and mention `@mdn/yari-content`. - -3. Complete the [browser selection questionnaire](#compatibility-table-browser-selection-questionnaire). - - If you're comfortable sharing your responses publicly, do so; - otherwise, ask in the GitHub discussion for a Mozilla email contact. - - If needed, the MDN team may ask follow-up questions. - -4. Wait for the team to consider your recommendation. - -Whether your recommendation is selected, deferred, or rejected, we'll follow up in the GitHub discussion with next steps. - -## Browser selection questionnaire - -Answer these questions to recommend a browser (or engine) to MDN compatibility tables: - -1. Why do you want this browser added to MDN (and BCD)? -2. How many users and developers do you estimate the browser has? - How did you make this estimation? -3. What's the governance model of the browser? - For example, who owns it, what is or is not open source, who participates in its development, and how is it funded? -4. What is on the browser's roadmap for the next year? - How do you see the browser's compatibility or support for existing tools changing in the future? diff --git a/meta/content/en/governance/issues/_index.md b/meta/content/en/governance/issues/_index.md deleted file mode 100644 index a22050910732868..000000000000000 --- a/meta/content/en/governance/issues/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Issues" -weight: 0 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/issues/triage.md b/meta/content/en/governance/issues/triage.md deleted file mode 100644 index c9612f7ddf30b67..000000000000000 --- a/meta/content/en/governance/issues/triage.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Issue triage" -weight: 0 -description: > - Issue triage process for mdn/content ---- - -We triage new issues filed in the mdn/content repository. The purpose of triage is: - -1. **Quickly close any issues that don't need further action from mdn/content maintainers**: For example, we often see issues that could be closed with a comment, but it's hard for individual maintainers to feel able (empowered) to do this. It's helpful to have a dedicated space where we can make collective decisions about these issues, and record them as collective decisions. - -2. **Help remove blockages to issues being worked on**: We see issues getting stuck because it is not clear how to process with them. An outline of a plan for how to address an issue helps maintainers (both staff and volunteers) fix it. - -## Triage meeting schedule and participants - -We hold triage once a week. Triage meetings alternate timezones, between Europe/Asia-friendly and Europe/North America-friendly. - -The meeting lasts 30 minutes. - -All mdn/content maintainers (that is, all people with merge access to mdn/content) are invited. - -One person is responsible for running the meeting: this includes getting the list of issues to triage and updating issues (adding labels, writing comments). - -## Meeting schedule - -The person running the meeting has a list of open issues that have the `needs-triage` label set. - -For each issue, we ask: - -- is this an issue we want to keep open? If not, close it now with a comment. -- is this issue in the correct repo? If not, transfer it now with a comment. -- otherwise: - - do we need more information from the reporter? If so, ask, add the `needs-info` label, and move on. Issues that have had `needs-info` set for a month without a response may be closed. - - is it a bug or a feature request? - - what does a fix look like? If we can quickly decide and write that up as a comment in the issue. If we can't, don't (so we don't spend 30 minutes discussing one issue - maybe schedule it for the editorial meeting instead?) - - is it a good first issue? If so, add the `good-first-issue` label. - - do we need more/expert opinion? If so, tag an expert in the issue. -- remove the `needs-triage` label - -This process does not prioritize issues or assign issues to people. diff --git a/meta/content/en/governance/meetings.md b/meta/content/en/governance/meetings.md deleted file mode 100644 index 56cea699f234adb..000000000000000 --- a/meta/content/en/governance/meetings.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Meetings" -weight: 30 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/pulls/_index.md b/meta/content/en/governance/pulls/_index.md deleted file mode 100644 index 61c868cb9783b44..000000000000000 --- a/meta/content/en/governance/pulls/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Pull requests" -weight: 0 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/pulls/review.md b/meta/content/en/governance/pulls/review.md deleted file mode 100644 index 11ed406d0594660..000000000000000 --- a/meta/content/en/governance/pulls/review.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Review a pull request" -weight: 0 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/roadmap.md b/meta/content/en/governance/roadmap.md deleted file mode 100644 index d2f1639384bbf8c..000000000000000 --- a/meta/content/en/governance/roadmap.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "What we document" -weight: 10 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/governance/roles-and-responsibilities.md b/meta/content/en/governance/roles-and-responsibilities.md deleted file mode 100644 index 6f815a5a6f9ed50..000000000000000 --- a/meta/content/en/governance/roles-and-responsibilities.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Roles and responsibilities" -weight: 20 -description: > - This page needs a description. ---- - -{{% pageinfo %}} -This is a placeholder page. -{{% /pageinfo %}} diff --git a/meta/content/en/legacy/_index.md b/meta/content/en/legacy/_index.md deleted file mode 100644 index a8028acdc26a1a5..000000000000000 --- a/meta/content/en/legacy/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Legacy documentation" -weight: 1000 -description: > - Unedited contributor documentation migrated from GitHub and MDN itself. ---- diff --git a/meta/content/en/legacy/adding-images.md b/meta/content/en/legacy/adding-images.md deleted file mode 100644 index 36fcbecdd56ae95..000000000000000 --- a/meta/content/en/legacy/adding-images.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Adding images" -weight: 4 ---- - -Adding an image to a document is easy as well. All you need to do is add -your image file within the document's folder, and then reference the image -from within the document's `index.html` or `index.md` file, using an `` -or [the equivalent Markdown syntax](https://github.github.com/gfm/#images). -It's as easy as that. Let's walk through an example: - -1. You should be getting used to this by now, as we've done it several - times above. Make sure you start with a fresh working branch updated with - the latest content from the `main` branch of the `mdn` remote. - - ```sh - 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-images - ``` - -2. Add your image to the document folder. For this example, let's assume - we're adding a new image to the `files/en-us/web/css` document. - - ```sh - cd ~/repos/mdn/content - cp /some/path/my-cool-image.png files/en-us/web/css/ - ``` - -3. Run the `filecheck` command on each image you add. It'll complain if - something's wrong (see also the [Compressing images](#compressing-images) - section below). - We'll automatically run this as one of the tests we run when your new pull - request is created, but why wait to fix any possible issues later? - - ```sh - yarn filecheck files/en-us/web/css/my-cool-image.png - ``` - -4. Use your image within the document. For example, add the following `` element - somewhere inside `files/en-us/web/css/index.html`: - - ```html - My cool image - ``` - -5. Add and commit all of the deleted, created, and modified files, as well as - push your branch to your fork: - - ```sh - git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html - git commit - git push -u origin my-images - ``` - -6. Now you're ready to create your - [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). - -## Compressing images - -When you add images to MDN, you should make sure that they are compressed -as much as possible without degrading quality, to save on download size -for our readers. In fact, if you don't do this our CI process will fail -and the build results will warn you that some of your images are too big. - -The best way to compress them is by using the built-in compression tool. -You can compress an image appropriately by using the `filecheck` command -with the `--save-compression` option — this compresses the specified image -as much as possible, and saves the result over the top of the original. - -For example: - -```sh -yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression -``` diff --git a/meta/content/en/legacy/archiving.md b/meta/content/en/legacy/archiving.md deleted file mode 100644 index 036987d24172693..000000000000000 --- a/meta/content/en/legacy/archiving.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Archiving and unarchiving pages" -linkTitle: "Archiving" -weight: 4 ---- - -Pages with the banner "This is an archived page. It's not actively maintained." -at the top are archived pages — they are archived because either they are -obsolete or out-of-date, or they are not in scope for MDN contributors to -actively work on. - -If you find a page that is marked archived and you think it shouldn't be, -you can follow the below steps to unarchive it: - -- Submit an issue to check why the page is archived and if it should be - unarchived. -- Find the source code location of the archived page. Archived pages live in - the [Archived content](https://github.com/mdn/archived-content/) repo, - the structure of which is the same as this repo (except that there are - also locale directories present other than `en-US`). As an example: - - Take the archived 'Mobile developer challenge' page, which was at the URL `https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge`. - - This page's source code is at [https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html](https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html). -- To unarchive the page, you need to open a pull request to move the page's - directory into the appropriate place inside this repo, and update the - page's meta data (like `slug`) if needed. - -> **Note:** To archive a non-archived page, you need to follow the -> above procedure, but move the page in question the opposite way between repos. -> When removing the page from MDN, remember to use the [delete command](#deleting-a-document). - -**Note:** You can have an archived page with non-archived pages below it in the -hierarchy, and vice versa. To achieve this you need to have the same directory -structure in both the `content` and `archive-content` repos. Whether a page -is non-archived or archived depends on which repo its `index.html` file is -in. As an example, compare the [archived-content mozilla directory](https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla) -with the [content mozilla directory](https://github.com/mdn/content/tree/main/files/en-us/mozilla). -Both locations represent the same directory structure, but the -`index.html` file appears in the latter, therefore the page is not archived. diff --git a/meta/content/en/legacy/code-examples.md b/meta/content/en/legacy/code-examples.md deleted file mode 100644 index e1e0d5f59fc56a8..000000000000000 --- a/meta/content/en/legacy/code-examples.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Adding code examples" -linkTitle: "Code examples" -weight: 4 ---- - -There are a lot of code examples on MDN, and you'll probably want to add -some as you contribute content to the project. There are four types of -code example used on MDN: - -- [Static examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Static_examples) - — plain code blocks, possibly with a screenshot to statically show the - result of such code if it were to be run. -- [Traditional MDN "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Traditional_live_samples) - — A macro that takes plain code blocks, dynamically puts - them into a document inside an `