Creating and editing links

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 Ctrl-K (Command-K on the Mac). The link button looks like this: . 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.

Note: If you're paying attention, you'll see that there's a second tab—Advanced—in the link editor dialog. There are no options there that we advise you to use on a regular basis, at least at this time. It's possible that in the future there will be alternate styles for links, but we will likely have special UI elements for those features when they're available.

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.

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")}}. For example, to create a link to the section on macros later in this same article, you can simply do {{anch("Using macros")}}, like this: Using macros.

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.

Note: Please look at the Using macros documentation if you're interested in learning more about using macros, and check out our KumaScript documentation to learn more about the macro system itself.

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.

Document Tags and Contributors

Contributors to this page: jswisher, teoli, Bownee1, Sheppy, suopte
Last updated by: jswisher,
Hide Sidebar