Move Events reference as one article under DOM API

[Josh-Cena]

I know a lot of us have mixed feelings about the events reference, because it simply isn't supposed to be here. I'm merging everything into a single guide article, and next I will fix the broken anchors within in it (the current state gives me no appetite to modify this page).

[github-actions]

Preview URLs (31 pages)

• /en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling
• /en-US/docs/Learn_web_development/Core/Scripting/Events
• /en-US/docs/Learn_web_development/Extensions/Forms/User_input_methods
• /en-US/docs/MDN/Writing_guidelines/Howto/JSON_Structured_data
• /en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/API_event_subpage_template
• /en-US/docs/Mozilla/Firefox/Releases/9
• /en-US/docs/Web/API/CustomEvent/CustomEvent
• /en-US/docs/Web/API/CustomEvent/initCustomEvent
• /en-US/docs/Web/API/CustomEvent
• /en-US/docs/Web/API/Document/createEvent
• /en-US/docs/Web/API/Document_Object_Model/Events
• /en-US/docs/Web/API/Element/copy_event
• /en-US/docs/Web/API/Element/cut_event
• /en-US/docs/Web/API/Element/paste_event
• /en-US/docs/Web/API/Event/Event
• /en-US/docs/Web/API/Event/initEvent
• /en-US/docs/Web/API/EventTarget/addEventListener
• /en-US/docs/Web/API/EventTarget/dispatchEvent
• /en-US/docs/Web/API/EventTarget
• /en-US/docs/Web/API/Event
• /en-US/docs/Web/API/ExtendableEvent
• /en-US/docs/Web/API/MouseEvent/initMouseEvent
• /en-US/docs/Web/API/UIEvent/initUIEvent
• /en-US/docs/Web/API/Window/postMessage
• /en-US/docs/Web/API
• /en-US/docs/Web/HTML/Reference/Attributes
• /en-US/docs/Web/HTML/Reference/Elements/body
• /en-US/docs/Web/MathML/Reference/Global_attributes
• /en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Cross-browser_audio_basics
• /en-US/docs/Web/Media/Guides/Audio_and_video_delivery
• /en-US/docs/Web

Flaws (43)

Note! 28 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/Document_Object_Model/Events
Title: DOM events
Flaw count: 1

• macros:
  • Macro produces link /en-US/docs/Web/API/Document_Object_Model/Whitespace_in_the_DOM which is a redirect

---

URL: /en-US/docs/Web/HTML/Reference/Attributes
Title: HTML attribute reference
Flaw count: 35

• broken_links:
  • Can't resolve /en-US/docs/Web/HTML/Reference/Attributes/alt
  • Can't resolve /en-US/docs/Web/HTML/Reference/Attributes/autoplay
  • Can't resolve /en-US/docs/Web/HTML/Reference/Attributes/cite
  • Can't resolve /en-US/docs/Web/HTML/Reference/Attributes/colspan
  • Can't resolve /en-US/docs/Web/HTML/Reference/Attributes/controls
  • and 30 more flaws omitted

---

URL: /en-US/docs/Web/MathML/Reference/Global_attributes
Title: MathML global attributes
Flaw count: 7

• broken_links:
  • Can't resolve /en-US/docs/Web/MathML/Reference/Global_attributes/autofocus
  • Can't resolve /en-US/docs/Web/MathML/Reference/Global_attributes/class
  • Can't resolve /en-US/docs/Web/MathML/Reference/Global_attributes/data-*
  • Can't resolve /en-US/docs/Web/MathML/Reference/Global_attributes/id
  • Can't resolve /en-US/docs/Web/MathML/Reference/Global_attributes/nonce
  • and 2 more flaws omitted

External URLs (5)

URL: /en-US/docs/Web
Title: Web technology for developers

• https://developer.chrome.com/docs/devtools/ (1 time)
• https://firefox-source-docs.mozilla.org/devtools-user/index.html (1 time)
• https://learn.microsoft.com/en-us/microsoft-edge/devtools/landing/ (1 time)
• https://webkit.org/web-inspector/ (1 time)

---

URL: /en-US/docs/Web/API/Document_Object_Model/Events
Title: DOM events

• https://mdn.dev/archives/media/samples/domref/dispatchEvent.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-07-26 13:30:37)

[bsmth]

I think this is a great idea, so no objections from me.

[Josh-Cena]

Anyone else we should consult?

[hamishwillee]

This is a good idea. I haven't reviewed the new events doc though, and won't unless requested.

[dipikabh]

Brian brought this to our internal team discussion and there was consensus to go ahead with this move. Thanks for this work! 🙌

I've left a few suggestions.

Do we need to capture the first para in https://developer.mozilla.org/en-US/docs/Web/Events/Event_handlers#what_are_the_available_events somewhere, maybe in a section before "See also" (I've suggested to add one) in the "DOM events" guide? Probably with a different heading that suggests where people can expect to find event documentation on MDN.

[dipikabh]

looking at other items in the sidebar (some of which are pretty long!):

Suggested change

	short-title: Events
	short-title: Understanding events

or

Suggested change

	short-title: Events
	short-title: Working with events

[Josh-Cena]

This guide talks about the list of events, working with events, and the conceptual model of events. It sounds a bit of a stretch to make the title any more specific than just "Events". I agree we should shorten the other title though.

[dipikabh]

Would be nice to replace this macro as well with the sidebar in fm at some point. Looks like only 9 files will be impacted

[Josh-Cena]

Looks like only 9 files will be impacted

Really? We do have a lot of DefaultAPISidebar usage. Last time we agreed to only do this when we could move the sidebar parameter to a separate api-group front matter.

[dipikabh]

Should probably be moved to the Guides section.

Also change to "DOM events"

[Josh-Cena]

I'm not too sure about that. The page is technically branded as a "guide", but this particular section feels much more "reference" than "guide". In the long term I'm not even sure if this hand-maintained table is sustainable, but for now I would just call it "Events index" and keep it as "reference".

Suggested change

	- [Event reference: Media](/en-US/docs/Web/API/Document_Object_Model/Events#media)
	- [Event index: Media](/en-US/docs/Web/API/Document_Object_Model/Events#media)