您的搜索结果

    MDN 编辑指南

    Note: This content covers how to edit on MDN. It will be broken into a few sub-pages before things are done.

    The WYSIWYG (what-you-see-is-what-you-get) editor offered by the Mozilla Developer Network wiki makes it easy to contribute new content.  The MDN editor guide provides some information on how to use the editor, as well as some information about helpful features that may improve your productivity.

    The MDN style guide offers information about how to format and style the content itself, including our preferred grammar and spelling rules.

    The editor interface

    The editor window, shown below, is comprised of eight key boxes. This section will provide information about each section so you know how to use our entire editing environment.

    Note: We're constantly working on improvements to MDN, so there will be times when this documentation or the screen shots below may be slightly out-of-date. We'll periodically update this documentation, though, to avoid it being unusably behind.

    Page controls

    The page controls area offers buttons affecting the page as a whole:

    Save and keep editing
    Saves the page without closing the editor; this lets you periodically save your work, creating an entry in the page history that you can revert to if you need to, or in case you need to stop working and come back to it later. This option is not available when creating new pages. See The revision comment box to learn how to include a revision comment on your saved article.
    Save changes
    Saves the page and closes the editor, returning you to view the page in standard browsing mode. See The revision comment box to learn how to include a revision comment on your saved article.
    Preview changes
    Opens a new tab or window showing the page as it exists in your editor, rendered as if you were browsing to it. This includes executing any macros you use in-content. Your work is not saved when you use this option. This lets you check to be sure you haven't made any errors in your macro syntax or other formatting that may prevent the page from rendering correctly.
    Discard changes
    Cancels your edit, disposing of any changes you've made without saving them. You're returned to the page in standard browsing mode.

    The page info box

    The page info box contains information about the page, but also can be expanded to offer additional page controls. By default, it displays the page's title and the date and time at which a local draft was saved; the local draft, stored on your computer, is used as a backup in case you accidentally navigate away from the editor or your browser crashes.

    You can click the "Edit Page Title and Properties" link to switch to a view offering additional page controls. This view looks like this:

    This view allows you to change the page's display title and the depth of the page's table of contents. The display title is the title shown in the browser's title bar (or tab bar) and as the title of the page at the top of the article and in the breadcrumb bar, as appropriate. It doesn't affect the page's URL.

    Note: It's worth noting that we prefer short URLs and descriptive titles; for example, the article about the Kuma API has the title "The Kuma API" but its URL slug (the part after the site's root) is Project:MDN/Kuma/API, where "API" represents this page.

    The TOC (table of contents) level lets you specify how deeply into the article's heading levels the table of contents automatically displayed on the page should go. By default, heading levels <h2> through <h4> are included in the TOC, so that the TOC has a three-level depth. However, you can set this to any of those, as well as "No TOC" (to not display a TOC at all, such as on landing pages) or to show all levels in the TOC.

    As is the case with all changes you might make, changes in the page info box do not take effect unless you save the page.

    The toolbar

    The editor's toolbar offers features that let you adjust the appearance and flow of the article as you work. There are two rows of buttons (more if the width of your window is narrow enough that they wrap, but generally two) and a third row that shows the hierarchy of HTML elements leading up to where you are. In the screenshot below, for example, you're writing inside a top-level <p> block.

    The toolbar's buttons are divided into seven groups. Let's look at each; we will examine the buttons in each group in order left-to-right.

    Document options

    The document options box provides options for document-level manipulations:

    Source mode toggle
    The source mode toggle button lets you toggle between editing using the WYSIWYG interface and in raw HTML source mode. We strongly request that you try to avoid using source mode, as it's very easy to wind up with content that doesn't match our style guide or, worse, doesn't work right at all. Currently, though, the editor has some quirks that make it impossible to do certain things without resorting to source mode.
    Save and keep editing
    A duplicate for the main "Save and keep editing" button.
    Save and exit
    Just like the main "Save changes" button.
    Paste as plain text
    Opens a dialog into which you can paste text; the text has all styling stripped from it so that you don't inadvertently introduce unwanted styles into the site content. Once you've pasted your text, you can (optionally) make changes, then click a button to insert it into the article you're working on.
    Paste from Word
    On Windows, lets you paste text from Microsoft Word and have it adjusted to work reasonably well in MDN's wiki. We prefer for you to not use this (the results will work but are not typically style guide compliant), but it's there for a few teams that need it.
    Check spelling
    Starts the spell checker.
    Spell check as you type
    Presents a submenu that lets you control and configure the as-you-type spell checker.
    Find
    Opens the Find panel in "Find" mode, which lets you search your document for a specified string.
    Replace
    Opens the Find panel in "Find and replace" mode, allowing you to find strings and replace them with new ones.

    It's worth noting that the Find and Replace buttons both take you to the same dialog box, which offers several configurable options for finding and optionally replacing text.

    Block-level options

    These buttons provide options affecting or creating blocks in your article.

    Insert/remove bulleted list
    Creates or removes a bulleted list from your article. Once you're working in a bulleted list, each time you press return, you will start a new bullet. The tab key can be used to indent a level, and shift-tab will outdent a level. Pressing return on an empty bullet will exit bullet list mode. Right-clicking on the list lets you choose to edit the list's properties (specifically, the shapes of the bullets).
    Insert/remove numbered list
    Creates or removes a numbered list from your article. Once you're working in a numbered list, each time you press return, you will start a new bullet. The tab key can be used to indent a level, and shift-tab will outdent a level. Pressing return on an empty bullet will exit numbered list mode. Right-clicking the list offers the option to open the properties dialog for the list; the properties include the style of the numbers (numbers, letters, Roman numerals, etc, and what number to start with).
    Definition list
    Creates a new definition list. Definition lists consist of a series of titles and definitions (this list you're reading right now is an example).
    Definition title
    Creates a new title in a definition list. If you're not already editing a definition list, a new one is created for you. Pressing return after entering a definition title automatically starts you editing a definition description.
    Definition description
    Creates a new description in a definition list. Pressing return on a description line automatically starts a new title. Pressing return twice will exit definition list mode.
    Decrease indent
    Shifts the indentation level to the left once; this is the same as shift-tab while in a list.
    Increase indent
    Shifts the indentation level to the right once; this is the same as tab while in a list.
    Blockquote
    Inserts a blockquote. Please do not use this. Blockquotes are not part of our standard style guide, and this button will be removed in the near future.
    Image
    Inserts a new image into the article. See Adding images to an article below for details on how to use this option.
    Table
    Inserts a table into the article. See Working with tables for more information on tables in articles.
    Text color
    Lets you set the text foreground color. Please do not use this. We will switch to using CSS styles for all coloring soon.
    Background color
    Lets you set the text background color. Please do not use this. We will switch to using CSS styles for all coloring soon.
    Text direction left-to-right
    Sets LTR as the current text typing direction. Used only when covering localization/internationalization topics.
    Text direction right-to-left
    Sets RTL as the current text typing direction. Used only when covering localization/internationalization topics.

    Maximize

    This is an odd box, in that it consists of just one button: Maximize. This button causes the editor interface (that is, the toolbar and the edit box) to take over your entire browser window, giving you as much space as possible to write.

    Headings

    The heading buttons let you insert a heading. Click one of these buttons to create a new heading at the corresponding depth. By default, H2 through H4 are included in the table of contents, but you can change this, as described in The page info box.

    Formatting styles

    The next box is a drop-down menu offering a selection of special formatting options. These are:

    None
    Removes all styling from the current block.
    Note box
    Creates a note box, as seen below. You should always start a note box with "Note:" in bold letters.

    Note: This is a note box.

    Warning box
    Creates a warning box, as seen below. These should always begin with "Warning:" in bold letters.

    Warning: This is a warning box.

    foo = bar()
    Special note
    This is a right sidebar.
    Callout box
    Creates a new callout box. We are phasing this kind of box out in favor of a new design, so it shouldn't be used for new content.
    Two columns
    Makes the selected text or the current block two columns instead of one, on browsers that support it.
    Three columns
    Makes the selected text or the current block three columns instead of one, on browsers that support it.
    Syntax box
    Creates a syntax box, such as the one shown below. You need to use the "PRE" button as well, to create a <pre> block inside it. You probably won't see the yellow box until you do.
    Right sidebar
    Creates a light grey sidebar that floats to the right of content. You may enter small amounts of text in these boxes to draw special attention to them.
    SEO summary
    This special style is used to indicate a sentence or two that should be used as the article's summary for SEO purposes. It's also used by macros that automatically construct landing pages. If you don't specify this, MDN automatically uses the first paragraph of your article, but sometimes that's not the optimal text (or it's too much text), so this lets you override that.

    Code samples and redirects

    These buttons are mostly used for providing preformatted text (usually code samples), but our "insert redirect" button is, for some reason, here too.

    PRE
    Inserts a <pre> (preformatted text) block, or turns the current block into one. All code samples or examples of text output to a terminal should be in one of these blocks.
    Syntax highlighter
    The syntax highlighter lets you choose a language for which to apply syntax highlighting to the<pre> (preformatted text) block; if you're not already in such a block, this will create one for you. Simply choose the language and you're good to go.
    Insert code sample template
    This button is used by the live sample system to help you quickly insert a new live sample. You don't need to use it, but it's there for convenience. See Using the live sample system for details on using this and other live sample features.
    Insert code sample iframe
    Inserts an <iframe> into the document, displaying a given live sample. See Using the live sample system for details on using this and other live sample features.
    Create a redirect
    Inserts a redirect. See Creating redirects for further information.

    The final group of toolbar buttons includes options for creating and maintaining links and anchors, as well as for applying inline styles to content.

    Link
    Creates a new link. This button opens the link editor dialog, which is covered under Creating and editing links below.
    Unlink
    Removes the link at the insertion point.
    Anchor
    Creates an anchor at the insertion point.
    Bold
    Toggles boldface text mode.
    Italic
    Toggles italic text mode.
    Underline
    Toggles underlined text mode.
    Code
    Toggles <code> mode. This is used for inline presentation of variable names, function names, object names, filenames, and so forth.
    Strike through
    Toggles strikethrough mode.
    Superscript
    Toggles superscript mode. Please note that we don't use footnotes on MDN, so you should rarely if ever need this button.
    Remove format
    Removes the current formatting from the selection.
    Align left
    Makes the current block left-aligned. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.
    Center
    Centers the current block. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.
    Align right
    Makes the current block right-aligned. Please do not use this. We will be using CSS styles for all alignment tasks starting very soon.

    The edit box

    The edit box is, of course, where you actually do your writing. Right-clicking in the edito box will offer appropriate additional options depending on the context of your click; clicking in a table will offer table-related options and clicking in a list will offer list-related options, for example.

    The revision comment box

    After you've made your changes, it's strongly recommended you add a comment to your revision. This is displayed in the revision history for the page, as well as on the Revision Dashboard. It helps to explain or justify your changes to others that may review your work later. To add a revision comment, simply type the note into the revision comment box before clicking either of the save buttons at the top of the page.

    Note: We know that the revision comment box being so far away from the save buttons doesn't make any sense. We're working on design changes that will fix that.

    The tags box

    Page tags help categorize and organize information, and help us identify pages that need special attention. Tags are also used to mark pages that are obsolete and may need to be deprecated or even deleted. It's incredibly useful to have good, clean tags on pages, so be sure to have good tags on articles you contribute to.

    The tag box is near the bottom of the editor page, and looks like this:

    The tag editing box showing three tags.

    Adding a tag

    To add a new tag, simply click in the box and start typing:

    Screen thot: the tag box after typing a new tag but before pressing Enter.

    Here we see the three already existing tags (as button-like objects) and our new tag as unadorned text. When we press Enter or Tab key (or comma), the new tag is committed to the list, and the list looks like this:

    Screen shot: the tag box with our new tag in place.

    For a list of recommended tags, as well as a usage guide for specific tags, please see MDN tagging standards.

    Removing a tag

    There are two ways to remove a tag: you can click on the "x" icon next to its name in its button, or you can click to its right in the editor box and press the delete key on your keyboard.

    Committing your changes

    Your changes are not saved unless you click one of the save buttons at the top of the editor window. Scroll back to the top of the window if you don't see the buttons, then click one of the two green save buttons. Now your change has been committed.

    The reviews box

    MDN uses reviews to try to monitor and improve the quality of its content. This works by setting a flag on an article indicating that a review is needed. You can learn more about content reviews and how they work in the How to help article.

    To request a review on the article you've worked on, simply toggle on the checkbox next to the type of review that's needed. Technical reviews should be requested any time you make changes to the explanation of how something technical works, while editorial reviews are a good idea when you've made changes and would like someone to review your writing and style choices.

    Be sure to click one of the save buttons after making your selections, to commit your review request.

    The attachments box

    The attachments box lets you upload files to MDN for use in MDN content, as well as see what files are being used by the current document.

    Note: Due to a quirk in our current implementation, files are not associated with pages unless they're actually used in the page. So if you upload an attachment and don't make use of it before you save the article, it will not appear on the attachments list. So be sure to link to it or embed the image right away.

    To add an attachment to the page, simply click the "Attach Files" button; this expands the attachment box to look like this:

    As you see, there's a table that lets you select a file to upload, then give it a title and, optionally, a description and an additional comment. The title is mandatory, and should describe the file so its usage context is understandable. Once the fields are filled out and you've selected your file, click the "Upload" button to send it to MDN.

    Note: Only a select few types of files are permitted as attachments on MDN: GIF, JPEG, PNG, SVG, and HTML. Photoshop images are permitted but should be avoided except in very specific cases. Any other file types will not be allowed by the upload form.

    Feel free to open this page in the editor and look at its attachment list at the bottom to get a feel for it.

    Once a file has been attached, it will appear (by its title, as you specified in the form) in the image properties dialog box when using images in your article. See Adding images to an article for details on this interface. To link to other types of files, copy the URL from the attachments box and use that as your link target when adding links to the page using the link button in the toolbar.

    Keyboard shortcuts

    There are a number of convenient keyboard shortcuts available to help you avoid taking your hands off the keyboard while you work.  The shortcuts are listed for Windows and Linux; on Mac, instead of using the Control key, you can use the Command key.

    Shortcut Description
    Ctrl-A Select all
    Ctrl-C Copy to clipboard
    Ctrl-V Paste from clipboard
    Ctrl-X Cut
    Ctrl-Z Undo
    Ctrl-Y Redo
    Ctrl-K Open link editor
    Ctrl-B Bold
    Ctrl-I Italic
    Ctrl-O Toggle <code> style.
    Ctrl-Shift-O Toggle source view mode.
    Ctrl-P Toggles the <pre> style on the current block.
    Ctrl-U Underline
    Ctrl-S Save changes and close the editor
    Ctrl-Shift-S Save changes without closing the editor
    Ctrl-2 through Ctrl-6 Select header level 2-6
    Ctrl-Shift-L Toggles between bulleted list, numbered list, and paragraph format
    Tab Increases indent level if in indent mode, otherwise inserts two spaces as a tab.  Inside tables, this jumps to the next cell, or inserts a new row if there is no next cell.  If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.
    Shift-Tab Decreases indent level if in indent mode.  Inside tables, this jumps to the previous cell, or inserts a new row if there is no previous cell.  If the cursor is currently in the page title or in a header, the cursor jumps to the next paragraph.
    Shift-Space Inserts a non-breaking space (&nbsp;)
    Shift-Enter

    Exits out of the current block.  For example, if you're currently editing a <pre> block, shift-Enter exits the block, putting you back in the body of the article.

    Note: Not currently implemented; see bug 780055.

    Adding images to an article

    Once you've attached an article to the page (see The attachments box), you can use it in your article. You can also link to images elsewhere on MDN. To insert an image, click on the "Image" button in the toolbar, which looks like this:

    The image properties dialog box that appears looks like this:

    There are three tabs; the first (and the one you'll use most) is the Image Info tab. The other two are the Link and Advanced tabs.

    Image Info

    There are many options here:

    Attachments
    This popup menu shows a list of the page attachments. Only items you've uploaded during the current edit session, or that are already used elsewhere on the page, will be listed.
    URL
    If you wish to use an image that's not in the attachments list (for example, one attached elsewhere on MDN, or uploaded during a previous edit session), you can enter its URL in this field.
    Alternative text
    The alternative text to be displayed if the image is not displayed. This text is also used by screen readers, so please put an appropriate note here for the sake of accessibility.
    Width / Height
    You may adjust the width and height of the image as displayed in the article here. By default, these are locked to remain in proportion to one another, but you may toggle that by clicking on the lock icon.
    Border
    You may optionally specify the width of a black border to draw around your image. Please only use the value 0 (or leave blank) or 1 here, and you should only choose to use a border if your image has a pale background and should stand out from the the article's background.
    HSpace / VSpace
    These let you specify how much whitespace to surround the image with horizontally and vertically, respectively. You will usually only need to use these if you use the alignment option below.
    Alignment
    By default, images are displayed alone as their own block. However, you may choose here to float the image to the left or to the right, allowing text to wrap around it. We don't do this often; it's used only in very special cases where the image is small (or very narrow and tall) and there's enough text to put next to it to justify it. This is a bit of a judgement call. If you use this option, you will probably want to set HSpace and VSpace values to prevent the text from being too close to the image. A value of 6 or 8 for each usually works well.

    The preview box gives an example of what the image will look like given your current settings.

    The Link options tab for images lets you set a URL to go to when the image is clicked on. This is most commonly used to simply link to a larger version of the image itself (by providing the same URL as in the Image Info tab). The Link panel looks like this:

    Other than the URL field, in which you place the URL of the link's destination, you can set a target. However, please do not do so. We prefer all links to open in the same tab.

    Supported image types

    You may upload GIF, JPEG, and PNG images, as well as SVG diagrams. For screenshots, we prefer PNG, and we're trying to transition to using SVG for diagrams because they can be translated into other languages more easily than other image types.

    Photoshop files may also be uploaded. However, they may not be used as images inline in content.

    Removing and changing images

    To remove an image from the article, you can simply select it and press your delete key, or place the cursor after it and press delete.

    Note: You cannot delete attachments on MDN; we will eventually have a mechanism for this, but at this time, they remain on the server for potential later re-use.

    You can also revise the image properties for an image by double-clicking it, or right-clicking on it and choosing "Image Properties" from the context menu that appears. This will present the same dialog as above.

    Working with tables

    On MDN, we use tables primarily when presenting lists of information with more than two pieces of information per data point. If you're creating a list of items with a name and a value, you should typically use a definition list instead of a table; that is, we prefer to avoid using two-column tables. This is primarily because tables can be difficult to display and to read on mobile devices, so we try to avoid them when possible.

    Please see the MDN style guide for details on use of tables and their proper formatting; however, let's look at the actual method by which you insert and edit tables.

    Creating a table

    To insert a new table, click the Table icon in the toolbar, which looks like this:

    Having done this, you'll be presented with the Table Properties dialog:

    There are two panels here: Table Properties and Advanced.

    Table properties

    This panel is where you'll do most of your work configuring the table, as there are few items in the Advanced panel we recommend using. The options here are:

    Rows
    The number of rows in your table. You may add more rows while in the editor, but this lets you quickly configure your table.
    Columns
    The number of columns in your table.
    Headers
    Lets you configure where your headers are, if any. By default, no header cells are added to your table; however, we generally prefer that tables have headers, so you should change this most of the time. The possible values are None, First row, First column, and Both.
    Alignment
    Lets you align the table along the left, right, or center of the article. Please do not use this option. Our style guide specifies that tables should always be left-aligned. There are very few exceptions to this rule (usually only when we're being naughty and using tables for layout, which we're working on getting out of the habit of doing as we build out our CSS).
    Caption
    You may choose to add a caption to your table; however, we do not usually do so on MDN, so you will probably leave this blank.
    Summary
    You should typically leave this blank, as you should be providing appropriate explanatory text adjacant to your table.

    Advanced

    The Advanced panel provides a few additional options, most of which we don't use on MDN and will likely remove in the future.

    As you see here, there are only four options; they are:

    Id
    The <table> element's id. We generally do not use IDs on tables on MDN.
    Language Direction
    Lets you establish the writing direction used in the table. This should be used only when localizing content.
    Style
    This field lets you hand-enter custom CSS. Do not use this field! We will probably remove your table if you do. We are trying to eliminate all uses of custom styles outside what's provided by our stylesheets.
    Stylesheet Classes
    This lets you specify a stylesheet class to use for the table. This should nearly always be "standard-table", which is our standard table class.

    Once you've finished configuring your table, click "OK" to create it.

    Working with tables

    Once a table has been created, working with it is very much like in any table editor, entering data into its cells. Pressing the tab key will advance you to the next cell in the table, wrapping to the next row if you're in the last cell in the row you're currently working on. If you're in the last cell of the last row when you press tab, a new row will be added to the end of the table, and the cursor will be placed in the first cell of the new row.

    You may right-click on the table to get an assortment of options for adjusting the cells, rows, columns, and the table itself:

    Paste
    On browsers that support pasting via script (some, including Firefox, do not, for security purposes), this will paste your clipboard at the current point in the table.
    Cell
    This submenu offers options related to the selected cell or cells. See Cell options.
    Row
    This submenu offers options related to the selected row or rows. See Row options.
    Column
    This submenu offers options related to the selected column or columns. See Column options.
    Delete Table
    Deletes the entire table. This option is listed twice due to a glitch we've yet to track down. Both do the same thing.
    Sort Table
    Opens a dialog box providing options for sorting the contents of the table. See Sorting tables below.
    Table Properties
    Opens the same table properties dialog used to create a new table. This option is listed twice due to a bug we haven't resolved yet. Both work just fine.

    Cell options

    The cell options submenu offers options related to manipulating and editing cells in your table, and looks like this:

    These options should be fairly self-explanatory, with the exception that "Merge Cells" is only available if you have selected multiple cells; you can then use this option to combine them into a single cell.

    Cell properties

    The Cell Properties option opens a dialog box that gives you control over the details of a cell:

    The options you can configure here are:

    Width
    The width of the cell; you may change the units used for this value using the adjacent drop-down. Please don't use this. You shouldn't need to adjust widths of cells except in rare cases involving nesting images or example code within tables.
    Height
    The cell's height; this is always in pixels. Please don't use this. We prefer for cell sizes to be determined automatically, except in exceptionally rare cases.
    Word Wrap
    Specifies whether or not the cell's contents should be permitted to wrap. This should almost always be left at "Yes", the default.
    Horizontal Alignment
    Allows you to set the horizontal alignment for the cell's or cells' contents. This should almost always be left at the default.
    Vertical Alignment
    Lets you set the vertical alignment of the cell or cells. This should nearly always be left at the default, but may be adjusted if necessary.
    Cell Type
    Lets you specify whether the cell or cells contain data or header information. Making a row a header row gives it header styling that stands out from the data within the table.
    Rows Span
    Lets you specify how many rows the cell should take up within the table. Rarely needed, but useful for certain types of table.
    Columns Span
    Lets you indicate how many columns the cell should occupy within the table. You should rarely need to use this option.
    Background Color
    Lets you specify a background color for the cell; clicking "Choose" opens a color picker to make it easier to find a color you like. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable will soon be covered by CSS classes.
    Border Color
    Lets you specify a border color for the cell; clicking "Choose" opens a color picker to make it easier to find a color you like. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable will soon be covered by CSS classes.

    Row options

    The row options submenu gives you options you may use to adjust and refine the rows in your table:

    These options are all straightforward; Insert Row Before lets you add a new row before the current cursor position in the table, while Insert Row After adds a new row below the current row. Delete Rows removes the row containing the insertion point, or all selected rows (or all rows on which you have selected cells).

    Column options

    The column options submenu lets you edit the columns in your table:

    These options mirror those in the row options menu; Insert Column Before lets you add a new column to the left of the current cursor position in the table, while Insert Column After adds a new row to the right of the current location. Delete Columns removes the column containing the insertion point, or all selected columns (or all columns in which you have selected cells).

    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 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 Loopup / 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.

    Creating redirects

    Sometimes you need to have a page that simply redirects to another page, or to a section of another page. This can be needed if a page is merged into another page sometime after its creation, for example. Fortunately, this is easy to do. You can simply click the redirect button in the toolbar, which looks like this: .

    This brings up a dialog box asking for the name of the destination document and its URL. The name isn't incredibly important; it's mostly useful if you're looking at the redirect page itself and want to know what you're redirecting to. The URL must be a full path from the base of the site, like "/en-US/docs/foo". Relative URLs will not work. However, you can specify a section within the target page using a hashmark ("#") character, such as "/destination/url/here#section_name". This lets you redirect the user straight to that section of the target page.

    Using macros

    The Kuma platform on which MDN runs provides a powerful macro system, KumaScript, which makes it possible to do a wide variety of things automatically. The KumaScript guide provides an in-depth look at how to use macros on MDN, so this section is more of a brief overview. If you've already read the section above on Using link macros, you're already at least a little bit familiar with the concept.

    Macros on MDN are implemented using server-executed JavaScript code, interpreted using Node.js. On top of that we have a number of libraries we've implemented that provide wiki-oriented services and features to let macros interact with the wiki platform and its contents. If you're interested in learning more, see the KumaScript guide; the KumaScript reference provides details on the libraries and other KumaScript APIs we've implemented.

    To actually use a macro, you simply enclose the call to the macro in a pair of double-braces, with its parameters, if any, enclosed in parentheses; that is:

    {{macroname(parameter-list)}}

    A few notes about macro calls:

    • Macro names are case-sensitive, but some attempt is made to correct for common capitalization errors; you may use all lowercase even if the macro name uses caps within it, and you may capitalize a macro whose name normally starts with a lower-case letter.
    • Parameters are separated by commas.
    • If there are no parameters, you may leave out the parentheses entirely; {{macroname()}} and {{macroname}} are identical.
    • Numeric parameters can be in quotes, or not. It's up to you (however, if you have a version number with multiple decimals in it, it needs to be in quotes).

    Macros are heavily cached; for any set of input values (both parameters and environmental values such as the URL for which the macro was run), the results are stored and reused. This means that the macro is only actually run when the inputs change.

    Note: You can force all the macros on a page to be re-evaluated by force-refreshing the page in your browser (that is, a shift-reload).

    Macros can be as simple as just inserting a larger block of text or swapping in contents from another part of MDN, or as complex as building an entire index of content by searching through parts of the site, styling the output, and adding links.

    You can read up on our most commonly-used macros on the Custom macros page; also, there's a complete list of all macros here.

    Using the live sample system

    MDN supports turning sample code displayed in articles into running samples the reader can look at in action. These live samples can include HTML, CSS, and/or JavaScript in any combination.

    How the system works

    The live sample system gathers up all the code in a group, merges it together into one HTML file, and then renders that HTML in an <iframe>.

    A "group," in this context, can be defined in one of two ways:

    1. All <pre> blocks following a given header, but before the next header. The group is identified by the ID of the header under which the code is located.
    2. All <pre> blocks inside a given block. The group is identified by the enclosing block's ID.

    The <iframe> uses a special URL to fetch the sample code for a given group: http://url-of-page$samples/group-id, where group-id is the ID of the header under which the code is located, or of the block in which the code is located. The resulting frame is sandboxed, secure, and may do anything that works on the Web (as long as it forwards the point of the content, of course; random stuff running on MDN will be removed).

    Each <pre> block containing code for the sample has a class on it that indicates whether it's HTML, CSS, or JavaScript code; these are "brush: html", "brush: css", and "brush: js". These classes must be on the corresponding blocks of code so that the wiki can use them correctly; fortunately, these are added for you automatically when you use the syntax highlighter features in the editor's toolbar.

    Using the live sample system is deceptively easy. There are lots of options available, and we'll try to break things down to look at them a bit at a time.

    Turning snippets into live samples

    One common use case is to take existing code snippets already shown on MDN and turn them into live samples.

    Prepare the code samples

    The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples. This is simply a matter of ensuring that each piece of code is both properly marked as to which language it is, and is in a <pre> block. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. Next to the "PRE" icon in the toolbar is a drop-down menu icon under which are the various languages for which MDN has syntax highlighting available. Setting the syntax highlighting language for the block also correlates it with a language for the purposes of the live sample system.

    Note: You may have more than one block for each language; they are all concatenated together. This lets you have a chunk of code, followed by an explanation of how it works, then another chunk, and so forth. This makes it even easier to produce tutorials and the like that utilize live samples interspersed with explanatory text.

    So make sure the <pre> blocks for your HTML, CSS, and/or JavaScript code are each configured correctly for that language's syntax highlighting, and you're good to go.

    Insert the live sample frame

    Once the code is in place and properly configured to identify each block's language, you need to insert the <iframe>. To do so, you can click the "Insert Live Code Sample iFrame" button in the toolbar; it looks like this: . Upon clicking this button, you're presented with a dialog box for configuring your live sample frame:

    Under "Document", you enter the name of the article that contains the sample you wish to embed. By default, it's the article you're currently editing, but you may choose an article elsewhere on MDN, too. This makes it possible to reuse samples on multiple pages if needed.

    The "Sections in Document" menu presents the sections in the article from which you may choose to pull a sample.

    Clicking the OK button generates and inserts the macro call that will create your frame for you. That macro is called EmbedLiveSample. You can, of course, choose to type the macro out by hand. It takes up to four parameters:

    1. The ID of the header or enclosing block from which to draw the code. This isn't the same thing as the header text—by default, the ID for headers is the header text with spaces turned into underscores, and certain non-ASCII characters are encoded. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.
    2. The width of the <iframe> to create. This is optional; a reasonable default width will be used if you omit this or if it's zero. Note that if you want to use a specific width, you must also specify the height parameter.
    3. The height of the <iframe> to create.This is optional; a reasonable default height will be used if you omit this or if it's zero. Note that if you want to use a specific height, you must also specify the width parameter. If you use only one of them, the default frame size is used.
    4. The URL of a screenshot that shows what the live sample should look like. This is optional, but can be useful for new technologies that may not work in the user's browser, so they can see what the sample would look like if it were supported by their browser. If you include this parameter, the screenshot is shown next to the live sample, with appropriate headings.
    5. The slug of the page containing the sample; this is optional, and if it's not provided, the sample is pulled from the same page on which the macro is used.

    You can also provide a link that opens the live sample as a new document rather than embedding it inline in your article. To do that, use the LiveSampleLink macro, which accepts two parameters:

    1. The ID of the header or enclosing block from which to draw the code. This isn't the same thing as the header text—by default, the ID for headers is the header text with spaces turned into underscores. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.
    2. A string to use as the link text.

    It's worth noting that in many cases, you should be able to add the EmbedLiveSample or LiveSampleLink macro to pages with little or no additional work! As long as the sample can be identified by a header's ID or is in a block with an ID you can use, simply adding the macro should do the job.

    Adding a new live sample

    If you're writing a new page, and want to insert code that you want to present as a live sample, even more of the work can be done for you by the editor! Simply click on the "Insert Code Sample Template" button in the toolbar, which looks like this: . Clicking that button presents a simple dialog asking you to name your live sample:

    Enter the name of the sample; this is used as the heading for the sample. In the example below, we've entered "Live sample demo" in this box.

    Live sample demo

    As you can see here, the live sample template button has created not only the main heading ("Live sample demo"), but also subheadings for our HTML, CSS, and JavaScript content. You're not limited to one block of each; in addition, they don't even need to be in any particular order. Mix and match!

    You may choose to delete any of these you wish; if you don't need any script, just delete that heading and its <pre> block.

    Now that the template has been inserted, we can put in some code, and even some explanatory text.

    HTML

    This HTML creates a paragraph and some blocks to help us position and style a message.

    <p>A simple example of the live sample system in action.</p>
    <div class="box">
      <div id="item">Hello world!</div>
    </div>
    

    CSS

    The CSS code styles the box as well as the text inside it.

    .box {
      width: 200px;
      height: 100px;
      border: 2px solid blue;
      border-radius: 6px;
      background-color: #ffaabb;
    }
    
    #item {
      width: 100%;
      font-weight: bold;
      text-align: center;
    }
    

    JavaScript

    This code is very simple. All it does is change the font size of the "Hello world!" message.

    var el = document.getElementById("item");
    el.style.fontSize = "3em";
    

     

    附件

    文件 大小 日期 附加者为
    live-sample-button
    What the live sample button in the toolbar looks like
    6658 字节 2012-11-13 12:40:47 Sheppy
    Redirect button
    6508 字节 2013-04-18 10:25:38 Sheppy
    Initial tag box
    8766 字节 2013-05-23 08:49:43 Sheppy
    After typing a new tag, before hitting enter
    10045 字节 2013-05-23 08:52:46 Sheppy
    The tag box with the new tag added
    10035 字节 2013-05-23 08:54:52 Sheppy
    Edit page screenshot with labels
    179552 字节 2013-05-28 13:34:07 Sheppy
    Expanded page info box
    17190 字节 2013-05-28 13:41:05 Sheppy
    Editor's toolbar
    21482 字节 2013-05-28 13:59:35 Sheppy
    Attachments box - no files
    26414 字节 2013-05-29 10:47:48 Sheppy
    Image properties dialog - empty
    69968 字节 2013-05-29 14:01:37 Sheppy
    Image properties dialog - link options
    21546 字节 2013-05-29 14:13:36 Sheppy
    Image icon
    3692 字节 2013-05-29 15:22:25 Sheppy
    Table icon
    3499 字节 2013-05-29 15:24:40 Sheppy
    Table properties - advanced
    30156 字节 2013-05-29 15:26:16 Sheppy
    Table properties
    28983 字节 2013-05-29 15:26:25 Sheppy
    Table context menu - cell submenu
    31407 字节 2013-05-30 09:57:41 Sheppy
    Table context menu - column submenu
    24858 字节 2013-05-30 09:57:59 Sheppy
    Table context menu
    14389 字节 2013-05-30 09:58:15 Sheppy
    Table context menu - row submenu
    24957 字节 2013-05-30 09:58:33 Sheppy
    Table cell properties
    39657 字节 2013-05-30 10:11:49 Sheppy
    Link button
    3627 字节 2013-05-30 13:41:12 Sheppy
    Link dialog
    26410 字节 2013-05-30 13:43:17 Sheppy
    Link dialog - with lookup
    37617 字节 2013-05-30 13:51:55 Sheppy
    Link to arrays content
    31092 字节 2013-05-30 14:23:50 Sheppy
    Insert iframe icon
    3497 字节 2013-06-05 14:52:32 Sheppy
    Sample finder dialog
    22369 字节 2013-06-05 14:54:48 Sheppy
    Insert live sample dialog
    33711 字节 2013-06-05 16:06:44 Sheppy

    文档标签和贡献者

    对本页有贡献的人: OlingCat, Meteormatt
    最后编辑者: OlingCat,