MDN সম্পাদকের সহায়িকা

by 1 contributor:

দ্রষ্টব্য: কিভাবে আপনি মোজিলা ডেভেলপার নেটওয়ার্কে অবদান রাখবেন, এই নিবন্ধটিতে সে সম্পর্কে বিস্তারিত আলোচনা করা হয়েছে। চূড়ান্ত কাজ করার আগে এটাকে কয়েকটি সাব পেজে বিভক্ত করা হবে।

মোজিলা ডেভেলপার নেটওয়ার্কের WYSIWYG (what-you-see-is-what-you-get) এডিটর নতুন কনটেন্ট তৈরি তথা অবদান রাখার প্রক্রিয়াকে সহজ করেছে। কিভাবে আপনি এই এডিটর ব্যবহার করবেন, সে সম্পর্কে মোজিলা ডেভেলপার নেটওয়ার্কের সম্পাদকের সহায়িকা কিছু তথ্য দেয়। এবং তার সাথে আপনার উৎপাদন ক্ষমতা উন্নয়নের জন্য আরও কিছু ফিচার সম্পর্কেও তথ্য পাবেন।

MDN এর স্টাইল গাইড এর মধ্যে ফরম্যাটিং ও স্টাইলিং সম্পর্কে বিস্তারিত তথ্য ও আমাদের পছন্দনীয় ব্যাকরণ ও বানানরীতির বর্ণনা রয়েছে।

সম্পাদকের ইন্টারফেস

নিচের ছবিতে দেখানো সম্পাদক উইন্ডোটি আটটি প্রধান অংশের সমন্নয়ে গঠিত। নিবন্ধের এই অংশে আপনি এই আটটি অংশের ব্যবহার সম্পর্কে আলাদা আলাদা ভাবে জানতে পারবেন।

দ্রষ্টব্যঃ আমরা সবসময় MDN এর উন্নয়নে আকজ করে যাচ্ছি। তাই যেকোনো সময় যেকোনো কিছুর পরিবর্তন হচ্ছে। আর এ কারনেই কিছু কিছু স্ক্রিনশট অনেক সময় নাও মিলতে পারে। আমরা সবসময় চেষ্টা করব, সকল পরিবর্তন সম্পর্কে MDN কে হালনাগাদ রাখার। কিন্তু তারপরও যদি কোথাও আপনারা কোন ত্রুটি খুঁজে পান, সাথে সাথে মেইল করে বা আমাদের ফেসবুক গ্রুপে জানাতে পারেন।

পৃষ্ঠার নিয়ন্ত্রক

পৃষ্ঠার নিয়ন্ত্রক এলাকা হচ্ছে, যেখানে সমগ্র পৃষ্ঠার মধ্যে পরিবর্তন আনার জন্য বোতাম থাকেঃ

Save and keep editing
এটি আলাদা কোন পৃষ্ঠায় না গিয়ে, আপনি যেই পৃষ্ঠায় কাজ করছেন, সেখানেই থেকে আপনার নতুন পরিবর্তন গুলোকে সংরক্ষন করার কাজ করে। এই বোতামটি নতুন পৃষ্ঠা তৈরি করার সময় থাকে না। কিন্তু একবার যখন আপনি একটি নতুন পৃষ্ঠা তৈরি করে ফেলেছেন এবং একবার সংরক্ষন করেছেন, তারপর থেকে আপনি এই বোতামটি পাবেন। আর আপনারা আগেই জেনেছেন যে, নতুন কোন কিছু সম্পাদনা করলে মন্তব্য করতে হয়। তাই এই বোতামটি চাপার আগেও অবশ্যই মন্তব্য করতে হবে। আরও বিস্তারিত জানার জন্য The revision comment box দেখুন।
লক্ষ্য করুনঃ যেহেতু আমাদের দেশে ঘন ঘন বিদ্যুৎ চলে যায়, তাই এই বোতামটি আমাদের সবচেয়ে বেশি কাজে লাগবে। আর আমরা জানি যে বেশিরভাগ ওয়ার্ড প্রসেসিং সফটওয়্যারে ctrl+s চাপলে সেভ হয়। এই বোতামটিও ctrl+s এর কাজ করে।
Save changes
এই বোতামটি চাপলে আপনার করা পরিবর্তন গুলো সংরক্ষন হবে, আর নতুন সংরক্ষন সহ সম্পূর্ণ পাতাটি লোড হবে। অর্থাৎ আগের মত আর এডিটর পেজে থাকবে না। এডিটিং অপশন চলে গিয়ে সম্পূর্ণ পাতাটি আসবে। আর সব পরিবর্তন সংরক্ষনের পূর্বশর্ত হিসেবে এই বোতামটি চাপার আগেও মন্তব্য করতে হবে। বিস্তারিত জানতে The revision comment box দেখুন।
Preview changes
এই বোতামটি চাপলে আপনার খসড়া পরিবর্তন সহ নতুন একটি ট্যাব আসবে। এটি ব্যবহার করে আপনার করা পরিবর্তন গুলো সংরক্ষন করা ছাড়াই সংরক্ষন পরবর্তী অবস্থা দেখতে পারবেন। এটি ব্যবহার করার সময় মনে রাখবেন যে, এটি শুধু আপনার পরিবর্তন গুলোর খসড়া দেখাবে। এই বোতামটি চাপার মাধ্যমে কোন কিছু সংরক্ষন হবে না। এটা ব্যবহার করে আপনি দেখতে পারবেন, যে আপনি যে কাজটি করছেন, তা ঠিকঠাক হচ্ছে কি না; বা কোথাও ভুল হচ্ছে কি না। আর যেহেতু এটার মাধ্যমে কোন কিছু সংরক্ষন হচ্ছে না, তাই এক্ষেত্রে মন্তব্য না করলেও চলবে।
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.

Finding samples that need updating

When looking for existing samples to update, there are three main kinds of updating you may wish to do:

  1. Turn an existing non-live example snippet into a live sample.
  2. Correct bugs in an existing live sample.
  3. Improve an existing live sample, or update a sample based on technology changes.

Note: If you find an article that has samples in need of being updated to use the live sample system, please add the tag "NeedsLiveSample" to the page.

Finding samples to turn into live samples

MDN has lots of older examples that don't yet use the live sample system. Our goal is to update most or all of these to be live samples. This will improve consistency and usability. You will almost certainly find many of these as you use MDN on a daily basis; however, how can you find them if you're specifically looking for them to update? Unfortunately, there's not an easy way to do that. But there are some guidelines you can follow to help track them down:

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

 

ডকুমেন্ট ট্যাগ এবং অবদানকারী

Contributors to this page: badsha_eee
সর্বশেষ হালনাগাদ করেছেন: badsha_eee,