Linking guide

  • Revision slug: Project:Linking_guide
  • Revision title: Linking guide
  • Revision id: 424369
  • Created:
  • Creator: maybe
  • Is current revision? No
  • Comment

Revision Content

We regularly get users asking us questions about how to link to the MDN, or even if we allow them to do this. This short guide has been elaborated in order to answer the most common questions and help you linking to our content is the most useful ways for your readers.

Yes! Of course yes! Not only is the hypertext link the essence of the Web, it is both a way to point your users to valuable resources and a show of trust towards our work.

Therefore we encourage you to link to our content. Don't hesitate: link to our front page or a deeplink to some internal page is welcome.

There is no specific page that you should link to. What's important is how relevant that page is to your readers.

But, really, you should link to the most appropriate page for your content and users. Don't forget, that's your user the important, not your link or us.

How to link?

Linking is trivial, but good linking is somewhat more difficult. There are several way to do links:

Linking in the text

This is the most useful kind of linking: it is aimed at providing users with a link to further information about a given concept. Most of the time, such links link to pages that contain the related information and not to the home page of the Web site (there are obvious legitimate exceptions !).

... and when using the IndexedDB API, you are able to store data in a local database...

Such links are very valuable for both the user, which has in-context information one click away from his mouse, and for us as this precise context brings us users very likely to like our content. And we want the user to find the information he's looking for as quickly as possible.

What not to do when linking in the text?

Linking in the text is really nice and useful, but there are a few elements to pay attention for:

  • Don't overlink. Do not link every word, or almost: it is annoying, choose carefully the main concepts of your text, or a specific and not necessarily known one.
    Don't link many times in the page the same concept: if you are speaking about CSS animations, you don't need to link every occurrence of the word animation to the animation CSS property. If the readers didn't know the concept, they will likely click on the first occurrence to get the relevant info. Later in the text, you can safely assume they already know about the concept, either before reading the page, or after following a previous link to the previous information.
  • Pay attention when linking in forums and blog comments. Giving a pertinent link to a pertinent resource for a specific question or problem is great and often welcomed. Roaming forums and blogs to spam links to the MDN is not appreciated: the site owners, and readers, will quickly identify you as spammers and will give us a bad reputation. We are working hard to build a valuable resource and have no wish to see our efforts ruined by such behaviour, so please only link when it is pertinent to do so.

Adding a banner or an image

The other way to link to the MDN is to add an image with a link outside the main text, for example in the side bar. This has a different meaning: as much as linking in the text is a way to provide complimentary information to your user, adding an image link in the side bar is more a way to show your support to the MDN project, a way to promote it.

Don't hesitate, show us your support, visit Promote MDN to build a tailored button. You are of course free to link to a different page, like one of the landing pages.

Thank you very much for your support.

Revision Source

<p>We regularly get users asking us questions about how to link to the MDN, or even if we allow them to do this. This short guide has been elaborated in order to answer the most common questions and help you linking to our content is the most useful ways for your readers.</p>
<h2 id="Can_I_link_to_the_MDN.3F">Can I link to the MDN?</h2>
<p><strong>Yes!</strong> Of course yes! Not only is the hypertext link the essence of the Web, it is both a way to point your users to valuable resources and a show of trust towards our work.</p>
<p>Therefore we encourage you to link to our content. Don't hesitate: link to our front page or a deeplink to some internal page is welcome.</p>
<h2 id="What_page_should_I_link_to.3F">What page should I link to?</h2>
<p>There is no specific page that you should link to. What's important is <u>how relevant that page is to <em>your</em> readers</u>.</p>
<ul>
  <li>You may link to the main page of the MDN, <a href="/" title="https://developer.mozilla.org/">https://developer.mozilla.org/</a> , if you are speaking about the MDN in general.</li>
  <li>You may link to a 'landing page', that is a special page which is a kind of table of content on a specific subject, if you are speaking of this subject in general. Common landing page that are linked are:
    <ul>
      <li>HTML : <a href="/en/HTML" title="https://developer.mozilla.org/en/HTML">https://developer.mozilla.org/en/HTML</a></li>
      <li>HTML5 : <a href="/en/HTML/HTML5" title="https://developer.mozilla.org/en/HTML/HTML5">https://developer.mozilla.org/en/HTML/HTML5</a></li>
      <li>CSS : <a href="/en/CSS" title="https://developer.mozilla.org/en/CSS">https://developer.mozilla.org/en/CSS</a></li>
      <li>CSS3 : <a href="/en/CSS/CSS3" title="https://developer.mozilla.org/en/CSS/CSS3">https://developer.mozilla.org/en/CSS/CSS3</a></li>
      <li>DOM : <a href="/en/DOM" title="https://developer.mozilla.org/en/DOM">https://developer.mozilla.org/en/DOM</a></li>
      <li>JavaScript : <a href="/en/JavaScript" title="https://developer.mozilla.org/en/JavaScript">https://developer.mozilla.org/en/JavaScript</a></li>
    </ul>
  </li>
  <li>You may link to a specific page if you are speaking about a specific page. E.g.
    <ul>
      <li>If you are speaking about HTML Elements, you may be interested in linking to our list of all HTML Elements ( <a href="/en/HTML/Element" title="en/HTML/Element">https://developer.mozilla.org/en/HTML/Element</a> ) or to a specific element like {{ HTMLElement("colgroup") }}</li>
      <li>Similarly if you are speaking about the CSS, you may be link to our CSS Reference (a big index: <a href="/en/CSS/CSS_Reference" title="https://developer.mozilla.org/en/CSS/CSS_Reference">https://developer.mozilla.org/en/CSS/CSS_Reference</a> ) or to the specific properties you are speaking about, like {{ cssxref("list-style-type") }}</li>
    </ul>
  </li>
</ul>
<p><strong>But, really, you should link to the most appropriate page for your content and users</strong><strong>.</strong> Don't forget, that's your user the important, not your link or us.</p>
<h2 id="How_to_link.3F">How to link?</h2>
<p>Linking is trivial, but good linking is somewhat more difficult. There are several way to do links:</p>
<h3 id="Linking_in_the_text">Linking in the text</h3>
<p>This is the most useful kind of linking: it is aimed at providing users with a link to further information about a given concept. Most of the time, such links link to pages that contain the related information and not to the home page of the Web site (there are obvious legitimate exceptions !).</p>
<blockquote>
  <p>... and when using the <a href="mks://localhost/en/IndexedDB" title="IndexedDB">IndexedDB</a> API, you are able to store data in a local database...</p>
</blockquote>
<p>Such links are very valuable for both the user, which has in-context information one click away from his mouse, and for us as this precise context brings us users very likely to like our content. And we want the user to find the information he's looking for as quickly as possible.</p>
<h4 id="What_not_to_do_when_linking_in_the_text.3F">What not to do when linking in the text?</h4>
<p>Linking in the text is really nice and useful, but there are a few elements to pay attention for:</p>
<ul>
  <li><strong>Don't overlink</strong>. <a href="/en/JavaScript/Reference/Statements/do...while" title="do...while">Do</a> <a href="/En/CSS/:not" title=":not()">not</a> <a href="/En/CSS/:link" title=":link">link</a> every word, or almost: it is annoying, choose carefully the main concepts of your text, or a specific and not necessarily known one.<br />
    Don't link many times in the page the same concept: if you are speaking about CSS animations, you don't need to link every occurrence of the word animation to the <a href="/en/CSS/animation" title="animation">animation CSS property</a>. If the readers didn't know the concept, they will likely click on the first occurrence to get the relevant info. Later in the text, you can safely assume they already know about the concept, either before reading the page, or after following a previous link to the previous information.</li>
  <li><strong>Pay attention when linking in forums and blog comments.</strong> Giving a pertinent link to a pertinent resource for a specific question or problem is great and often welcomed. Roaming forums and blogs to spam links to the MDN is not appreciated: the site owners, and readers, will quickly identify you as spammers and will give us a bad reputation. We are working hard to build a valuable resource and have no wish to see our efforts ruined by such behaviour, so please only link when it is pertinent to do so.</li>
</ul>
<h3 id="Adding_a_banner_or_an_image">Adding a banner or an image</h3>
<p>The other way to link to the MDN is to add an image with a link outside the main text, for example in the side bar. This has a different meaning: as much as linking in the text is a way to provide complimentary information to your user, adding an image link in the side bar is more a way to show your support to the MDN project, a way to promote it.</p>
<p>Don't hesitate, show us your support, visit <a href="/en-US/promote" title="https://developer.mozilla.org/en-US/promote">Promote MDN</a> to build a tailored button. You are of course free to link to a different page, like one of the landing pages.</p>
<p>Thank you very much for your support.</p>
Revert to this revision