Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

这篇文章需要文法复核。如何帮忙。

这篇翻译不完整。请帮忙从英语翻译这篇文章

注意: 本文覆盖了怎样编辑MDN中的内容。在完成之前会被分割成数个次级页面。

这个 WYSIWYG (所见即所得)编辑器是由 MDN wiki 提供的一个便于贡献新内容的工具。该指南将展示其使用方法和一些提升效率的细节。

MDN 样式指南提供一些关于编辑内容格式、样式的方法和建议的首选语法、拼写规则等信息。

编辑界面

编辑界面一共由 8 个主要部分组成。该节将会介绍编辑界面的每一个部分。你将学会如何使用整个编辑环境。

注意: 由于我们正在不断改进MDN,所以在一段时间内,本文中的文档以及一些屏幕截图可能会有一点过时。我们会定期更新。

页面管理

页面管理区提供影响整个页面的按钮:

保存并继续编辑
保存页面但不关闭编辑器,这使得你可以周期性地保存你的更改,创建一个页面历史和它的入口,在你需要时可以恢复到这个历史页面,又或者在某些情况下,你可以停止编辑,晚一点再回来继续。在创建新页面的时候,没有这个选项。点击  The revision comment box 了解如何在你保存的文章中添加修改版注释。
保存更改
保存页面且关闭编辑器,返回到标准的浏览器模式浏览页面。点击  The revision comment box  了解如何在你保存的文章中添加修改版注释。
预览更改
打开一个新的标签页或窗口预览你编辑器的内容,就像是正常的浏览这个页面,这包括执行你在内容中使用的所有宏指令。这个选项不会保存你的更改。这只是帮助你检查以确认你的宏指令语法没有任何错误,或者其他会导致页面显示不正常的样式错误。
放弃更改
放弃你的编辑,清除你对页面的所有更改。你将会返回到标准的浏览器模式浏览页面。

页面信息框

页面信息框包含了正在编辑的页面信息,也可以展开来提供额外的页面控制选项。默认情况下,它会显示页面的标题以及本地草稿的保存日期和时间;保存在你计算机上的草稿,是为了在你无意间离开编辑页面或者浏览器崩溃时能够恢复已保存的备份。

你可以通过单击“编辑页面标题及属性”来显示目录。目录看起来像这样:

这个页面允许改变页面显示的标题和目录深度。页面显示的标题指在浏览器标题栏(标签栏)、页面顶部和导航栏显示的标题。它的改变不会影响页面的URL。

注意:需要注意的是,简短的URL和描述性标题将会更好。比如,关于Kuma API的文章的标题是“The Kuma API”,但是其URL路径是Project:MDN/Kuma/API,其中的API代表当前页面。

TOC目录等级允许设置在文章开头自动显示的内容导航的深度。默认情况下,TOC包括 3 层,从<h2><h4>。还可以设置为别的值,比如“ No TOC ”代表不显示,或者设置显示所有级别。

页面上所有更改都需要保存才能生效。

工具栏

编辑器工具栏提供一些特性来调整文章的样式。通常有两行按钮(如果浏览器比较窄,行数会增多),第三层显示当前HTML层级。下面的截图示例中,正在编写顶层的<p>标签。

工具栏的按钮被分成七组。下面会分别介绍并测试每个按钮。

文档选项

文档选项提供了文档级别的控制选项。

源码模式切换
源码模式切换键允许在 WYSIWYG 界面和 HTML 源码模式中切换。尽量避免使用源码模式,因为将会很容易出现与文档风格迥异的部分,也可能根本不生效。
保存并继续编辑
与主界面的“保存并继续编辑”功能相同。
保存并退出
与主界面的“保存并退出”功能相同。
粘贴为纯文本
打开一个对话框来粘贴文本。文本的格式将被去除。粘贴完之后,可以做一些更改,然后点击确认按钮将其插入到文章中。
从 Microsoft Word 中粘贴
在 Windows 平台上,允许从 Microsoft Word 中复制文章,文本会被调整为适应 MDN 的格式。虽然功能有效,但是生成的格式并不一定符合 MDN 的风格,因此不推荐使用。有一些团队确实需要这样的功能。
检查拼写
启动拼写检查。
实时拼写检查
打开一个子菜单,允许控制和配置实时拼写检查。
查找
以“查找”模式打开“查询”面板,允许在文档中搜索特定文字。
替换
以“查找并替换”模式打开“查询面板,允许在文档中搜索特定文字并替换。

需要注意的是,“查找”和“替换”按钮会打开相同的对话框,提供若干选项来配置查询和可选的替换文字。

块级选项

这些按钮提供了在文档中新增或编辑区块的功能。

新增/移除无序列表
在文档中新增或移除一个无序列表。如果你当前正在操作一个无序列表,那么每次按下回车键(return),将会创建一个新项。制表键(tab)可以用来缩进一级。shift-tab键可以用来回到上一级。在空的项目中再次按下回车,将会结束编辑列表。在列表中点击右键将允许编辑列表属性,比如项目符号的形状等。
插入/移除 编号列表
在文档中新增或移除一个有序列表。如果你当前正在操作一个有序列表,那么每次按下回车键(return),将会创建一个新项。制表键(tab)可以用来缩进一级。shift-tab键可以用来回到上一级。在空的项目中再次按下回车,将会结束编辑列表。在列表中点击右键将允许编辑列表属性,比如列表编号的格式(数字、字母、罗马数字等)和起始编号等。
定义列表
在文档中新增一个定义列表。定义列表包含一系列的标题和定义。(比如你正在阅读的区域是一个定义列表。)
定义标题
在定义列表中新增一个标题。如果当前没在编辑一个定义列表,那么将会产生一个新项。在定义标题的时候按下回车(enter)将会自动进入定义描述。
定义描述
在定义列表中新增一个描述。编辑过程中按下回车(enter)将会开始下一项标题。连续按下两次回车将结束定义列表。
减少缩进
将缩进向左移动一次,功能与按下shift-tab键相同。
增加缩进
将缩进向右移动一次,功能与按下shift键相同。
块级引用
插入一个区块。请勿使用。区块不属于编辑标准,这个按钮将会很快被移除。
图片
向文档中插入一个图片。详细使用可以参考Adding images to an article
表格
向文档中插入一个表格。详细使用可以参考Working with tables
文本颜色
设置文本的颜色。请勿使用。我们会很快将所有颜色切换为CSS样式。
背景颜色
设置文本的颜色。请勿使用。我们会很快将所有颜色切换为CSS样式。
文本方向从左至右
设置文本方向为从左至右。用于进行本地化/国际化时。
文本方向从右至左
设置文本方向为从右至左。用于进行本地化/国际化时。

最大化

最大化按钮。这个按钮会将编辑器界面(工具栏和编辑框)充满浏览器窗口,将给予最大的编辑空间。

标题

标题按钮可以插入一个标题。点击一个按钮将会插入相应级别的标题。默认情况下,H2到H4会显示在导航上,可以参考The page info box的描述来改变。

格式样式

这是一个下拉列表,可以选择一个预置的样式,例如:

None
移除所有样式。
Note box
创建一个“注意框”。注意框中的文字应当以加粗的“注意:”开头。

注意: 这是一个注意框。

Warning box
创建一个“警告框”。警告框中的文字应当以加粗的“警告:”开头。

警告: 这是一个警告框!

标注框
创建一个标注框。我们在逐步更新这类框的设计,因此在新的文章中不要使用
双列
在支持的浏览器上,将选中文本或当前区块以双列显示。
三列
在支持的浏览器上,将选中文本或当前区块以三列显示。
Syntax Box
创建一个语法框。需要同时使用“PRE”按钮来创建<pre>框。
foo = bar()
右侧边栏
在内容右侧创建一个浅灰色边栏。可以写一些需要特殊注意的文字。
特殊标注
这是一个右侧栏
SEO描述
这个样式用来标记处一些特殊的句子,这些句子为了满足 SEO 需要,被当成文章描述。也被宏用来自动创建登陆页面。如果不加配置,那么 MDN 会自动选取文章的第一段,有些时候这些句子并不是最好的或者是太长,所以建议编辑这块文字。

代码示例

这些按钮用来预格式化文本(通常是代码示例)。“插入重定向”也是同样的功能。

PRE
插入一个 HTML <pre>  (预格式化文本),或者将当前段落转换为一个 PRE 块。所有代码示例和终端输出都应该是这样的格式。
语法高亮(Syntax highlighter)
语法高亮允许选择一种语言格式来高亮当前 <pre>  段落。如果当前段落不是 PRE ,将会创建一个带语法高亮的PRE 。
插入代码示例模板(Insert code sample template)
这个按钮用来简便地增加一个运行实例。可以查看Using the live sample system
插入代码示例框架(Insert code sample iframe)
在文档中新增一个 <iframe> 来展示已有的运行实例。查看 Using the live sample system 获取更多信息。
创建重定向
新增一个重定向,参考 Creating redirects

行内样式和链接

工具栏最后一组按钮提供创建和编辑链接、应用行内样式等功能。

创建链接(Link)
新增一个链接。点击按钮将会出现一个对话框。
取消链接(Unlink)
取消光标所在位置的链接。
锚点(Anchor)
在光标处新增锚点。
加粗(Bold)
切换是否加粗。
倾斜(Italic)
切换是否倾斜。
下划线(Underline)
切换是否增加下划线。
代码(Code)
切换是否显示为代码(<code>)。用来标记行内的变量名称、函数名称、对象名称、文件名等信息。
删除线(Strike through)
切换是否显示删除线。
上标(Superscript)
切换是否显示为上标。请注意 MDN 上不使用脚注,所以这个功能应当很少被使用。
清除格式(Remove format)
清除选中内容的格式。
左对齐(Align left)
使当前区块左对齐。请勿使用。我们将会很快使用CSS样式来完成对齐功能。
居中(Center)
使当前区块居中。请勿使用。我们将会很快使用CSS样式来完成对齐功能。
右对齐(Align right)
使当前区块右对齐。请勿使用。我们将会很快使用CSS样式来完成对齐功能。

编辑框

编辑框当然指的是编辑内容的区域。在编辑框中右击将会根据所点击内容出现附加功能列表。比如,点击表格将会提供表格相关选项,点击列表将会出现列表相关选项。

修订备注框

当完成更新之后,强烈建议写一段修订备注。这将会出现在页面的修订历史和 Revision Dashboard 中。这有助于向其它编辑者或复核的成员说明你的工作。增加修订备注只需要在保存页面之前点击并在修订备注框中增加内容就可以。

注意:我们知道修订备注框距离保存按钮太远毫无意义,我们正在更改的设计将会解决这个问题。

标签框

标签有助于分类和优化信息,并且标记出需要特别注意的页面。标签也用来标记过时甚至被删除的页面。给页面加上清晰的标签非常重要,请务必给您贡献的页面增加清晰的标签。

标签框在页面的底部,如下所示。

The tag editing box showing three tags.

增加标签

点击文本框然后输入文本就可以增加标签。

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

我们可以看到已经存在的三个标签(像按钮一样)以及一个没有按钮边框的新标签。当你按下EnterTab键(或是逗号)时,新标签将被提交至列表,新的列表如下所示:

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

推荐标签列表及具体标签的使用指南,请查看MDN tagging standards

删除标签

有两种删除标签的方式:你可以点击对应按钮中标签名右侧的"x",或是点击编辑框中该标签的右侧,然后按下键盘上的删除键。

提交你的修改

只有当你点击了编辑页面顶部的任意一个保存按钮,你的修改才会保存。如果你没有看到这些按钮,滚动页面回到的顶部然后点击保存。现在你的修改已经提交了。

评论

MDN试图用评论来监控和提高其内容的质量。通过在文章上设置一个旗标来提示评论。你可以在content reviews中了解更多,并且了解评论在How to help如何起作用。

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";

 

文档标签和贡献者

 最后编辑者: mona,