Links

Links not only among many documents, but within a single document are a crucial component to any wiki, and MDN relies heavily on them. Fortunately, links are also very easy to create, even though there are lots of ways to make them!

Please note that we have particular preferred practices for linking; these are described in the MDN style guide.

Using the toolbar

The most obvious way to create a link is to click the link button in the toolbar, or press Ctl+K (Command-K on the Mac). The link button looks like this: . You can use this feature to create a link from scratch, or to add a link to existing, selected, text.

Creating a link from scratch

Once you've clicked on the link button, you'll be presented with the link editor dialog, seen below:

Here you can construct your new link. The controls in this dialog are:

Link Type

The type of link you're creating. The default, URL, is for a URL somewhere on the Web, either on MDN or off-site. You may also choose "Link to anchor in the text" or "Email". The anchor link option lets you link to an anchor you've previously inserted using the Anchor button in the toolbar, by choosing it from a list. The email option lets you configure a mailto: URL by entering the recipient's email address, subject, and default message content. You will almost always use the URL option.

Article Title Lookup / Link Text

This field serves two purposes: first, you can enter the text that will be displayed to the user in the article as the link target, and also, the text entered here is used to look up articles on MDN that match what you enter, to find possible destination pages. For example, if you type "Array" in this box, you will see something like the following:

Here, you can see a list of all the pages on MDN whose titles include the text you've typed. You can then scroll through the list and select one of those pages, or keep typing to narrow down the list.

Attachments

Alternatively, you may make the link be a link to one of the files attached to the current page by selecting the attachment from this list. This is a great way to offer links to download code samples and the like.

URL

Finally, the URL field lets you actually directly enter the URL; it also shows the URL of whatever you've selected in either the Article Title Lookup or Attachments menus, if you've used those. A common practice is to paste URLs to pages you're working on elsewhere on MDN, however (removing the "https://developer.mozilla.org" from the beginning, since that's implied).

Once you've got your link configured, click the OK button to insert it.

Linking existing text

If you have existing text that you'd like to turn into a link, you can simplify the process somewhat. Highlight the text you'd like to turn into a link before opening the link editor; this will pre-populate the Article Title Lookup field with the selected text. For example, let's say we have the following text:

You may find it useful to use JavaScript arrays when working on this project.

We'd like to turn "arrays" into a link to the appropriate content. Just highlight that word and invoke the link editor; you'll get a dialog pre-populated like this:

Here, two articles are being suggested as possible matches. "Working with Arrays" looks like a good choice, so we can choose that. This automatically fills in the URL field, so you can just click OK and the text gets turned into a link, like this:

You may find it useful to use JavaScript arrays when working on this project.

Using link macros

MDN makes heavy use of macros to automatically create links to the appropriate content given a term, while also styling the link according to our style guide for you. Consider this: our style guide indicates that API term names, HTML elements and attributes, CSS properties, function names, and the like should be styled with the <code> element (just like that, in fact). They should also, usually, be links to the appropriate page on MDN.

Using macros to create these links takes a little getting used to but offers many benefits:

• The appropriate styles are applied for you.
• The link is created for you—and is future-proofed against future changes in the way MDN is structured.
• Appropriate tooltips can be created for you, too.

There are lots of these macros, and we won't look at them all here. Instead, we'll look at a few specific examples of the most common ones. For a more complete list, see the "Creating hyperlinks" section in our Custom macros for MDN guide. It's worth noting that you can always look at the KumaScript source code for any of these macros; most have comments at the top that explain how they work and what the various parameters are, if any.

Linking to documentation for APIs

We have a number of extremely helpful macros for creating styled links to APIs. Here are a few of the most useful ones:

HTMLElement

Inserts an HTML element's name, properly styled and linked. For example: {{HTMLElement("table")}} yields <table>.

cssxref

Inserts a CSS property, at-rule, or selector's documentation in the CSS reference. For example: {{cssxref("background-color")}} results in background-color.

domxref

Inserts a link into the Web API Reference for a given API term. For example: {{domxref("window")}} yields window and {{domxref("window.scrollBy()")}} inserts window.scrollBy()

SVGElement

Inserts an SVG element's name, properly styled and linked. For example: {{SVGElement("circle")}} yields <circle>.

Linking to sections in the same article

To link to a section within the same article, you can use the anch macro. The syntax is simple: {{anch("Name of destination section")}}. By default, the displayed link text is the title of that section, but you can add a second, optional, parameter indicating alternate text to use instead. Some examples:

• {{anch("Using the toolbar")}} looks like this: Using the toolbar
• {{anch("Using the toolbar", "earlier in this article")}} looks like this: earlier in this article

Linking to bugs

You can link to a bug in Mozilla's Bugzilla database with the bug macro. This macro accepts a single parameter: the bug number to link to. For example, {{bug(765642)}} looks like this: bug 765642.

Similarly, you can create links to bugs in the WebKit Bugzilla instance with WebkitBug: {{webkitbug(31277)}} yields WebKit bug 31277.

Linking to RFCs

Much of the way the Internet works at a core level is documented in RFCs. You can easily reference RFCs using the RFC macro. For example, {{RFC(2616)}} becomes RFC 2616.

Linking to information about XPCOM interfaces

If you're documenting Mozilla internals, being able to easily create links to XPCOM interface documentation is helpful. There are a few macros used for this.

Linking to the documentation for an XPCOM interface as a whole is as simple as {{interface("interfacename")}}. For example, you might write:

When you need to parse or create URIs, the {{interface("nsIIOService")}} interface can help.

The result looks like this:

When you need to parse or create URIs, the nsIIOService interface can help.

If you need to link to information about a specific method or attribute on an XPCOM interface, the ifmethod and ifattribute macros are for you. These accept as parameters the name of the interface and the name of the method or attribute to which you wish to reference. The ifmethod macro is particularly interesting, since it does some special formatting by adding the style guide-mandated parentheses after the method's name. For example, {{ifmethod("nsIIOService", "newURI")}} results in nsIIOService.newURI(). That's a case where you're being protected against possible changes in the style guide in the future!

Linking to Mozilla preference documentation

To insert the name of a Mozilla preference and make it link to the corresponding page in our Preference reference, use the pref macro. This accepts one parameter: the full name of the preference you wish to link to. For example, you can use {{pref("javascript.options.showInConsole")}} to create this: javascript.options.showInConsole.

Linking to a Mozilla source file

You can link to files in Mozilla's source tree (although you probably won't do this often) using the source macro. Instead of specifying the full URL of the file, you can simply specify the path relative to the /source/ directory. For example: {{source("browser/Makefile.in")}} creates this link: browser/Makefile.in.

You may also, optionally, specify alternative text to use for the link. For example, you can use {{source("browser/Makefile.in", "the browser's makefile")}} to get the result: the browser's makefile.

Linking to recommended content

If you wish to create a list of related pages, or other recommended reading material, you should do so by creating a quicklinks box in the sidebar; this mechanism is replacing our old "See also" headings at the end of articles. For details on how to create quicklinks boxes, see Using quicklinks.

URL schemes

For security reasons, you should only create links that use the following schemes:

• https://
• https://
• ftp://
• mailto:

Others may or may not work, but are not supported and will probably be removed by editorial staff.