From 3034628aeda0bf95ff631a50b13a26539e726b57 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 15 Sep 2022 15:39:52 +0200 Subject: [PATCH 01/26] docs(contributing): details about adding images to video guide --- .../howto/images_media/index.md | 69 ++++++++++++++++++- 1 file changed, 67 insertions(+), 2 deletions(-) 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..511e0ffc462c8b2 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.html` or `index.md` file, using an `` 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 will 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 a document, for example, with an `` element 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 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. From 6416cd03e92cb93e2a4dd8001383b1475226c104 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 15 Sep 2022 16:29:05 +0200 Subject: [PATCH 02/26] docs(contributing): details about code examples --- .../howto/code_examples/index.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 files/en-us/mdn/writing_guidelines/howto/code_examples/index.md diff --git a/files/en-us/mdn/writing_guidelines/howto/code_examples/index.md b/files/en-us/mdn/writing_guidelines/howto/code_examples/index.md new file mode 100644 index 000000000000000..577e51a3acb0d98 --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/howto/code_examples/index.md @@ -0,0 +1,27 @@ +--- +title: How to add code examples +slug: MDN/Writing_guidelines/Howto/Code_examples +tags: + - meta + - writing-guide +page-type: mdn-writing-guide +--- + +{{MDNSidebar}} + +## Adding code examples + +There are a lot of code examples on MDN, and you'll probably want to add some as you contribute content to the project. This page describes the types of code examples available to use on MDN. + +There are four types of code examples used: + +- [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. +- [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 `