How to set the summary for a page

In this article, we'll show you how to set the SEO summary (also known as the description or just as the summary) of an article on the MDN Web Docs site. The summary is used in a number of ways:

  • It's used by Google and other search engines to help catalog and index pages.
  • Search engines display the summary in search result pages to help readers choose the page that most closely matches their needs.
  • MDN menus and topic landing pages often display the summary below the article title, again to help users find the information they're looking for.
  • Links on MDN frequently have tooltips containing the summary text, to provide quick insight to users without having to click through to the article itself.

The summary should, therefore, be text that makes sense both in the context of the article itself as well as when presented alone in other contexts. You should also keep the MDN writing style guide in mind while writing the summary text.

The default summary

Pages for which no summary has been explicitly set take on a default summary. By default, the summary's text is the entire text of the first block of HTML that looks like it might be text content rather than a title. This is not always the best text to use, however, for a number of possible reasons:

  • The first text block is an aside or note of some kind, rather than a useful overview of the article content.
  • The first text block is a content paragraph but doesn't contain a good overview of the article.
  • The text is too long (or too short).

It's best to explicitly set the page summary, to help ensure that the summary is as helpful as possible.

Setting the summary

Let's look at how to go about setting a page's summary.

What is the task?

Marking the text within a page that should be used as its summary in other contexts; if the appropriate text isn't already available, this task might include writing a small amount of appropriate text.

Where does it need to be done?

On pages that lack a summary, have a summary that isn't helpful, or have a summary that unnecessarily fails to meet recommended guidelines.

What do you need to know to do the task?

Ability to use the MDN editor; good English writing skills; enough familiarity with the topic of the page to write a good summary.

What are the steps to do it?

  1. Pick a page on which to set the summary. If you already have one in mind, great! You can skip to step 2; otherwise, to find a page to fix:
    1. In the MDN documentation status page, click the link under Sections for a topic that you know something about (for example, HTML):
    2. On the topic's documentation status page, click the Pages header in the Summary table. This takes you to an index of all the pages in that topic section; it shows the page links in the left column, and the tags and summaries in the right column:
    3. Pick a page that is missing a summary, or that has a poor summary:
    4. Click the link to go to that page.
  2. Once on the page to which you wish to add a summary, click Edit to open the page in the MDN editor. See the Guide to the MDN editor if you need information about using the editor.
  3. Look for a sentence or two that works as a summary, even if taken out of context. If needed, edit the existing content to create or modify the text until you can select a sentence or two that make a good summary. See Crafting a good summary for help selecting or creating an appropriate summary.
  4. Select the text to be used as a summary.
  5. In the Styles widget of the editor toolbar, select SEO Summary. In the page source, this creates a <span> element with class="seoSummary" around the selected text.
  6. Save your changes with a revision comment. The comment is optional, but we encourage you to provide one. It makes it easier for other people to track the changes. Something like "Set SEO summary" is enough.

Crafting a good summary

The summary is used in many different scenarios, including these:

  • As the description of the article on search results pages on MDN as well as on Google and other search engines.
  • As the description of the article in menus and topic landing pages on MDN itself.
  • In contextual tooltips when the user hovers the cursor over links to articles on MDN.

It's important to keep these scenarios in mind while composing a summary. In order to help ensure that the summary works well in all of these situations, please try to follow the guidelines below.

Note: Unless otherwise specifically stated, these are guidelines, not hard and fast rules. While you should do what you can to meet these guidelines, sometimes there are exceptions that can't be avoided.

  • The summary should indicate both the topic and the type of page. "In this guide, we'll learn to use the Intersection Observer API to create responsive web apps that only update animations that are currently visible on screen." is 160 characters, for example, and explains what technology is being covered, how the technology is being used, and that the article is a tutorial.
  • You can choose text from anywhere within any paragraph in the article, but it should ideally be within the first paragraph (or the second, in some cases). If the point of the article isn't made in those paragraphs, the introduction of the page probably needs rewriting.
  • The summary must still fit well within the context of the article's body, since it is in fact part of the article.
  • It's okay to have links to other pages within the summary. These are automatically removed before being given to search engines, and do not count against you. They're also removed before the summary is used as a tooltip. Links are not removed from the summary when used as a page description within menus and landing pages on MDN, which is really convenient as well.
  • The summary should include an appropriate selection of key terms likely to be searched for by someone looking for information contained on the page. In the example case about the Intersection Observer API, those keywords include the API name, "animations", "visible", "responsive", and "web apps", possibly among others.
  • To optimize the Search Engine Optimization (SEO) value gained from a summary, it should be no longer than 150 characters long.
  • Since a search engine result page (SERP) typically doesn't show more than 160 characters of the summary, you should avoid summaries longer than that. Having your text unceremoniously chopped off can dissuade people from clicking the link.
  • It might be tempting to write a great summary that doesn't work on page, then hide the summary inside a block with the "hidden" class on it. But this doesn't work, because search engines ignore text that's not visible to the user.

Think of the summary as being akin to the blurb on the back or inside the front cover of a book. This short text has to catch the reader's attention quickly and encourage them to read on.

It can be a little tricky to write an summary that works well both for search engine result pages and within the article text itself, but currently MDN doesn't offer a way to create an SEO summary separate from the page content, so do the best you can.

See also