External links

How to choose whether to include an external link

External links are allowed on MDN, but they require extra care to make sure they’re useful to MDN’s audience. If you’re considering an external link, act to minimize the risks of:

  • Broken or outdated links
  • Creating an appearance of endorsement, especially for commercial products or services
  • Attempts to use MDN to distribute spam

Use these guidelines (and your best judgment) to decide whether to include an external link on MDN.

Before considering an external link, consider cross-referencing content within MDN. Internal links are easier to maintain and make the entirety of MDN more valuable to readers.

Good external links take readers to resources that are relevant, durable, and widely trusted. Prefer links to external content that is:

  • Unique or indispensable (e.g., an IETF RFC)
  • Necessary for attribution, citation, or acknowledgement (e.g., as part of a Creative Commons attribution)
  • More likely to be maintained for the topic than incorporating such content into MDN itself (e.g., a vendor’s release notes)
  • Open source or community driven, like MDN itself

Poor external links lack relevance, maintainability, accessibility, or otherwise put up barriers to readers. Avoid links to external content that is:

  • Generic or non-specific (e.g., a vendor’s home page, instead of related documentation)
  • Ephemeral or unmaintained (e.g., a one-time announcement)
  • Self-linking or self-promotion (e.g., the author’s own work off of MDN)
  • Paywalled (e.g., an expensive course beyond the reach of hobbyists, students, or readers living in lower-income countries)
  • Inaccessible (e.g., a video without captions)

Self-linking, self-promotion, and spam

While a personal blog post, conference talk, or GitHub repository has value, linking to your own resources can create the appearance of a conflict of interest. Think twice before linking to resources that you have a business or personal connection to.

If you have a business or personal relationship with the target of a link, you must disclose that relationship in your pull request. Failure to do so may imperil your continued participation with MDN.

Sometimes such links are relevant and appropriate. For example, if you’re the editor of a specification and you’re contributing to docs related to that spec, then linking to the spec is expected and acceptable. But you must disclose the relationship between you and the link.