Markdown conversion Quicklinks

[hamishwillee]

A quicklinks section creates a page-specific addition to the sidebar of "related topics".

It looks as shown below. It takes a list, which may be manually created or generated from a macro.

<section id="Quick_links">
<ul>
  <li>{{domxref("MediaDevices.selectAudioOutput()")}}</li>
  <li><a href="https://html.spec.whatwg.org/multipage/interaction.html#transient-activation">HTML Living Standard > Transient activation</a></li>
</ul>
</section>

This does not convert to markdown; the section is html, so the content is forced to be HTML.

My preference is that we allow the content to be a markdown list.

<section id="Quick_links">
- {{domxref("MediaDevices.selectAudioOutput()")}}
- [HTML Living Standard > Transient activation](href="https://html.spec.whatwg.org/multipage/interaction.html#transient-activation)
</section>

I have no strong feeling about how we delinate the section - i.e. using something other than a section fine with me.

Thoughts, suggestions?

FYI @wbamberg

[wbamberg]

Yes, Quick_links is the way to put content in the sidebar. Usually this is done inside a macro (e.g. https://github.com/mdn/yari/blob/5e3df01e21dfcaf3d905bf4ae0a23d858c5b0525/kumascript/macros/LearnSidebar.ejs#L1828) but (because this is MDN and you can do just anything) you can also specify it directly in content, as in these cases.

Note though that Quick_links doesn't add to an existing sidebar. If you have more than one id="Quick_links", Yari uses the first one and throws any subsequent ones away. Quick_links is like Highlander in that there can be only one.

I think we should stop using Quick_links outside macros.

As far as I can tell, here are all the pages which use it like that:

https://developer.mozilla.org/en-US/docs/web/xpath

https://developer.mozilla.org/en-US/docs/web/xpath/comparison_with_css_selectors

https://developer.mozilla.org/en-US/docs/web/exslt

https://developer.mozilla.org/en-US/docs/web/xslt

https://developer.mozilla.org/en-US/docs/web/events/mouse_gesture_events

https://developer.mozilla.org/en-US/docs/web/events

https://developer.mozilla.org/en-US/docs/web/events/event_handlers

https://developer.mozilla.org/en-US/docs/web/events/using_device_orientation_with_3d_transforms

https://developer.mozilla.org/en-US/docs/web/events/creating_and_triggering_events

https://developer.mozilla.org/en-US/docs/web/events/orientation_and_motion_data_explained

https://developer.mozilla.org/en-US/docs/web/events/detecting_device_orientation

https://developer.mozilla.org/en-US/docs/web/accessibility/aria

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/contentinfo_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/heading_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/application_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/figure_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/region_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/form_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/textbox_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/mark_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/feed_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/complementary_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/dialog_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/checkbox_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/document_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/button_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/grid_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/table_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/role_img

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/article_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/listitem_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/row_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/list_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/banner_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/main_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/comment_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/alert_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/listbox_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/navigation_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/switch_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/rowgroup_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/cell_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/tab_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/tabpanel_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/suggestion_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/aria_timer_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/gridcell_role

https://developer.mozilla.org/en-US/docs/web/accessibility/aria/roles/search_role

https://developer.mozilla.org/en-US/docs/related/imsc/basics

https://developer.mozilla.org/en-US/docs/related/imsc

https://developer.mozilla.org/en-US/docs/related/imsc/timing_in_imsc

https://developer.mozilla.org/en-US/docs/related/imsc/subtitle_placement

https://developer.mozilla.org/en-US/docs/related/imsc/namespaces

https://developer.mozilla.org/en-US/docs/related/imsc/mapping_video_time_codes_to_imsc

https://developer.mozilla.org/en-US/docs/related/imsc/imsc_and_other_standards

https://developer.mozilla.org/en-US/docs/related/imsc/styling

https://developer.mozilla.org/en-US/docs/related/imsc/using_the_imscjs_polyfill

https://developer.mozilla.org/en-US/docs/mdn/at_ten

https://developer.mozilla.org/en-US/docs/glossary/hotlink

https://developer.mozilla.org/en-US/docs/glossary/blink

https://developer.mozilla.org/en-US/docs/glossary/second-level_domain

https://developer.mozilla.org/en-US/docs/glossary/accessibility_tree

https://developer.mozilla.org/en-US/docs/glossary/css_selector

https://developer.mozilla.org/en-US/docs/glossary/https

https://developer.mozilla.org/en-US/docs/glossary/database

https://developer.mozilla.org/en-US/docs/glossary/fork

https://developer.mozilla.org/en-US/docs/glossary/user_agent

https://developer.mozilla.org/en-US/docs/glossary/rtsp

https://developer.mozilla.org/en-US/docs/glossary/ssl

https://developer.mozilla.org/en-US/docs/glossary/pop

https://developer.mozilla.org/en-US/docs/glossary/cacheable

https://developer.mozilla.org/en-US/docs/glossary/gzip_compression

https://developer.mozilla.org/en-US/docs/glossary/type_coercion

https://developer.mozilla.org/en-US/docs/glossary/http_header

https://developer.mozilla.org/en-US/docs/glossary

https://developer.mozilla.org/en-US/docs/glossary/mathml

https://developer.mozilla.org/en-US/docs/glossary/microsoft_edge

https://developer.mozilla.org/en-US/docs/glossary/bootstrap

https://developer.mozilla.org/en-US/docs/glossary/call_stack

https://developer.mozilla.org/en-US/docs/glossary/static_method

https://developer.mozilla.org/en-US/docs/glossary/wrapper

https://developer.mozilla.org/en-US/docs/glossary/python

https://developer.mozilla.org/en-US/docs/glossary/reporting_directive

https://developer.mozilla.org/en-US/docs/glossary/endianness

https://developer.mozilla.org/en-US/docs/glossary/cryptography

https://developer.mozilla.org/en-US/docs/glossary/grid_tracks

https://developer.mozilla.org/en-US/docs/glossary/fetch_directive

https://developer.mozilla.org/en-US/docs/glossary/crawler

https://developer.mozilla.org/en-US/docs/glossary/public-key_cryptography

https://developer.mozilla.org/en-US/docs/glossary/iife

https://developer.mozilla.org/en-US/docs/glossary/cryptographic_hash_function

https://developer.mozilla.org/en-US/docs/glossary/local_variable

https://developer.mozilla.org/en-US/docs/glossary/primitive

https://developer.mozilla.org/en-US/docs/glossary/forbidden_header_name

https://developer.mozilla.org/en-US/docs/glossary/cipher

https://developer.mozilla.org/en-US/docs/glossary/simd

https://developer.mozilla.org/en-US/docs/glossary/favicon

https://developer.mozilla.org/en-US/docs/glossary/scrollport

https://developer.mozilla.org/en-US/docs/glossary/symbol

https://developer.mozilla.org/en-US/docs/glossary/key

https://developer.mozilla.org/en-US/docs/glossary/latency 

https://developer.mozilla.org/en-US/docs/glossary/semantics

https://developer.mozilla.org/en-US/docs/glossary/first-class_function

https://developer.mozilla.org/en-US/docs/glossary/php

https://developer.mozilla.org/en-US/docs/glossary/css_preprocessor

https://developer.mozilla.org/en-US/docs/glossary/type_conversion

https://developer.mozilla.org/en-US/docs/glossary/fetch_metadata_request_header

https://developer.mozilla.org/en-US/docs/glossary/http_2

https://developer.mozilla.org/en-US/docs/glossary/spa

https://developer.mozilla.org/en-US/docs/glossary/number

https://developer.mozilla.org/en-US/docs/glossary/cross_axis

https://developer.mozilla.org/en-US/docs/glossary/symmetric-key_cryptography

https://developer.mozilla.org/en-US/docs/glossary/global_object

https://developer.mozilla.org/en-US/docs/glossary/input_method_editor

https://developer.mozilla.org/en-US/docs/glossary/browser

https://developer.mozilla.org/en-US/docs/glossary/internationalization_and_localization

https://developer.mozilla.org/en-US/docs/glossary/flexbox

https://developer.mozilla.org/en-US/docs/glossary/markup

https://developer.mozilla.org/en-US/docs/glossary/representation_header

https://developer.mozilla.org/en-US/docs/glossary/type

https://developer.mozilla.org/en-US/docs/glossary/http_3

https://developer.mozilla.org/en-US/docs/glossary/ltr

https://developer.mozilla.org/en-US/docs/glossary/tls

https://developer.mozilla.org/en-US/docs/glossary/identifier

https://developer.mozilla.org/en-US/docs/glossary/webassembly

https://developer.mozilla.org/en-US/docs/glossary/tcp

https://developer.mozilla.org/en-US/docs/glossary/null

https://developer.mozilla.org/en-US/docs/glossary/whitespace

https://developer.mozilla.org/en-US/docs/glossary/web_performance

https://developer.mozilla.org/en-US/docs/glossary/network_throttling

https://developer.mozilla.org/en-US/docs/glossary/strict_mode

https://developer.mozilla.org/en-US/docs/glossary/smtp

https://developer.mozilla.org/en-US/docs/glossary/lossless_compression

https://developer.mozilla.org/en-US/docs/glossary/same-origin_policy

https://developer.mozilla.org/en-US/docs/glossary/main_thread

https://developer.mozilla.org/en-US/docs/glossary/dom

https://developer.mozilla.org/en-US/docs/glossary/rtl

https://developer.mozilla.org/en-US/docs/glossary/adobe_flash

https://developer.mozilla.org/en-US/docs/glossary/character_set

https://developer.mozilla.org/en-US/docs/glossary/navigation_directive

https://developer.mozilla.org/en-US/docs/glossary/perceived_performance

https://developer.mozilla.org/en-US/docs/glossary/cors-safelisted_response_header

https://developer.mozilla.org/en-US/docs/glossary/document_directive

https://developer.mozilla.org/en-US/docs/glossary/thread

https://developer.mozilla.org/en-US/docs/glossary/brotli_compression

https://developer.mozilla.org/en-US/docs/glossary/response_header

https://developer.mozilla.org/en-US/docs/glossary/method

https://developer.mozilla.org/en-US/docs/glossary/ligature

https://developer.mozilla.org/en-US/docs/glossary/loop

https://developer.mozilla.org/en-US/docs/glossary/fps

https://developer.mozilla.org/en-US/docs/glossary/rng

https://developer.mozilla.org/en-US/docs/glossary/graceful_degradation

https://developer.mozilla.org/en-US/docs/glossary/ajax

https://developer.mozilla.org/en-US/docs/glossary/web_server

https://developer.mozilla.org/en-US/docs/glossary/scroll_container

https://developer.mozilla.org/en-US/docs/glossary/grid

https://developer.mozilla.org/en-US/docs/glossary/payload_header

So there are:

• 99 pages under https://developer.mozilla.org/en-US/docs/Glossary
• 39 pages under https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
• a handful in the remnants of the Event reference https://developer.mozilla.org/en-US/docs/Web/Events
• a handful of others

For Glossary, these look like "See also" links and should be treated as such (although the Glossary page type for some reason wants to call these "Learn more"). For a sidebar, we could use the existing Glossary macro instead, or just nothing, which is what most glossary pages do.

For Accessibility, we should have a dedicated (simple) sidebar macro. Perhaps sorting this out could be part of https://github.com/mdn/content/blob/main/rfcs/aria-roles.md ?

For the rest, we could just convert them to "See also" sections, and have no sidebar. Really there is some reorg we should do with the remnants of the Event reference, but that feels like a separate issue.

[hamishwillee]

TLDR; Yes. If we get consensus I am happy to do this.

---

I can't argue that there are few places where these quicklinks could not be/should not be a see also section. Often we have both see also and quicklinks - unnecessary duplication. Having this in a standard form is desirable.

The only reason I really want to disagree is because I hate the monolithic "somewhat data driven" sidebar mechanism with a passion. I'd rather add the links I see are needed in the page, because I don't have spare half hour to work out WTF the sidebar is doing. That might improve with the data in content repo rather than yari, but I doubt it.

[wbamberg]

The only reason I really want to disagree is because I hate the monolithic "somewhat data driven" sidebar mechanism with a passion. I'd rather add the links I see are needed in the page, because I don't have spare half hour to work out WTF the sidebar is doing. That might improve with the data in content repo rather than yari, but I doubt it.

I think it's important for sidebars to be consistent across a set of docs, so if you're on a CSS page you'll see the same links in the sidebar that you see on any other CSS page. Having per-page custom sidebars undermines this principle. I think the implementation of sidebars on MDN is bad in various ways, but I like the idea that an author could just say "this is a CSS page" and automatically get the same sidebar as every other one.

In that sense I think "See also" is the place for custom per-page related links.

[hamishwillee]

Yes, hence the TLDR. Doesn't change the fact that editing sidebars is a colossal PITA. So there !