Writing Guidelines: quicklinks and surfacing content #31248

estelle · 2023-12-23T08:47:40Z

Added a lot of links between pages within the guidelines to improve searchability.
Removed some wiki-related content
Rewrote quicklinks (not 100% perfect, but the old stuff was for the wiki)

"quicklinks" was an ID. It means something to wiki developers, but nothing to MDN maintainers. I am repurposing the work to mean "a quick link or group of links".

Why https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks is not longer valid:

The example is no longer valid:

moz URL is 404,
we use github instead of ckeditor, and
you can include more than one per page, so bad practice.
So the syntax section had to go.

The bottom section is not valid:

only three examples are listed, there are way more.
there are tons of other type of writing quick links.
link lists are not limited to sidebars
we need to show how you can include a box with text around it.

No, my article is not 100% perfect, but what is there is not helpful. I think this version improves a lot on that. My the content covered by my version can be improved, but is suffices and is better than the current content.

…avigation.

…index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions · 2023-12-23T08:49:11Z

Preview URLs (6 pages)

(comment last updated: 2024-01-03 22:32:33)

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

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

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

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

Co-authored-by: Hamish Willee <[email protected]>

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>

wbamberg · 2023-12-28T05:07:52Z

Approving. Would be good to get a second opinion.

@teoli2003 @wbamberg The Quicklinks updates here are well written and self consistent. My inclination is to merge as "much better", but wanted to give this some visibility.

The changes redefine Quicklinks from being about the <section> that adds your own custom menu to the sidebar to additionally cover the broad set of macros that generate links and lists of links for use in sidebar and in body content - so it includes the XRef macro, list macros, and that section.

I probably would have considered a separate Sidebar topic -it's such a complex topic and much of the material that would be in that now lives here. Maybe a separate one on Xrefs. This is perhaps "too good", making it hard to justify such a split in future, even if it were better.

I think the changes to "quicklinks" here are quite confusing. In terms of our usage, we talk about "sidebar macros" and "xref macros", and it would be better to have two pages with those titles: they don't really have a lot in common.

The term "quicklinks" is a very MDN-jargony term deriving from the id used for the sidebar structures - "sidebar" would be much better - and we never use "quicklinks" or "quick links" to talk about xrefs.

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

estelle · 2023-12-28T23:55:44Z

@wbamberg

The term "quicklinks" is a very MDN-jargony term deriving from the id used for the sidebar structures - "sidebar" would be much better - and we never use "quicklinks" or "quick links" to talk about xrefs.

I updated the page; I provided the origin of the term and divided the content into sidebars and content links, then subdivided into quicklink sidebar macros, otherwise creating sidebars, and quicklinks in content, and xref links.

the original page is not useful, so was hoping to replace it with useful content addressing what the page originally addressed, which made sense when we were wiki-based.

estelle · 2023-12-29T00:07:49Z

After this PR is merged, I will move the file so the slug better matches the title. At that time, i will also edit the in-page example to reflect the new slug.

hamishwillee · 2024-01-02T02:53:40Z

Hi @estelle,
I think we should rewrite this as just "Sidebars" - push "Cross-reference Links" to its own doc and purge the term quicklinks. The stuff on the in-page lists is of very little interest since it so rarely gets used - but we could have a section in common macros (with explanation that they aren't actually very common).

The main reason is that sidebars are important, and there is much more than this to say about them. Having all this information about other link types here makes it difficult to expose that additional information.

What I'm envisaging is first a flat list of the sidebar macros and an explanation of where you apply them. Then additional info on what you need to do to add things to the default API overview - i.e. the GroupData.json. Last of all the instructions on the quicklinks <section>.

There's this post by @wbamberg That would need to be captured in some shape or form https://discourse.mozilla.org/t/defaultapisidebar-apiref-and-groupdata/40210 .

Appreciate that this makes a relatively constrained job you started on much bigger. I'm happy to do this as follow on to your work, in which case I'd suggest you just rename this sidebar and I'll merge and take it forward. Up to you.

@wbamberg is the MDN sidebar expert for any questions and would be a better reviewer than me. Particularly since I am away at the end of the month. I have added him.

wbamberg · 2024-01-02T18:18:37Z

Basically I agree with everything Hamish says in #31248 (comment).

I think we should rewrite this as just "Sidebars" - push "Cross-reference Links" to its own doc and purge the term quicklinks.

I think this would be better. But I also think what's in this PR as it stands is better than the current page, so would be OK to merge it as is and make a follow up.

Also though, I wonder how much value we get out of these meta-docs. I have personally never read this page, and I doubt anyone really learns how to write for MDN using the meta-docs (page templates aside). So how much should we invest in improving them?

I wish wish wish we could improve the platform so authors didn't have to do all this manual labour. Why do authors even have to add macro calls manually? Why can't Yari work this out? Would much rather put the time into that.

wbamberg · 2024-01-02T18:22:13Z

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

 slug: MDN/Writing_guidelines/Page_structures/Quicklinks
 page-type: mdn-writing-guide
 ---

 {{MDNSidebar}}

-MDN supports adding quicklinks to pages; these are boxes containing a potentially hierarchical list of links to other pages on MDN or to pages off-site.
-This article describes how to create quicklinks boxes.
+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.


"can and often should" is not helpful advice without explaining somewhere what "often" means. IMO you should use macros for sidebars, and for xrefs when you are linking to a reference page for a concrete web platform feature (and an xref for that feature exists).

wbamberg · 2024-01-02T18:22:46Z

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


-```html
+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.


Like Hamish says, the term "quicklinks" doesn't add anything here.

wbamberg · 2024-01-02T18:26:35Z

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

+### 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:


I think this is bad advice. A given page in a given bit of the site should have a given sidebar - so e.g. a page in CSS should have CSSRef. All pages in that bit of the site should have the same sidebar.

If you want to add links to a page in CSS, you should want to add those links to all pages in CSS. So you should handle this by modifying the sidebar macro.

In general, if we want to document "manual quicklinks" at all, we should document them as an legacy pattern that people will sometimes find in parts of the site that don't yet have sidebar macros defined for them.

wbamberg · 2024-01-02T18:27:19Z

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

+
+- `\{{CSSRef}}`
+
+  - : Present on every CSS page, it generates different CSS sidebars depending on tags, like "properties", "selectors", "at-rules", "descriptors", etc., included in the page.


No, it always generates the same sidebar.

wbamberg · 2024-01-02T18:34:47Z

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

+
+  - : Present on every CSS page, it generates different CSS sidebars depending on tags, like "properties", "selectors", "at-rules", "descriptors", etc., included in the page.
+
+- `\{{ListSubpagesForSidebar(<parameters>)}}`


ListSubpagesForSidebar does not make a sidebar, it makes an ordered list of links, that can be included in a sidebar. (that is, it does not make a section with a quick_links ID, which is the magic that makes a blob of HTML get treated as a sidebar by Yari).

wbamberg · 2024-01-02T18:44:58Z

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

+- `\{{HTTPMethod("")}}`
+- `\{{HTTPStatus("")}}`
+
+All the macros accept additional parameters. The second parameter, if present, provides the link text. By default, these links are displayed like code, in a monospace font. To prevent HTML code semantics and CSS code styling, the `"nocode"` parameter can be included as the third value in the macro call.


Unfortunately, the different xref macros don't all have the same API, so it's hard to make general statements about them. For example, CSSXref doesn't support "nocode" at all, while for those that do, like DOMXref, it is more often the fourth parameter than the third. I think it would be better either to document the parameters completely, or just to refer to the source files, which should always include documentation: https://github.com/mdn/yari/blob/bda844f7dd745f7e3ac15736c3c884fc26507464/kumascript/macros/DOMxRef.ejs#L1-L15.

wbamberg · 2024-01-02T18:46:32Z

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

+
+All the macros accept additional parameters. The second parameter, if present, provides the link text. By default, these links are displayed like code, in a monospace font. To prevent HTML code semantics and CSS code styling, the `"nocode"` parameter can be included as the third value in the macro call.
+
+For example, `\{{CSSxRef("background-color")}}` creates the code link "{{CSSxRef("background-color")}}" and `\{{CSSxRef("At-rules", "CSS at-rule", "nocode")}}` creates the plain text link "{{CSSxRef("At-rules", "CSS at-rule", "nocode")}}".


https://developer.mozilla.org/en-US/docs/Web/CSS/At-rules doesn't exist. Also I think it is an anti-pattern to use xefs to link to guide pages, although we are not very clear about this.

estelle · 2024-01-03T22:32:44Z

I addressed @wbamberg and @hamishwillee's comments. I'll merge this now, and start working on breaking guidelines into two pages, and rename quicklinks to sidebars. (see
Macros: split quicklinks into sidebars and link pages #31506)

* 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]>

estelle and others added 18 commits December 21, 2023 11:16

Writing guidelines: structure the page templates sectionfor ease of n…

73c9bec

…avigation.

alt for images

88f98be

update links from wiki to github

428ba59

see also to quicklinks page and list of macros

5d48a9a

page types: added templates and see also sections

dea7cff

Added see also to page structure (which was just a list of subpages)

dea6247

Explanation of quicklinks

9398730

Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…

cc9f6f4

…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/…

06039b0

…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/…

079f9c6

…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/…

947e2d1

…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/…

c1017f8

…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/…

da5bb77

…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/…

d6bb774

…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/…

384b730

…index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

twaks

0cd17c6

Update files/en-us/mdn/writing_guidelines/page_structures/quicklinks/…

ff9ac49

…index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

twaks

51688cf

estelle requested a review from a team as a code owner December 23, 2023 08:47

estelle requested review from hamishwillee and removed request for a team December 23, 2023 08:47

github-actions bot added the Content:Meta Content in the meta docs label Dec 23, 2023

hamishwillee reviewed Dec 26, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/index.md Outdated Show resolved Hide resolved

hamishwillee added 2 commits December 27, 2023 09:36

page components desc.

12abd13

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

3e69df5

hamishwillee reviewed Dec 26, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Dec 26, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Dec 26, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Show resolved Hide resolved

hamishwillee reviewed Dec 26, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Dec 27, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Outdated Show resolved Hide resolved

estelle added 2 commits December 27, 2023 17:12

make it clearer

2ea66fa

grammar

7430a93

hamishwillee reviewed Dec 28, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Outdated Show resolved Hide resolved

hamishwillee reviewed Dec 28, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Show resolved Hide resolved

Apply suggestions from code review

f61c83c

Co-authored-by: Hamish Willee <[email protected]>

github-actions bot reviewed Dec 28, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Show resolved Hide resolved

hamishwillee reviewed Dec 28, 2023

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/quicklinks/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

b13f87e

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Change to sidebars and other link macros

8eabb92

github-actions bot reviewed Dec 28, 2023

View reviewed changes

estelle added 2 commits December 28, 2023 15:59

escape macro

d8ddcb3

escape macro

70176de

hamishwillee requested a review from wbamberg January 2, 2024 02:52

wbamberg reviewed Jan 2, 2024

View reviewed changes

estelle added 2 commits January 3, 2024 14:21

addressed will's comments

13dd0ca

typo

5571aff

estelle merged commit 95766bd into mdn:main Jan 3, 2024
7 checks passed

This was referenced Jan 4, 2024

Macros: split quicklinks into sidebars and link pages #31506

Closed

Macros: sidebars and links #31600

Closed

This was referenced Jan 12, 2024

Yari macro explanations: Sidebars and cross reference links estelle/content#3

Closed

Macros: explain sidebars & cross reference links. remove quicklinks lingo #31689

Merged

estelle deleted the guidelines branch March 26, 2024 18:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Writing Guidelines: quicklinks and surfacing content #31248

Writing Guidelines: quicklinks and surfacing content #31248

estelle commented Dec 23, 2023 •

edited

Loading

github-actions bot commented Dec 23, 2023 •

edited

Loading

wbamberg commented Dec 28, 2023

estelle commented Dec 28, 2023

estelle commented Dec 29, 2023

hamishwillee commented Jan 2, 2024

wbamberg commented Jan 2, 2024

wbamberg Jan 2, 2024

wbamberg Jan 2, 2024

wbamberg Jan 2, 2024 •

edited

Loading

wbamberg Jan 2, 2024

wbamberg Jan 2, 2024

wbamberg Jan 2, 2024

wbamberg Jan 2, 2024

estelle commented Jan 3, 2024 •

edited

Loading


		```html
		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.


		- `\{{CSSRef}}`

		- : Present on every CSS page, it generates different CSS sidebars depending on tags, like "properties", "selectors", "at-rules", "descriptors", etc., included in the page.


		- : Present on every CSS page, it generates different CSS sidebars depending on tags, like "properties", "selectors", "at-rules", "descriptors", etc., included in the page.

		- `\{{ListSubpagesForSidebar(<parameters>)}}`


		All the macros accept additional parameters. The second parameter, if present, provides the link text. By default, these links are displayed like code, in a monospace font. To prevent HTML code semantics and CSS code styling, the `"nocode"` parameter can be included as the third value in the macro call.

		For example, `\{{CSSxRef("background-color")}}` creates the code link "{{CSSxRef("background-color")}}" and `\{{CSSxRef("At-rules", "CSS at-rule", "nocode")}}` creates the plain text link "{{CSSxRef("At-rules", "CSS at-rule", "nocode")}}".

Writing Guidelines: quicklinks and surfacing content #31248

Writing Guidelines: quicklinks and surfacing content #31248

Conversation

estelle commented Dec 23, 2023 • edited Loading

github-actions bot commented Dec 23, 2023 • edited Loading

wbamberg commented Dec 28, 2023

estelle commented Dec 28, 2023

estelle commented Dec 29, 2023

hamishwillee commented Jan 2, 2024

wbamberg commented Jan 2, 2024

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

wbamberg Jan 2, 2024 • edited Loading

Choose a reason for hiding this comment

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

wbamberg Jan 2, 2024

Choose a reason for hiding this comment

estelle commented Jan 3, 2024 • edited Loading

estelle commented Dec 23, 2023 •

edited

Loading

github-actions bot commented Dec 23, 2023 •

edited

Loading

wbamberg Jan 2, 2024 •

edited

Loading

estelle commented Jan 3, 2024 •

edited

Loading