Links - The MDN project 编辑

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

Note: Please note that we have particular preferred practices for linking; these are described in the MDN writing 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 specify text that will be used as the link target (or, if you had selected text in the document before opening the dialog box, that text is displayed here as the link target), and second, 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. Note that the items in the list display their locale ("[en-US]" in this case). That text is not used in the link target text; it is there to help you ensure that you are linking to an article in the same locale as the one you are editing.

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. If you link to another article on MDN, remove the domain name ("https://developer.mozilla.org") from the beginning of the URL, since that's implied.

Once the link is configured, click the OK button to insert it.

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 add new toolbar widgets to use 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 Text 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 pre-populated dialog similar to the previous case. By "hovering" your mouse over a suggested article, you can see its relative slug (its URL relative to developer.mozilla.org), which can give you a better idea of where it is located and what type of article it is.

Here, of the articles suggested as possible matches. "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; in each case, there may be added parameters available to give you more control over the output (such as suppressing the automatic addition of the <code> styling). Each macro name below can be clicked upon to read the macro code itself; they all have comments at the top explaining what they do and all of their parameters.

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(). You can also supply an additional parameter to override the text: {{domxref("window.scrollBy", "scrollBy()")}} results in 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 straightforward: {{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 other browsers and Web engines:

WebKit (Safari, etc.)

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. You can, optionally, also provide alternate link text to use instead of a selected piece of text from the article or and/or the section number within the specification to which to link.

Linking to information about XPCOM interfaces

The MDN staff no longer actively maintains the XPCOM documentation, but volunteer contributions are welcome.

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.

The syntax for linking to the documentation for an XPCOM interface as a whole is just: {{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 the 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 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.

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.

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 Quicklinks.

URL schemes

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

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

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

Special URL schemes such as about: and chrome: are used by Firefox, Google Chrome, and some other browsers to provide access to special content such as preferences, debugging information, and so forth. These links do not work from article content, so please do not try to create links using these schemes within MDN articles. The same applies to the javascript: and jar: schemes, which are blocked by most modern browsers as a security precaution.