From 33557991243c4404e7e2183e677748d00c64150b Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 3 Jul 2023 11:54:51 -0400 Subject: [PATCH 1/7] creates new css template --- .../css_module_landing_page_template/index.md | 114 ++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md new file mode 100644 index 000000000000000..5a7e434ef88cd65 --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -0,0 +1,114 @@ +--- +title: CSS module landing page template +slug: MDN/Writing_guidelines/Page_structures/Page_types/CSS_module_landing_page_template +page-type: mdn-writing-guide +--- + +{{MDNSidebar}} + +> **Note:** _Remember to remove this note block before publishing._ +> +> --- +> +> **Page front matter:** +> +> The front matter at the top of the page is used to define "page metadata". +> The values should be updated appropriately for the particular module. +> +> ```md +> --- +> title: CSS NameOfTheModule +> slug: Web/CSS/CSS_NameOfTheModule +> page-type: css-module +> spec-urls: +> - url1 +> - url2 +> --- +> ``` +> +> - **title** +> - : The `title` value is displayed at the top of the page. +> This is the text "CSS" followed by the name of the module. +> For example, the module landing page for the [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module is _CSS grid layout_. +> - **slug** +> - : The `slug` value is the end of the URL path after `https://developer.mozilla.org/en-US/docs/`. +> This will be formatted as `Web/CSS/CSS_NameOfTheModule`. +> For example, the slug for the [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module landing page is `Web/CSS/CSS_grid_layout`. +> - **page-type** +> - : The `page-type` value for CSS module landing pages is `css-module`. +> - **spec-urls** +> - : The `spec-urls` value is a URL of the specification. In case there is more than one version of the specification that is relevant, present them in a bulleted list. For example, the value for `spec-urls` key for the [filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module landing page is: +> - `https://drafts.fxtf.org/filter-effects-2/` +> - `https://drafts.fxtf.org/filter-effects-1/` +> +> --- +> +> **Top-of-page macros** +> +> The `\{{CSSRef}}` macro call appears at the top of the content section (immediately below the page front matter). +> This macro must be present on every CSS module landing page. It generates a suitable CSS sidebar, depending on the tags included on the page. +> Remove the `\{{MDNSidebar}}` macro when you use this template. +> +> --- +> +> _Remember to remove this note block before publishing._ +> + +Begin the content on the page with an introductory paragraph, which names the module and says what it does. +This should ideally be one or two short sentences. + +## NameOfTheModule in action + +In this section, include an interactive example of the module that helps to demonstrate the usefulness or the power of various properties provided by this module. The purpose of this section is to create interest and curiosity in the mind of the readers learning about this module and the possibilities. Provide a short description of how readers can interact with the example. Don't go into a lot of detail in this section, and don't include code snippets. Add a link to the source code for the example in the [`css-examples`](https://github.com/mdn/css-examples/tree/main/modules) repository. For example, for the filter effects module interactive example, you would say: +"To see the code for this example, [view the source on GitHub](https://github.com/mdn/css-examples/blob/main/modules/filters.html)." + +## Reference + +### Properties + +List of all shorthand and longhand properties provided by the module. + +### At-rules + +List of CSS at-rules provided by the module. Omit this section if there are no relevant CSS at-rules for this module. + +### Functions + +List of CSS functions provided by the module. Omit this section if there are no relevant CSS functions for this module. + +### Data types + +List of CSS data types provided by the module. Omit this section if there are no relevant CSS data types for this module. + +### Events + +List of API events provided by the module. Omit this section if there are no relevant events for this module. + +### Interfaces + +List the related API and interfaces provided by the module. Omit this section if there are no relevant API interfaces for this module. + +## Guides + +- LinkToGuide1 + - : Description of the guide in one or two sentences. +- LinkToGuide2 + - : Description of the guide in one or two sentences. + +## Related concepts + +List all properties, data types, or glossary terms that may be relevant or related to this module. + +## Specifications + +`\{{Specifications}}` + +_To use this macro, remove the backticks and backslash in the markdown file._ + +## See also + +Include links to reference pages and guides related to the current property. Check the [See also](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) section in our _Writing style guide_ for more hints and directions. + +- link1 +- link2 +- external_link (year) From 0ea9737db51bebca069ec08ec51ddaa73f3cd3ac Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 3 Jul 2023 22:05:57 -0400 Subject: [PATCH 2/7] updates page types page to link to the new template --- .../css_module_landing_page_template/index.md | 10 +++++--- .../page_structures/page_types/index.md | 23 ++++++++++++++++++- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md index 5a7e434ef88cd65..71bef79bc08c601 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -29,7 +29,7 @@ page-type: mdn-writing-guide > - **title** > - : The `title` value is displayed at the top of the page. > This is the text "CSS" followed by the name of the module. -> For example, the module landing page for the [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module is _CSS grid layout_. +> For example, the title for the [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module landing page is _CSS grid layout_. > - **slug** > - : The `slug` value is the end of the URL path after `https://developer.mozilla.org/en-US/docs/`. > This will be formatted as `Web/CSS/CSS_NameOfTheModule`. @@ -59,11 +59,15 @@ This should ideally be one or two short sentences. ## NameOfTheModule in action -In this section, include an interactive example of the module that helps to demonstrate the usefulness or the power of various properties provided by this module. The purpose of this section is to create interest and curiosity in the mind of the readers learning about this module and the possibilities. Provide a short description of how readers can interact with the example. Don't go into a lot of detail in this section, and don't include code snippets. Add a link to the source code for the example in the [`css-examples`](https://github.com/mdn/css-examples/tree/main/modules) repository. For example, for the filter effects module interactive example, you would say: +In this section, include an interactive example of the module that helps to demonstrate the usefulness or the power of various properties provided by this module. The purpose of this section is to demonstrate a few use cases and to create interest and curiosity in the mind of the readers learning about this module. + +Provide a short description of how readers can interact with the example. Don't go into a lot of detail to explain the example, and don't include code snippets. Add a link to the source code for the example in the [`css-examples`](https://github.com/mdn/css-examples/tree/main/modules) repository. For example, for the filter effects module interactive example, you would say: "To see the code for this example, [view the source on GitHub](https://github.com/mdn/css-examples/blob/main/modules/filters.html)." ## Reference +Create the relevant subsections to list the related properties, functions, data types, and so on. + ### Properties List of all shorthand and longhand properties provided by the module. @@ -97,7 +101,7 @@ List the related API and interfaces provided by the module. Omit this section if ## Related concepts -List all properties, data types, or glossary terms that may be relevant or related to this module. +List all other properties, data types, or glossary terms that may be relevant or related to this module. ## Specifications diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md index 2e0ecd6ed51dc46..57ea1599b36c585 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md @@ -45,7 +45,7 @@ If the work is more significant, then you should consider a few factors when pri If you want to get a team together to work on an update, or you just want to report or discuss some content needing an update, feel free to [file a content issue](https://github.com/mdn/content/issues) or [ask us for help](/en-US/docs/MDN/Community/Communication_channels). -## The page-type front matter key +## Front matter key for page types We have defined a front matter key `page-type` to clearly identify the type of MDN pages. The templates linked below indicate which `page-type` values you should set for each page type. @@ -129,6 +129,27 @@ An **SVG reference page** lists all the attributes that are available on an SVG - [SVG element page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template) +## CSS module landing page + +Every **[CSS](/en-US/docs/Web/CSS) module** links to a specification that provides support for certain features and implementations in CSS. For example, the specification linked to the [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module describes the margin and padding properties that let you create spacing in and around a CSS box. + +A **CSS module landing page** provides an overview of the features that the module provides and lists all the properties, data types, CSS functions, and so on offered by the module. The CSS module landing page also provides a quick demonstration of what can be achieved using the properties of the module through an interactive example. +The module landing page serves primarily as a _navigation_ page, but also functions as an at-a-glance _reference_ page for the module. + +Some related properties and features that belong in other modules but are closely related to the functionality offered by the module you are documenting can also be covered in a _Related concepts_ section. +For example, the `` data type and the `prefers-reduced-motion` media query are not covered in the CSS animations module, but because they are closely related with CSS animations, it is a good idea to highlight them in the [Related concepts](/en-US/docs/Web/CSS/CSS_animations#related_concepts) section of the CSS animations module landing page. + +### Examples + +- [CSS animations](/en-US/docs/Web/CSS/CSS_animations) +- [CSS basic user interface](/en-US/docs/Web/CSS/CSS_basic_user_interface) +- [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) +- [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) + +### Templates + +- [CSS module landing page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_module_landing_page_template) + ## CSS feature reference page A **CSS reference page** lists all the available syntax for a CSS feature such as a selector or property, and explains the feature's purpose and usage. It also provides examples, browser compatibility information, and other important data. From fd39c03e287bd325d327e97e6b62a5789303ab52 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 3 Jul 2023 22:24:26 -0400 Subject: [PATCH 3/7] fixes prettier erros --- .../page_types/css_module_landing_page_template/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md index 71bef79bc08c601..57f12767ba9c155 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -21,8 +21,8 @@ page-type: mdn-writing-guide > slug: Web/CSS/CSS_NameOfTheModule > page-type: css-module > spec-urls: -> - url1 -> - url2 +> - url1 +> - url2 > --- > ``` > @@ -52,7 +52,6 @@ page-type: mdn-writing-guide > --- > > _Remember to remove this note block before publishing._ -> Begin the content on the page with an introductory paragraph, which names the module and says what it does. This should ideally be one or two short sentences. From efb00cdcc7c691ed33a02ca59c4dfadcc413b6c8 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 10 Jul 2023 14:39:41 -0400 Subject: [PATCH 4/7] fixes review comments --- .../writing_guidelines/page_structures/page_types/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md index 57ea1599b36c585..6b987d5350c6afb 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md @@ -131,9 +131,9 @@ An **SVG reference page** lists all the attributes that are available on an SVG ## CSS module landing page -Every **[CSS](/en-US/docs/Web/CSS) module** links to a specification that provides support for certain features and implementations in CSS. For example, the specification linked to the [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module describes the margin and padding properties that let you create spacing in and around a CSS box. +Every **[CSS](/en-US/docs/Web/CSS) module** represents a CSS specification that provides support for certain features and implementations in CSS. For example, the [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module represents the [specification](/en-US/docs/Web/CSS/CSS_box_model#specifications) that describes the margin and padding properties that let you create spacing in and around a CSS box. -A **CSS module landing page** provides an overview of the features that the module provides and lists all the properties, data types, CSS functions, and so on offered by the module. The CSS module landing page also provides a quick demonstration of what can be achieved using the properties of the module through an interactive example. +A **CSS module landing page** provides an overview of the features that the module provides and lists all the properties, data types, CSS functions, and so on offered by the module. When possible, the CSS module landing page provides a quick demonstration of what can be achieved using the properties of the module through an interactive example. The module landing page serves primarily as a _navigation_ page, but also functions as an at-a-glance _reference_ page for the module. Some related properties and features that belong in other modules but are closely related to the functionality offered by the module you are documenting can also be covered in a _Related concepts_ section. From d1261425c6acac0c7112c94afb4d1e41c6b340a6 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 10 Jul 2023 14:53:07 -0400 Subject: [PATCH 5/7] reverts heading --- .../mdn/writing_guidelines/page_structures/page_types/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md index 6b987d5350c6afb..af31a489dff831e 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md @@ -45,7 +45,7 @@ If the work is more significant, then you should consider a few factors when pri If you want to get a team together to work on an update, or you just want to report or discuss some content needing an update, feel free to [file a content issue](https://github.com/mdn/content/issues) or [ask us for help](/en-US/docs/MDN/Community/Communication_channels). -## Front matter key for page types +## The page-type front matter key We have defined a front matter key `page-type` to clearly identify the type of MDN pages. The templates linked below indicate which `page-type` values you should set for each page type. From 372a1200fddcc0c8065c030ddb6e5c7beab9a60e Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 10 Jul 2023 14:59:30 -0400 Subject: [PATCH 6/7] fixes review comments --- .../page_types/css_module_landing_page_template/index.md | 3 +++ .../mdn/writing_guidelines/page_structures/page_types/index.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md index 57f12767ba9c155..b25072f76d00fa4 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -38,8 +38,11 @@ page-type: mdn-writing-guide > - : The `page-type` value for CSS module landing pages is `css-module`. > - **spec-urls** > - : The `spec-urls` value is a URL of the specification. In case there is more than one version of the specification that is relevant, present them in a bulleted list. For example, the value for `spec-urls` key for the [filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module landing page is: +> +> ```plain > - `https://drafts.fxtf.org/filter-effects-2/` > - `https://drafts.fxtf.org/filter-effects-1/` +> ``` > > --- > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md index af31a489dff831e..a4f486913b8fa58 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md @@ -136,7 +136,7 @@ Every **[CSS](/en-US/docs/Web/CSS) module** represents a CSS specification that A **CSS module landing page** provides an overview of the features that the module provides and lists all the properties, data types, CSS functions, and so on offered by the module. When possible, the CSS module landing page provides a quick demonstration of what can be achieved using the properties of the module through an interactive example. The module landing page serves primarily as a _navigation_ page, but also functions as an at-a-glance _reference_ page for the module. -Some related properties and features that belong in other modules but are closely related to the functionality offered by the module you are documenting can also be covered in a _Related concepts_ section. +Some related properties and features that belong in other modules, but that are closely related to the functionality offered by the module you are documenting, can also be covered in a _Related concepts_ section. For example, the `` data type and the `prefers-reduced-motion` media query are not covered in the CSS animations module, but because they are closely related with CSS animations, it is a good idea to highlight them in the [Related concepts](/en-US/docs/Web/CSS/CSS_animations#related_concepts) section of the CSS animations module landing page. ### Examples From 54fcea83d52fe00cf772ba8251e9fc27d4fd8a90 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Mon, 10 Jul 2023 15:04:18 -0400 Subject: [PATCH 7/7] fixes prettier errors --- .../page_types/css_module_landing_page_template/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md index b25072f76d00fa4..4f36812828e23ae 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -37,6 +37,7 @@ page-type: mdn-writing-guide > - **page-type** > - : The `page-type` value for CSS module landing pages is `css-module`. > - **spec-urls** +> > - : The `spec-urls` value is a URL of the specification. In case there is more than one version of the specification that is relevant, present them in a bulleted list. For example, the value for `spec-urls` key for the [filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module landing page is: > > ```plain