diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index a7dd03bd26133a9..d0b063fd4089fd0 100644 --- a/files/en-us/_redirects.txt +++ b/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 diff --git a/files/en-us/mdn/contribute/index.md b/files/en-us/mdn/contribute/index.md index 79f0aa56f049848..ce4a170266f02cd 100644 --- a/files/en-us/mdn/contribute/index.md +++ b/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}} diff --git a/files/en-us/mdn/contribute/processes/index.md b/files/en-us/mdn/contribute/processes/index.md index d9e83420267230d..b37ea9b5f26c525 100644 --- a/files/en-us/mdn/contribute/processes/index.md +++ b/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}} 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 146ca69a878f6b9..617fe2b23a1d979 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/index.md +++ b/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 diff --git a/files/en-us/mdn/writing_guidelines/page_structures/links/index.md b/files/en-us/mdn/writing_guidelines/page_structures/links/index.md new file mode 100644 index 000000000000000..88c777233fbb1c8 --- /dev/null +++ b/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", "<input type="range">")}}` which produces "{{HTMLElement("input/range", "<input type="range">")}}". 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(<feature>)}}`, and `\{{Compat(<feature>, <depth>)}}`) and specification macros (`\{{Specifications}}` / `\{{Specifications(<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. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md index a40af4a787b766a..bea5e4bca803399 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md +++ b/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 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 index 4da195ad1256e90..66ac12b8cfb9368 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md +++ b/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 diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/other/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/other/index.md index 8f80ee2d91b43a5..a230739d73c5a69 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/other/index.md +++ b/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. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md b/files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md deleted file mode 100644 index da326177159d64b..000000000000000 --- a/files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Sidebars and other link macros -slug: MDN/Writing_guidelines/Page_structures/Quicklinks -page-type: mdn-writing-guide ---- - -{{MDNSidebar}} - -MDN supports adding links and lists of links in sidebars and within the main content of a page. You can and often **should** use macros to generate links. -This article describes how to use the different MDN macros, demonstrating how to include sidebars to MDN pages and add always-up-to-date and maintained links within your content. Quickly. - -In this guide, you will learn how to create a sidebar of links by just including a macro and how to add how to use those same macros to create sidebars with additional text. You will also learn about cross-reference macros to add links to other pages and macros to add lists of links to pages and subpages. - -## Creating sidebars - -Every page has a sidebar. These sidebars are created by Quicklinks. **Quicklinks** are MDN macros that create boxes containing a potentially hierarchical list of links to other pages on this site. They are mainly used in sidebars, though can also be used in the main content area. - -> **Note:** The "Quicklinks" names comes from the ID used in server-side scripts to identify these content areas and may come from a shortening of [`id="Quick_links"`](#sidebars_adding_additional_content). - -When a Quicklink is included, the server creates a section of content containing an unordered list of links. The links created, where they are displayed, and how they are displayed depend on the macro used and the parameters included in the markdown macro call. Some quicklinks include links based on a directory's structure or page type. Others include a list of predefined pages that are hard-coded in Yari. - -### Fully macro-generated sidebars - -To include only the content generated by the Quicklink macro, the macro is added immediately after the frontmatter and before the content on every page. For example, the first lines of this document are written as: - -```md ---- -title: Sidebars and other link macros -slug: MDN/Writing_guidelines/Page_structures/Quicklinks -page-type: mdn-writing-guide ---- - -\{{MDNSidebar}} -``` - -The `\{{MDNSidebar}}` is a Quicklink macro that adds the MDN sidebar to the page. Because we only want the content from the macro, and no additional content in our sidebar, the macro is placed immediately after the frontmatter. - -Here are a few other Quicklink macros, with what they do: - -- `\{{CSSRef}}` - - - : Present on every CSS page, it generates a CSS sidebar that includes links for modules, properties, selectors, combinators, pseudo-classes, pseudo-elements, at-rules, functions, and types, with all the link lists collapsed except for the link list for the current page type. - -- `\{{DefaultAPISidebar("")}}` - - - : The API sidebar displayed for overview pages; the single parameter is the name of the API group in GroupData. - -- Other sidebar "quicklink" macros - - : Other sidebar generating macro calls include `\{{GlossarySidebar}}`, `\{{LearnSidebar}}`,`\{{HTMLSidebar}}`, `\{{HTTPSidebar}}`, `\{{PWASidebar}}`, etc. - -The appropriate macro to use depends on the page type and is listed in the template for each page type. - -### Sidebars: adding additional content - -Each of the Quicklink macros listed above creates a predefined sidebar structure. -If you need to append links before or after the sidebar structure generated by the macro, you can do so by: - -1. Remove any sidebar Quicklink macro appearing immediately after the frontmatter and before the content, as each document can only have one sidebar. -2. At the end of the markdown file, add an HTML {{htmlelement("section")}} element and add `id="Quick_links"` (Hence the name "Quicklinks") to the opening tag. -3. Nest both the macro and any additional links within this `
`. - -For example, adding the following at the end of a markdown file (and removing any sidebar macro from below the frontmatter), will create a sidebar containing the links to all the ARIA role pages, preceded by a link to the ARIA roles overview page: - -```md - -``` - -> **Note:** This `
` must be appended to the end of the page, instead of between the frontmatter and the page content. - -You can also fully craft a sidebar with more than one Quicklinks macro, without including a Quicklinks macro, with cross reference macros, or any combination of macros and markdown. The steps to creating a sidebar without a Quicklinks macro are similar to the steps for the ARIA example above: - -1. Remove any sidebar Quicklink macro appearing immediately after the frontmatter and before the content. -2. At the end of the markdown file, add the following HTML markup as the last content of the markdown file: ``. -3. Add an unordered list of links written in markdown between the opening and closing `
` tags. - -```md - -``` - -> **Note:** To include content in your sidebar along with a quicklink macro, the extra content and the quicklinks macro must be placed at the end of the document. Only one sidebar is created per page, so any macro listed after the frontmatter must be removed. - -## Main content area links - -Macros are not limited to sidebars or even to long lists of links. - -### Lists of links - -Quicklink macros can also be used to add lists of links to the main area of the page. The following macros do not create a sidebar. They create a list of links. They can be included in the content of the page or within a sidebar. - -- `\{{LandingPageListSubPages()}}` - - - : 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 optional parameter accepts the slug or the parent page of the directory of pages to output instead of the subpages of the current page. - -- `\{{ListSubpagesForSidebar()}}` - - - : Inserts a tree of subpages of the slug of the pages specified as the first parameter. Include two parameters, with the second being `true` or `1`, to display the links as plain text instead of like code. Include a third parameter, set to `true` or `1`, to include the parent page at the top of the list with the link text "Overview". - -To add include either list of links as part of a sidebar, include the macro as described in [Sidebars: adding additional content](#sidebars-adding-additional-content). - -### Cross-reference links - -In addition to macros that create lists of links, there are macros that quickly 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) - -All the macros accept additional parameters. By default, the text displayed is the linked resource as written in the first parameter. The second parameter, if present, provides the link text. In most cases, these links are displayed like code, in a monospace font. 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")}}". - -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. - -## Underlying code for MDN macros - -There are around 100 [available macros](https://github.com/mdn/yari/tree/main/kumascript/macros). Here are a few standard macros for generating quicklinks and an example of a hardcoded Yari macro list. - -- [`CSSRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/CSSRef.ejs) - - : Builds the standard quicklinks for CSS Reference pages. -- [`HTMLSidebar`](https://github.com/mdn/yari/blob/main/kumascript/macros/HTMLSidebar.ejs) - - : Builds the standard quicklinks for HTML Reference pages. -- [`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. - -## 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(<feature>)}}`, and `\{{Compat(<feature>, <depth>)}}`) and specification macros (`\{{Specifications}}` / `\{{Specifications(<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. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md new file mode 100644 index 000000000000000..b7c635923499226 --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md @@ -0,0 +1,118 @@ +--- +title: Sidebars +slug: MDN/Writing_guidelines/Page_structures/Sidebars +page-type: mdn-writing-guide +--- + +{{MDNSidebar}} + +All the pages MDN community members may edit include a sidebar. These sidebars are created using macros. +This article describes the different MDN sidebar macros, demonstrating how to include sidebars on MDN pages. + +In this guide, you will learn how to create a sidebar of links by just including a macro and how to create sidebars with additional content. + +## Creating sidebars + +Every page has a sidebar. These sidebars appear because a sidebar macro has been included on the pages that create a potentially hierarchical list of links to other pages on this site. + +When a sidebar macro is included, the server creates a section of content containing an unordered list of links. The links created, where they are displayed, and how they are displayed depend on the macro used and the parameters included in the markdown macro call. Some sidebars include links based on a directory's structure or page type. Others include a list of predefined pages that are hard-coded in Yari. + +### Including single-macro sidebars + +To include only the content generated by a sidebar macro, the macro is added immediately after the frontmatter and before the content on every page. Frontmatter is where we specify the metadata and options for each page. The frontmatter on MDN includes the page title, slug, and page type, along with other information based on the page type, such as specification URL, browser compatibility object, etc. + +For example, the first lines of this document are written as: + +```md +--- +title: Sidebars +slug: MDN/Writing_guidelines/Page_structures/Sidebars +page-type: mdn-writing-guide +--- + +\{{MDNSidebar}} +``` + +The frontmatter is the content between the dashes. The sidebar macro is included immediately after the frontmatter. The `\{{MDNSidebar}}` is a sidebar macro that adds the MDN sidebar to the page. When the sidebar is a single macro call, the macro is placed immediately after the frontmatter. + +Here are a few other sidebar macros, with what they do: + +- `\{{CSSRef}}` + + - : Present on every CSS page, it generates a CSS sidebar that includes links for modules, properties, selectors, combinators, pseudo-classes, pseudo-elements, at-rules, functions, and types, with all the link lists collapsed except for the link list for the current page type. + +- `\{{DefaultAPISidebar("")}}` + + - : The API sidebar displayed for overview pages; the single parameter is the name of the API group in GroupData. + +- `\{{GlossarySidebar}}` + + - : Present on every glossary page, it generates the glossary sidebar that includes the list of top-level glossary terms (not the disambiguated terms) preceded by a section filter. + +- `\{{LearnSidebar}}` + + - : Present on every page within the Learn section except for common questions and how-to pages (which use the `QuickLinksWithSubpages` macro), it generates a sidebar based on the [hard-coded links](https://github.com/mdn/yari/blob/main/kumascript/macros/LearnSidebar.ejs) present in the Yari macro file. This macro is not based on file structure. + +- `\{{HTMLSidebar}}` + + - : Generates the sidebar for HTML documentation, including tutorials, references, and guides. The macro includes calls to the `\{{ ListSubpagesForSidebar}}` macro for the element and attribute reference sections, while the tutorial and guide [links are hard-coded](https://github.com/mdn/yari/blob/main/kumascript/macros/HTMLSidebar.ejs). + +- `\{{HTTPSidebar}}` + + - : Generates the sidebar for [HTTP documentation](/en-US/docs/Web/HTTP), including guides and reference docs. + +- `\{{PWASidebar}}` + + - : Generates the sidebar for progressive web app (PWA) documentation. The macro lists all the pages (it is not based on file structure). + +The appropriate macro to use depends on the [page type](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). The [template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) for each page type includes the appropriate macro for that page type. + +### Creating new sidebars + +You should use existing sidebar macros, without adding any content to them. If you are creating a whole new section of content, create a [macro for your sidebar](https://github.com/mdn/yari/blob/main/kumascript/macros/) in Yari. + +In the unlikely event that you need to create a temporary sidebar, this section explains how that can be done. Do not submit your temporary sidebar for PR review as it will not be approved. + +If you need to create a new sidebar macro, you can do so in your development environment by following these steps: + +1. Remove the sidebar macro appearing immediately after the frontmatter and before the content, as each document can only have one sidebar. +2. At the end of the markdown file, add an HTML {{htmlelement("section")}} element setting the `id` of the element to `Quick_links`. +3. Add a `\{{ListSubpagesForSidebar()}}` macro with the slug of the directory for each section of content you want to include in the sidebar, along with additional markdown, between the opening and closing `
` tags. + +For example, when developing the Accessibility sidebar, we could have temporarily included the following at the end of a markdown file (and removing any sidebar macro from below the frontmatter), will create a sidebar containing the links to all the ARIA role pages, preceded by a link to the ARIA roles overview page: + +```md + +``` + +If listed as the last content in the page, Yari, the engine that renders MDN, recognizes the `Quick_links` ID in the opening tag and converts the content of the identified `
` into a sidebar. + +The `\{{ListSubpagesForSidebar()}}` macro inserts the tree of subpages for the page whose slug is specified as the first parameter. The above creates a sidebar containing a link to all the Accessibilty documents, followed by the ARIA roles and attributes. + +Once you have determined the links to include in your sidebar, submit a pull request to [Yari with your proposed sidebar macro](https://github.com/mdn/yari/blob/main/kumascript/macros/). + +> **Note:** This `
` must be appended to the end of the document, instead of between the frontmatter and the page content. Only one sidebar is created per page, so any macro listed after the frontmatter must be removed. + +The [macro source code](https://github.com/mdn/yari/tree/main/kumascript/macros) is on Github. Each macro includes the documentation for itself, including parameters, if any. + +## See also + +- [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros) +- [Content link macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Links) +- [Page section macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros) +- [Banners and notices macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices) +- [All macros](https://github.com/mdn/yari/tree/main/kumascript/macros) on Github