Macros: sidebars and links

files/en-us/_redirects.txt

@@ -5412,7 +5412,7 @@
 /en-US/docs/MDN/Contribute/Content/Layout/Reference_page	/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference
 /en-US/docs/MDN/Contribute/Content/Layout/Reference_subpage	/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference
 /en-US/docs/MDN/Contribute/Content/Macros	/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros
-/en-US/docs/MDN/Contribute/Content/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks
+/en-US/docs/MDN/Contribute/Content/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /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
@@ -5445,7 +5445,7 @@
 /en-US/docs/MDN/Contribute/Guidelines/Layout/Reference_page	/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference
 /en-US/docs/MDN/Contribute/Guidelines/Layout/Reference_subpage	/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference
 /en-US/docs/MDN/Contribute/Guidelines/Macros	/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros
-/en-US/docs/MDN/Contribute/Guidelines/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks
+/en-US/docs/MDN/Contribute/Guidelines/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /en-US/docs/MDN/Contribute/Guidelines/Specification_tables	/en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables
 /en-US/docs/MDN/Contribute/Guidelines/Style_guide	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide
 /en-US/docs/MDN/Contribute/Guidelines/Video	/en-US/docs/MDN/Writing_guidelines/Howto/Images_media
@@ -5508,7 +5508,7 @@
 /en-US/docs/MDN/Contribute/Structures/Page_types/HTML_element_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template
 /en-US/docs/MDN/Contribute/Structures/Page_types/HTTP_header_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template
 /en-US/docs/MDN/Contribute/Structures/Page_types/SVG_element_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template
-/en-US/docs/MDN/Contribute/Structures/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks
+/en-US/docs/MDN/Contribute/Structures/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /en-US/docs/MDN/Contribute/Structures/Specification_tables	/en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables
 /en-US/docs/MDN/Contribute/Structures/Syntax_sections	/en-US/docs/MDN/Writing_guidelines/Page_structures/Syntax_sections
 /en-US/docs/MDN/Contribute/Style_guide	/en-US/docs/MDN/Writing_guidelines
@@ -5517,7 +5517,7 @@
 /en-US/docs/MDN/Contribute/Style_guide/Custom_macros	/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros
 /en-US/docs/MDN/Contribute/Style_guide/Live_samples	/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples
 /en-US/docs/MDN/Contribute/Style_guide/Macros	/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros
-/en-US/docs/MDN/Contribute/Style_guide/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks
+/en-US/docs/MDN/Contribute/Style_guide/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /en-US/docs/MDN/Contribute/Style_guide/Specification_tables	/en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables
 /en-US/docs/MDN/Contribute/Tagging	/en-US/docs/MDN/Writing_guidelines/Howto
 /en-US/docs/MDN/Contribute/Tasks	/en-US/docs/MDN/Community/Contributing/Getting_started
@@ -5585,7 +5585,7 @@
 /en-US/docs/MDN/Structures/Page_types/HTML_element_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template
 /en-US/docs/MDN/Structures/Page_types/HTTP_header_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template
 /en-US/docs/MDN/Structures/Page_types/SVG_element_page_template	/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/SVG_element_page_template
-/en-US/docs/MDN/Structures/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks
+/en-US/docs/MDN/Structures/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /en-US/docs/MDN/Structures/Specification_tables	/en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables
 /en-US/docs/MDN/Structures/Syntax_sections	/en-US/docs/MDN/Writing_guidelines/Page_structures/Syntax_sections
 /en-US/docs/MDN/Tools	https://github.com/mdn/yari/tree/main/docs
@@ -5598,6 +5598,7 @@
 /en-US/docs/MDN/User_guide/Troubleshooting_KumaScript_errors	https://github.com/mdn/yari/tree/main/docs/kumascript/troubleshooting-errors.md
 /en-US/docs/MDN/Writing_guidelines/Creating_moving_deleting	/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting
 /en-US/docs/MDN/Writing_guidelines/Howto/Tag	/en-US/docs/MDN/Writing_guidelines/Howto
+/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks	/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars
 /en-US/docs/MDN/Writing_guidelines/Research_technology	/en-US/docs/MDN/Writing_guidelines/Howto/Research_technology
 /en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria	/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion
 /en-US/docs/MDN/Yari	https://github.com/mdn/yari/tree/main/docs

files/en-us/mdn/contribute/index.md

@@ -122,4 +122,4 @@ If you are interested in words _and_ code, you could try your hand at the follow
 
 ## Other useful pages
 
-{{LandingPageListSubPages()}}
+{{LandingPageListSubPages}}

files/en-us/mdn/contribute/processes/index.md

@@ -8,4 +8,4 @@ page-type: landing-page
 
 The MDN documentation project is enormous; there are a vast number of technologies we cover through the assistance of hundreds of contributors from across the world. To help us bring order to chaos, we have standard processes to follow when working on specific documentation-related tasks. Here you'll find guides to those processes.
 
-{{LandingPageListSubPages()}}
+{{LandingPageListSubPages}}

files/en-us/mdn/writing_guidelines/page_structures/index.md

@@ -9,7 +9,7 @@ page-type: landing-page
 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()}}
+{{LandingPageListSubPages}}
 
 ## See also
 

files/en-us/mdn/writing_guidelines/page_structures/links/index.md

@@ -0,0 +1,76 @@
+---
+title: Link macros
+slug: MDN/Writing_guidelines/Page_structures/Links
+page-type: mdn-writing-guide
+---
+
+{{MDNSidebar}}
+
+MDN provides numerous macros to create links to MDN content that are always-up-to-date. In this guide, you will learn about MDN cross-reference macros that can be included in your content to include a single link to another page or a list of links to all of a document's subpages.
+
+## Lists of links
+
+MDN provides macros that create a list of links:
+
+- [`\{{LandingPageListSubPages}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/LandingPageListSubpages.ejs)
+
+  - : Inserts a definition list ({{HTMLelement("dl")}}) of the subpages of the current page, with each page's title as the {{HTMLelement("dt")}} term and its SEO summary as the {{HTMLelement("dd")}} term. The summary is the first paragraph of content.
+
+- [`\{{ListSubpagesForSidebar()}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/ListSubpagesForSidebar.ejs)
+
+  - : When included without parameters, inserts an ordered list of links to the current page's subpages. This macro is most often used within [sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars#sidebars_adding_additional_content) (hence the macro name), where the bullets are not rendered. The first parameter is a slug of the link tree's parent page. The link text is displayed as code. Setting a second parameter to `true` or `1` converts the links to plain text. Setting a third parameter to `true` or `1` adds a link the slug (parent) page at the top of the list with "Overview" as the link text.
+
+- [`\{{QuickLinksWithSubpages`()}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/QuickLinksWithSubpages.ejs)
+
+  - : Creates a set of quicklinks using the current page's (or the specified page's) children as the destinations. This creates hierarchical lists up to two levels deep. The pages' titles are used as the link text and their summaries as tooltips.
+
+### Example link list
+
+To include an ordered list of links which includes this page and its siblings, you write the following:
+
+```md
+\{{ListSubpagesForSidebar("/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}}
+```
+
+This produces:
+
+{{ListSubpagesForSidebar("/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}}
+
+## Cross-reference links
+
+In addition to macros that create lists of links, there are macros that create a single link to cross-reference a CSS, JavaScript, SVG, or HTML feature, including attributes, elements, properties, data types, and APIs. The macros that create single links require at least one parameter: the feature being referenced.
+
+Some of these macros include (see [all the macros on Github](https://github.com/mdn/yari/tree/main/kumascript/macros)):
+
+- [`\{{CSSxRef("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/cssxref.ejs)
+- [`\{{DOMxRef("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/DOMxRef.ejs)
+- [`\{{HTMLElement("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/HTMLElement.ejs)
+- [`\{{glossary("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/Glossary.ejs)
+- [`\{{JSxRef("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/jsxref.ejs)
+- [`\{{SVGAttr("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/SVGAttr.ejs)
+- [`\{{SVGElement("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/SVGElement.ejs)
+- [`\{{HTTPMethod("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/HTTPMethod.ejs)
+- [`\{{HTTPStatus("")}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/HTTPStatus.ejs)
+
+The first parameter of each of these macros is the last section of the slug of the document being referenced. For example, for HTML Elements include `\{{HTMLElement("")}}` with the part of the slug that comes after `Web/HTML/Element/` in the slug being the first parameter. With `\{{CSSxRef("")}}`, it is the part of the slug that comes after `Web/CSS/` in the slug. The link will go to this page.
+
+By default, the text displayed is the linked resource as written in the first parameter, in angle brackets for the case of `\{{HTMLElement()}}`. This may not be what you want. For example, the slug for the range input type is `Web/HTML/Element/input/range`. Including `\{{HTMLElement("input/range")}}` produces "{{HTMLElement("input/range")}}". That is not what you want. Fortunately, all the macros accept additional parameters, so you can provide the text you want to display.
+
+The second parameter, if present, provides the link text. In the input range case, we would write `\{{HTMLElement("input/range", "<code>&lt;input type=&quot;range&quot;&gt;</code>")}}` which produces "{{HTMLElement("input/range", "<code>&lt;input type=&quot;range&quot;&gt;</code>")}}". This particular macro removes the {{htmlelement("code")}} and angle brackets when the second parameter includes a space, so we added the brackets and code back in.
+
+Each macro is different!
+
+To prevent HTML code semantics and CSS code styling, some of the cross-reference macros include a parameter with the value of `"nocode"` to disable this styling.
+
+For example, `\{{CSSxRef("background-color")}}` creates the code link "{{CSSxRef("background-color")}}" and `{{domxref("CSS.supports_static", "check support", "nocode")}}` creates the plain text link "{{domxref("CSS.supports_static", "check support", "nocode")}}".
+
+Make sure to look at the source code to understand how the macro you are using works and to understand the various parameters; while the parameters are generally well documented, exceptions like "don't render as code if the second parameter includes a space" that we saw in the `\{{HTMLElement("")}}` macro is in the code but not otherwise documented.
+
+To learn which parameters each macro supports along with the order of parameters for each macro, the macro's source file, linked above, includes documentation. There is a [list of commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros), each of which outputs links in the main content area of the page.
+
+## See also
+
+- [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros)
+- [Macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github
+- [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros), including BCD macros ( `\{{Compat}}`, `\{{Compat(&lt;feature>)}}`, and `\{{Compat(&lt;feature>, &lt;depth>)}}`) and specification macros (`\{{Specifications}}` / `\{{Specifications(&lt;feature>)}}`)
+- [Banners and notices guide](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices)including the `\{{SeeCompatTable}}`, `\{{Deprecated_Header}}`, and `\{{SecureContext_Header}}` macros.

files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md

@@ -274,7 +274,7 @@ The following macros are included on all reference pages, but are also supported
 
 ## See also
 
-- [Quicklinks](/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks)
+- [Sidebar macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars)
 - [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

files/en-us/mdn/writing_guidelines/page_structures/macros/index.md

@@ -38,5 +38,6 @@ You can read up on our most commonly-used macros on the [Commonly-used macros](/
 
 ## See also
 
-- [Quicklinks](/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks)
+- [Sidebar macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars)
+- [Link macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Links)
 - [List of macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github

files/en-us/mdn/writing_guidelines/page_structures/macros/other/index.md

@@ -25,8 +25,8 @@ We have an assortment of macros that can be used to automatically generate the c
 - [`APIListAlpha`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIListAlpha.ejs) builds a list of the current page's subpages, formatted as a list of API terms, divided up by first letter. There are three parameters. The first is 0 if you want to include all top-level subpages or 1 to leave out subpages with "." in their names. The second and third let you add text to display as part of the name in each link. This can be used to add "<" and ">" for element links, or to add "()" at the end of lists of method names.
 - [`SubpagesWithSummaries`](https://github.com/mdn/yari/blob/main/kumascript/macros/SubpagesWithSummaries.ejs) constructs a definition list of all the immediate children of the current page. There is no other formatting done. You can get a two-column list ready for use as a multi-column landing page using [`LandingPageListSubpages`](https://github.com/mdn/yari/blob/main/kumascript/macros/LandingPageListSubpages.ejs).
 
-### Quicklinks
+### Lists of links
 
-We have one macro specifically designed to create [quicklinks](/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks):
+We have one macro specifically designed to create [lists of links](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) within content:
 
-- [`QuickLinksWithSubpages`](https://github.com/mdn/yari/blob/main/kumascript/macros/QuickLinksWithSubpages.ejs) creates a set of quicklinks comprised of the pages below the current page (or specified page, if one is given). Up to two total levels of depth are generated.
+- [`QuickLinksWithSubpages`](https://github.com/mdn/yari/blob/main/kumascript/macros/QuickLinksWithSubpages.ejs) creates a list of links comprised of the pages below the current page (or specified page, if one is given). Up to two total levels of depth are generated.