Writing Guidelines: quicklinks and surfacing content (#31248)

* Writing guidelines: structure the page templates sectionfor ease of navigation. * alt for images * update links from wiki to github * see also to quicklinks page and list of macros * page types: added templates and see also sections * Added see also to page structure (which was just a list of subpages) * Explanation of quicklinks * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * twaks * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * twaks * page components desc. * Update files/en-us/mdn/writing_guidelines/page_structures/index.md * Update files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md * move macros to see also section * move macros to see also section * Update files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md * Update files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * the bot and this PR hate me * Update files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * happiness * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md * header levels * make it clearer * grammar * Apply suggestions from code review Co-authored-by: Hamish Willee <[email protected]> * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Change to sidebars and other link macros * escape macro * escape macro * addressed will's comments * typo --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Hamish Willee <[email protected]>
mdn · Jan 3, 2024 · 95766bd · 95766bd
1 parent a8006cf
commit 95766bd
Show file tree

Hide file tree

Showing 6 changed files with 206 additions and 83 deletions.
diff --git a/files/en-us/mdn/writing_guidelines/page_structures/index.md b/files/en-us/mdn/writing_guidelines/page_structures/index.md
@@ -10,3 +10,8 @@ Throughout MDN there are document structures that are used to provide consistent
 This page lists articles describing these structures so that you can modify page content appropriately for the documents you write, edit, or translate.
 
 {{LandingPageListSubPages()}}
+
+## See also
+
+- [Page templates](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates)
+- [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components)
diff --git a/...-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md b/...-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md
@@ -260,3 +260,21 @@ You can use the argument `notservice` to indicate that a feature works in web wo
 
 {{AvailableInWorkers}}
 {{AvailableInWorkers("notservice")}}
+
+## Browser compatibility and specification macros
+
+The following macros are included on all reference pages, but are also supported by all page types:
+
+- `\{{Compat}}` / `\{{Compat(&lt;feature>)}}` / `\{{Compat(&lt;feature>, &lt;depth>)}}`
+
+  - : Generates a [compatibility table](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for the feature passed as the parameter. If no parameter is included, it defaults to the features defined by `browser-compat` in the frontmatter. An optional depth parameter sets how deep sub features should be added to the table. The depth, if omitted, defaults to 1, meaning only the first level of sub feature data from BCD will be included.
+
+- `\{{Specifications}}` / `\{{Specifications(&lt;feature>)}}`
+  - : Includes the specification for the feature specified in the parameter. If no parameter is passed, the specification listed is defined by the value for `spec_urls` in the frontmatter, if present, or from the specification listed in browser compatibility data defined by `browser-compat` in the frontmatter. The specification is rendered as an external link.
+
+## See also
+
+- [Quicklinks](/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks)
+- [Page templates](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates)
+- [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components)
+- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github
diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md
@@ -35,3 +35,8 @@ Macros are heavily cached; for any set of input values (both parameters and envi
 Macros can be as simple as just inserting a larger block of text or swapping in contents from another part of MDN, or as complex as building an entire index of content by searching through parts of the site, styling the output, and adding links.
 
 You can read up on our most commonly-used macros on the [Commonly-used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros) page; also, you can browse through the [complete sources for all macros](https://github.com/mdn/yari/tree/main/kumascript/macros). Most of the macro sources have documentation built into them, as comments at the top.
+
+## See also
+
+- [Quicklinks](/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks)
+- [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github
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
@@ -51,7 +51,25 @@ We have defined a front matter key `page-type` to clearly identify the type of M
 
 For the complete list of page types see [The page-type front matter key](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key).
 
-## API landing page
+## Page templates
+
+Below are examples of the various pages you'll find on MDN along with templates that can be used to create new content based on the type of content you will be presenting, including the following pages:
+
+- [API landing pages](#api_landing_page)
+- [API reference page](#api_reference_page)
+- [API reference subpage](#api_reference_subpage)
+- [Conceptual pages](#conceptual_page)
+- [CSS feature reference](#css_feature_reference_page)
+- [CSS module landing page](#css_module_landing_page)
+- [Glossary entry](#glossary_page)
+- [HTML element](#html_element_reference_page)
+- [HTTP header](#http_header_reference_page)
+- [Landing page](#landing_page)
+- [SVG element](#svg_element_reference_page)
+
+Each section includes links to live example pages for that page type.
+
+### API landing page
 
 An **{{Glossary("API")}} landing page** provides an overview of what a particular API does, as well as links to the documentation for each of the interfaces, globals, functions, etc. offered by the API.
 It does not link directly to specific methods or properties within the API's classes, except in the context of the overview text.
@@ -62,74 +80,74 @@ For example, the [Generic Sensor API](https://www.w3.org/TR/generic-sensor/) cov
 In such cases, many of the high level concepts are the same, so it makes no sense to repeat those over multiple landing pages.
 In such a case, it would make more sense in terms of repetition and findability to cover them all under a single "Web sensors" landing page.
 
-### Example
+#### Example
 
 - [WebVR API](/en-US/docs/Web/API/WebVR_API)
 
-### Templates
+#### Templates
 
 - [API landing page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_landing_page_template)
 
-## API reference page
+### API reference page
 
 > **Note:** Also known as an _Interface landing page_.
 
 An **API reference page** lists all the methods, properties, events, and so forth that are members of a particular interface or class.
 It provides an overview of what the class or interface does or is used for, and gives links to the documentation for each of these members.
 It is more granular than an API landing page, which typically links to multiple API reference pages.
 
-### Example
+#### Example
 
 - [Request interface](/en-US/docs/Web/API/Request) of the [Fetch API](/en-US/docs/Web/API/Fetch_API).
 
-### Templates
+#### Templates
 
 - [API reference page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_reference_page_template)
 
-## API reference subpage
+### API reference subpage
 
 An **API reference subpage** is a child of an API reference page.
 It documents a single interface member in detail.
 
-### Examples
+#### Examples
 
 - [`count()` method](/en-US/docs/Web/API/IDBIndex/count) of the [IDBIndex](/en-US/docs/Web/API/IDBIndex) interface (part of the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API))
 - [capabilities property](/en-US/docs/Web/API/VRDisplay/capabilities) of the [VRDisplay](/en-US/docs/Web/API/VRDisplay) interface (part of the [WebVR API](/en-US/docs/Web/API/WebVR_API))
 - [Request() constructor](/en-US/docs/Web/API/Request/Request) of the [Request](/en-US/docs/Web/API/Request) interface (part of the [Fetch API](/en-US/docs/Web/API/Fetch_API))
 - [vrdisplaypresentchange event](/en-US/docs/Web/API/Window/vrdisplaypresentchange_event) (part of the [WebVR API](/en-US/docs/Web/API/WebVR_API), hangs off the [Window](/en-US/docs/Web/API/Window)) interface
 
-### Templates
+#### Templates
 
 - [API method subpage template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_method_subpage_template)
 - [API property subpage template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_property_subpage_template)
 - [API constructor subpage template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_constructor_subpage_template)
 - [API event subpage template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_event_subpage_template)
 
-## HTML element reference page
+### HTML element reference page
 
 An **HTML reference page** lists all the attributes that are available on an HTML element, explains the element's purpose and usage, and provides examples, browser compatibility information, and other important data.
 
-### Example
+#### Example
 
 - [`<video>` element](/en-US/docs/Web/HTML/Element/video)
 
-### Templates
+#### Templates
 
 - [HTML element page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template)
 
-## SVG element reference page
+### SVG element reference page
 
 An **SVG reference page** lists all the attributes that are available on an SVG element, explains the element's purpose and usage, and provides examples, browser compatibility information, and other important data.
 
-### Example
+#### Example
 
 - [\<g> element](/en-US/docs/Web/SVG/Element/g)
 
-### Templates
+#### Templates
 
 - [SVG element page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template)
 
-## CSS module landing page
+### CSS module landing page
 
 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.
 
@@ -139,76 +157,76 @@ The module landing page serves primarily as a _navigation_ page, but also functi
 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 `<easing-function>` 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
+#### 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
+#### 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
+### 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.
 
-### Examples
+#### Examples
 
 - [background-color property](/en-US/docs/Web/CSS/background-color)
 - [:hover pseudo-class](/en-US/docs/Web/CSS/:hover)
 - [@media at-rule](/en-US/docs/Web/CSS/@media)
 
-### Templates
+#### Templates
 
 - [CSS property page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_property_page_template)
 - [CSS selector page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_selector_page_template)
 - [CSS function page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_function_page_template)
 
-## HTTP header reference page
+### HTTP header reference page
 
 An **HTTP header reference page** lists all the available directives that an HTTP header can contain, and explains the header's purpose and usage.
 It also provides examples, browser compatibility information, and other important explanations.
 
-### Example
+#### Example
 
 - [Cache-Control header](/en-US/docs/Web/HTTP/Headers/Cache-Control)
 
-### Templates
+#### Templates
 
 - [HTTP header page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template)
 
-## Conceptual page
+### Conceptual page
 
 A **conceptual page** is a _guide_ page that explains or teaches something.
 Generally, if a page contains primarily prose, and doesn't fall into another page type, it's probably a conceptual page.
 An extended discussion of a topic might be spread across multiple conceptual pages, and linked using [Next](https://github.com/mdn/yari/blob/main/kumascript/macros/Next.ejs) and [Previous](https://github.com/mdn/yari/blob/main/kumascript/macros/Previous.ejs) macros.
 
-### Examples
+#### Examples
 
 - [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API)
 - [Visualizations with Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API)
 - [Cascade and inheritance in CSS](/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance)
 
-## Glossary page
+### Glossary page
 
 A **glossary page** contains a brief explanation of a term, topic, or concept.
 The first paragraph should be a simple, self-contained description of the term, no more than a couple sentences.
 This can be followed by links to further information in the **See also** section.
 If the page grows to more than a screenful or so, it's too long and should be converted to a conceptual page. See [How to write and reference an entry in the glossary](/en-US/docs/MDN/Writing_guidelines/Howto/Write_a_new_entry_in_the_glossary) for more details.
 
-### Examples
+#### Examples
 
 - [DOM](/en-US/docs/Glossary/DOM)
 - [Exception](/en-US/docs/Glossary/Exception)
 - [Hyperlink](/en-US/docs/Glossary/Hyperlink)
 
-### Templates
+#### Templates
 
 - [Glossary page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Glossary_page_template)
 
-## Landing page
+### Landing page
 
 A **landing page** serves as a menu, of sorts, for its subpages, and is therefore primarily a _navigation_ page.
 A landing page layout is typically used for the root page of a tree of pages about a particular topic.
@@ -224,3 +242,8 @@ The list of subpages can be generated automatically using the templates [`Subpag
 - [JavaScript](/en-US/docs/Web/JavaScript)
 - [Learning area](/en-US/docs/Learn)
 - [Contributing to MDN](/en-US/docs/MDN/Contribute)
+
+## See also
+
+- [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components)
+- [Creating code examples in markdown](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide)