How to write and reference an entry in the glossary

In this article, we cover how to add and link to entries in the MDN Web Docs glossary. We also provide guidelines about glossary entry layout and content. The glossary provides definitions for all of the terms, jargon, abbreviations, and acronyms you'll come across when reading about the web and about web development.

The glossary isn't, and possibly never will be, complete! The web is always changing and always growing. You can help us keep the glossary up-to-date, and to fill in any gaps, by contributing new entries to the glossary (or even by fixing problems you spot with existing entries).

Contributing to the glossary is an easy way to help make the web easier for everyone to understand. You don't need a high level of technical skill to do so, either, since glossary entries are intended to be straightforward and brief.

How to write an entry

If you're looking for topics that need a glossary entry, check the list of undocumented terms at the end of the Glossary landing page; click any of those links to start a new Glossary page for the item you clicked; then follow the steps below.

If you have an idea for a new glossary entry , just open the following button in a new tab, and then follow the steps below the button:

Step 1: Select a term to explain

The first thing to do is to choose a term to write about. If you don't know which terms are in need of definitions, you can check out our list of suggestions. Just click one and get started writing! If you're logged in already, you'll wind up in the MDN editor.

Step 2: Write a summary

The first paragraph of any glossary page is a simple and short description of the term (preferably no more than two sentences). Make sure anyone reading the description can understand the defined term immediately.

Note: Please don't copy-and-paste definitions from elsewhere (especially not Wikipedia, since its range of license versions is smaller, and thus incompatible with that of MDN). It's really important to make sure this content is simple and easy to understand. It's worth spending some time on it rather than stealing content blindly. This glossary should be useful new content, not repeating things from elsewhere.

Writing a good glossary entry

If you must, you can add a few extra paragraphs, but it's very easy to find yourself writing a whole article. Writing a whole article is fine, but please don't put it in the glossary. If you aren't sure where to put your article, feel free to reach out to discuss it.

A few simple guidelines to consider while writing a glossary entry that may help you create a better one:

  • When you use terms in the glossary's description of the term or abbreviation, you should create appropriate links for them. Often, this will just involve creating links to other pages in the glossary (see How to use the Glossary macro below). For terms directly related to the term being described by the glossary, it may be more useful to link to MDN Web Docs' main body article on the topic.
  • Try to use appropriate related terms (with links) within your article if it can be done without making the article hard to follow. Having a good web of related, useful inks can make a page or set of pages much easier to use.
  • Think about what you would type into a search engine if you wanted to find this page. Try to use all the words you'd search on in the article, without making the article nonsensical, overly long, or difficult to read.

Specifying the tooltip

As is the case with most MDN links, hovering the mouse cursor over a glossary link will show a brief description of the page (in this case, a short summary of the term's definition). By default, the tooltip is the entire first paragraph of the article, but this is often too long.

You can specify a subsection of text that will be used as the page summary (and therefore the tooltip text) by selecting a sentence or two that best summarize the definition of the term, then adding the "SEO Summary" style to them. This not only establishes the tooltip text, but also specifies the text that will be sent to Google and other search engines when they ask for a brief summary describing the page contents. For that reason, specifically selecting a page summary is also valuable for helping your new page get found more easily.

Note: Ideally, the summary should be between 150-160 characters; less is okay, more is not as good but won't break anything, either.

Finally, a glossary entry should always end with a "Learn more" section. This section should contain links to help the reader move forward: discovering more details, learning to use the relevant technology, and so on.

We recommend that you sort the links into at least these three groups:

General knowledge
Links that provide more general information; for example, such as a link to a relevant page on Wikipedia.
Technical reference
Links to more in-depth technical information, on MDN Web Docs or elsewhere.
Learn about it
Links to tutorials, exercises, examples, or any other materials that help the reader learn to use the technology behind the defined term.

Dealing with disambiguation

Sometimes, a term has several meanings depending on the context. To resolve the ambiguities, you must follow those guidelines:

  • The term's main page must be a disambiguation page containing the GlossaryDisambiguation macro.
  • The term has subpages that define the term for a given context.

Let's illustrate that with an example. The term signature can have different meanings in at least three different contexts: security, function and email.

  1. The page Glossary/Signature is the disambiguation page with the GlossaryDisambiguation macro.
  2. The page Glossary/Signature/Security is the page defining a signature in a security context.
  3. The page Glossary/Signature/Function is the page defining a function signature.
  4. The page Glossary/Signature/Email is the page defining email signature.

How to use the {{Glossary}} macro

The glossary is much more useful when people can access the definitions from another document without navigating away from what they're reading. Therefore we urge you to link to the glossary whenever you can, using the Glossary macro:

Macro Result Note
{{Glossary("browser")}} browser When a text matches the term to be defined, just use the macro as is (it's case insensitive)
{{Glossary("browser", "Web browser")}} Web browser To display an alternative text, use the second argument to specify that text
{{Glossary("browser", "Web browser", 1)}} Web browser Specify 1 as an optional third argument to display the link as a regular link rather than a subtle hint

Links created with the {{Glossary}} macro always display a tooltip containing the glossary entry's summary paragraph or the "SEO summary" if one has been selected as described in Specifying the tooltip above.

Using the macro wisely

In many cases, it's perfectly safe to use the Glossary macro anywhere on MDN. There are a couple of guidelines to consider, though:

  • If a term already has a link to an appropriate page somewhere else on MDN, don't replace the link with a glossary link.
  • Within an article section, use the {{Glossary}} macro only once for the same term (hint: a section always starts with a title).