Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Writing Guidelines: quicklinks and surfacing content #31248

Merged
merged 40 commits into from
Jan 3, 2024
Merged
Show file tree
Hide file tree
Changes from 31 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
73c9bec
Writing guidelines: structure the page templates sectionfor ease of n…
estelle Dec 21, 2023
88f98be
alt for images
estelle Dec 21, 2023
428ba59
update links from wiki to github
estelle Dec 21, 2023
5d48a9a
see also to quicklinks page and list of macros
estelle Dec 21, 2023
dea7cff
page types: added templates and see also sections
estelle Dec 21, 2023
dea6247
Added see also to page structure (which was just a list of subpages)
estelle Dec 21, 2023
9398730
Explanation of quicklinks
estelle Dec 22, 2023
cc9f6f4
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
06039b0
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
079f9c6
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
947e2d1
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
c1017f8
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
da5bb77
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
d6bb774
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
384b730
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
0cd17c6
twaks
estelle Dec 23, 2023
ff9ac49
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
estelle Dec 23, 2023
51688cf
twaks
estelle Dec 23, 2023
12abd13
page components desc.
hamishwillee Dec 26, 2023
3e69df5
Update files/en-us/mdn/writing_guidelines/page_structures/index.md
hamishwillee Dec 26, 2023
b24e540
Update files/en-us/mdn/writing_guidelines/page_structures/page_types/…
hamishwillee Dec 26, 2023
b4826d9
move macros to see also section
estelle Dec 27, 2023
12f97da
move macros to see also section
estelle Dec 27, 2023
89dfda5
Update files/en-us/mdn/writing_guidelines/page_structures/macros/comm…
estelle Dec 27, 2023
1fdb573
Update files/en-us/mdn/writing_guidelines/page_structures/macros/comm…
estelle Dec 27, 2023
6a1cc6a
the bot and this PR hate me
estelle Dec 27, 2023
062fc22
Update files/en-us/mdn/writing_guidelines/page_structures/macros/comm…
estelle Dec 27, 2023
be4753a
happiness
estelle Dec 27, 2023
ca6e541
Apply suggestions from code review
estelle Dec 27, 2023
5c7b0bc
Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…
hamishwillee Dec 27, 2023
e5b68ce
header levels
estelle Dec 27, 2023
2ea66fa
make it clearer
estelle Dec 28, 2023
7430a93
grammar
estelle Dec 28, 2023
f61c83c
Apply suggestions from code review
estelle Dec 28, 2023
b13f87e
Apply suggestions from code review
hamishwillee Dec 28, 2023
8eabb92
Change to sidebars and other link macros
estelle Dec 28, 2023
d8ddcb3
escape macro
estelle Dec 28, 2023
70176de
escape macro
estelle Dec 29, 2023
13dd0ca
addressed will's comments
estelle Jan 3, 2024
5571aff
typo
estelle Jan 3, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions files/en-us/mdn/writing_guidelines/page_structures/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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(<feature>)}}` / `\{{Compat(<feature>, <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.
estelle marked this conversation as resolved.
Show resolved Hide resolved

- `\{{Specifications}}` / `\{{Specifications(<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
Original file line number Diff line number Diff line change
Expand Up @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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.
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved

### 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.
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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)
Loading