How to document a CSS property

Little by little new properties are added to CSS. The MDN CSS Reference needs to be kept up-to-date with these developments. This document describes how to add a CSS property reference page by guiding you step by step.

Each CSS property reference page follows the same structure: it allows the reader to find the relevant information quickly once familiar with how and where the information is displayed. With that, the amount of search to find a specific information in the references, is reduced enormously for the everyday reader.

Step 1 — Decide which property to document

First, you need to decide which property to document. For example, the CSS Documentation status page list properties that need to be documented. To know more details about the new CSS property you need to find a relevant specification for it (e.g. a W3C specification, a wikimo page with further details or a bug report containing information for a non-standard property an rendering engine like Gecko or Blink implements).

Pro tip: when using a W3C spec, always use the Editor's Draft (note the red banner on the left side) and not a published version (e.g. Working Draft). The Editor's Draft is always closer to the final version!

Step 2 — Update the database of CSS properties

Several characteristics of a CSS property, like its syntax or if it can be animated, are mentioned in several pages and are therefore stored in an ad-hoc database. This database consists of four pages and each property must be described on one single line.

These pages are:

CSS values syntax
Defines the syntax, the initial value, and the media types the properties apply to.
CSS animated properties
Defines which properties can be animated, and how.
CSS values serialization
Defines the kind of elements each property applies to, how the value will be computed, and the order in which value will appear when the serialization happens.
CSS percentage values
Defines the meaning of percentages for each property.

In order to unify the textual wording of our reference, and to provide the right HTML formatting, a whole lot of macros to ease the editing of these pages have been created and should be used within these pages. The following steps are guiding you through updating these database pages.

Step 2a — Getting the right information out of the specification

A fundamental element is that we document what is in the specification. That means the reference page is based on the latest iteration of that specification and later on there are compatibility notes stressing the differences between different specification versions and their different implementations by rendering engines.

Once you have found the relevant specification, the first thing to do is to look for a property definition in the specification. Look for the summary table (near the bottom), it has most of the values that you are looking for:

The summary table lists useful attributes of the CSS properties defined in the give spec.

In some specifications, especially in older drafts, there isn't such a property index table. In this case you need to look for the property box of the property itself which looks like this:

This box lists most useful attributes of a CSS property.

Note that in some cases the property index table might be more briefly and with less details than the property box.

Step 2b — Update CSS values syntax page

Now that you have found the right information, you can start updating the first database page. The first one contains the syntax, initial value and the media types associated with the property. Go to the CSS values syntax page that looks like this:

Shows the different columns of the CSS values syntax table

Click the Edit button and look for the section that corresponds to the CSS property you are documenting. If you don't find it, you can create one or add it to the Miscellaneous section at the bottom of it. If you are unsure, don't worry, it is easy to change this later, just ask the CSS driver on IRC or per e-mail.

Now create the missing line and fill it:

  1. Lists the row-related operation of a table: Insert a row before or after the current location or delete the selected rows.Add a line to the table:
    • Go to the nearest line.
    • Open the context menu with a right click.
    • Go to Row .
    • Choose Insert Row Before or Insert Row After to create the new row.
  2. The property name is in the first column, as the parameter of the 'cssxref' macro. Insert the name of the CSS property in the first column (labeled "Property") by using the {{cssxref("")}} macro.

    For example, for text-combine-horizontal:

    {{cssxref("text-combine-horizontal")}}

     

  3. Copy the syntax as it appears in the specification inside a {{csssyntaxdef()}} macro: the first parameter is the property name and the second the syntax itself.

    For example, for text-combine-horizontal:

    {{csssyntaxdef("text-combine-horizontal", "none | all | [ digits <integer>? ]")}}

    Some properties are using an intermediary CSS type to make the definition easier to read, like border-width is defined by <br-width>{1,4}. In this case add both definitions, the second with a parameter "non-terminal" meaning that the word "where" must be added (or its equivalent in other language), separated by <br/> (that you can insert simply by pressing Shift-ENTER).

    For example, for border-width:

    {{csssyntaxdef("border-width","<br-width>{1,4}")}}
    {{csssyntaxdef("br-width", "<length> | thin | medium | thick", "non-terminal")}}
  4. Then, copy the initial value as it appears inside a {{cssinitialdef()}} macro: the first parameter is the property name and the second the initial value itself.

    For example, for text-combine-horizontal:

    {{cssinitialdef("text-combine-horizontal", "none")}}

    Some values have complex initial values that can vary according to the context. In this case, you need to add some textual information to it. This textual information may contain links or specific HTML.

    To achieve this, use the two macros {{cssinitialstartdef}} and {{cssinitialenddef}}. The first one takes one single parameter, the property name, and the second has no parameter. These two macros are acting like an opening and a closing tag, you can add your formatted text as needed between these two macros. For example, the text-align property has the following initial value entry:

    {{cssinitialstartdef("text-align")}}start, or a nameless value that acts as left if direction is ltr, right if {{cssxref("direction")}} is rtl if start is not supported by the browser.{{cssinitialenddef}}

    Another special case are shorthand properties resetting non-defined longhand properties to their initial value. The initial value of a shorthand property is the aggregation of the initial values of each of the longhand properties they are linked to. If one of these changes, the initial value of the shorthand changes as well. To guarantee coherence, the {{cssinitialshorthand}} macro should be used. Like all related macros, its first parameter is the name of the property; the second parameter is a space-separated list of the longhand properties associated to the shorthand.

    For example, for flex-flow:

    {{cssinitialshorthand("flex-flow", "flex-direction flex-wrap")}}
  5. The fourth column indicates if an unspecified property's value is inherited from its parent or not. It is a toggle and there are two macros to choose from: {{cssdoesinherit}} that indicates that a child element may inherit the value of its parent and {{cssnotinherited}} telling that the parent value will not be used (but the initial value will be instead). Both macros require a single parameter, the name of the property.

    For example, for text-combine-horizontal:

    {{cssdoesinherit("text-combine-horizontal")}}
  6. The last column contains the information of the kind of media the property belongs to. The {{cssmediadef}} macro has to be used for this porpose. Its first parameter is, as usual, the name of the property, the second is a comma-separated list of media types and groups, as it appears on the Media: line in the CSS specification.

    For example, for text-combine-horizontal:

    {{cssmediadef("text-combine-horizontal", "visual")}}
  7. The last step is to add a comment in the comment box beneath the article edit zone, then to click the SAVE CHANGES button at the top. The updated page should appear after a few seconds and no error message should be displayed. If so, click EDIT again and check your recent addition; a common error is to forget a parenthesis or a quote (" or ') in one of the macros.

Step 2c — Update CSS animated properties page

First database page updated! Onto the next one! The second is the CSS animated properties page with the information about how the CSS property you are documenting can be animated, if possible. Go to the page and add an empty row to the table like in step 2b. Apply the following steps:

  1. Like in Step 2b, add the name of the CSS property in the first column (labeled "Property"), using the {{cssxref("")}} macro.

  2. Then add the animation data in the second and last column. The animation data is usually in the property box in the specification, but on older specs, it may be missing. In this case look into this table of the CSS Transition specification, which lists all animation data about properties standardized before animations. If it isn't in the list (and the information is not in its spec), it can't be animated. If you are unsure, don't hesitate to ask the CSS driver.

    If the property is not animatable, the {{cssnotanimatabledef}} macro has to be used; it needs only one argument, the name of the property. If the property is animatable, the {{cssanimatabledef}} macro is the one to use; it takes three arguments:

    • Like usual, the first parameter is the name of the property.
    • The second parameter is a space-separated list of keywords, indicating how the animation will be done. The following keywords are available:
      Keyword Corresponding text in spec
      color as color
      integer as integer
      number as number
      length as length
      lpc as length, percentage, or calc
      transform as transform
      shadowlist as shadow list
      visibility as visibility
      rectangle as rectangle
      font_stretch as font stretch
      font_weight as font weight
      simplelist a simple list of …
      repeatablelist as a repeated list of …
    • The third parameter is an optional comment. If needed, which should be unusual, please start it with a '.'.

    Finally, if the property is a shorthand, similarly to what has been done for initial values, use the {{cssanimatableshorthand}} macro: its first parameter is the name of the property; the second parameter is a space-separated list of the longhand properties associated to the shorthand.

  3. Again, the last step is to add a comment in the comment box beneath the article edit zone, then to click the SAVE CHANGES button at the top. The updated page should appear after a few seconds.

Step 2d — Update the CSS values serialization page

Onto the third database page! The next step will be about updating the CSS values serialization page. Here again, go to the page and add an empty row at the same position in the tables. Then apply the folowing steps:

  1. Add the name of the CSS property in the first column (labeled "Property"), using the {{cssxref("")}} macro.

  2. Note that there isn't any specific macro for shorthands as the Applies to value is necessary common to all the longhand properties associated to it.

    1. Use the {{cssappliestostartdef}} macro, which takes the property name as its single parameter, as a start tag. After that, you can add all the relevant information and formatting you like. You end by adding the closing tag, the macro {{cssappliestoendef}}, which doesn't need any parameter.
  3. Once this is done, move to the next column, Computed value, which is named after the same corresponding line or column in the specification. Here you have four different macros to consider:

    1. Use the {{csscomputedasspecifieddef}} macro that only takes the property name as the parameter. This is the most common case, and corresponds to the case where the specification uses "As specified" as the computed value.
    2. Use the {{csscomputedstartdef}} macro, which takes the property name as its single parameter, as a start tag. After it, you can add all the relevant information and formatting you like. You end by adding the closing tag, the macro {{csscomputedendef}}, which doesn't need any parameter.
    3. Use the {{csscomputedshorthand}} macro, that again only takes the property name as the parameter. This is needed for shorthand properties: its first parameter is the name of the property; the second parameter is a space-separated list of the longhand properties associated to the shorthand.
    4. Use the {{csscomputedcolordef}} macro (one single parameter, the property name). This is suitable for properties that take a <color> value which is quite complex to compute. That way, the description is unified between the documented properties.
  4. Finally, the last column, Canonical order, contains information about how a property value can be serialized. Again, you have different macros available:
    1. Use the {{cssuniqueorderdef}} macro that only takes the property name as the parameter. This is the most common case: the syntax of available values is non-ambiguous, it defines one single way of serializing the value. E. g. properties whose values are one of many keywords, or of one simple CSS type.
    2. Use the {{cssorderofappearancedef}} macro (one single parameter, the property name). This covers most properties using a '||' and a collection of values.
    3. For more complex case, use the {{cssorderdef}} macro. It takes two parameters, the property name and a string containing the text to display. This pretty rare, but is often used in the case where a relative value is transformed to its absolute counterpart when serializing.
    4. Finally, the couple {{csscomputedstartdef}} (one single parameter, the property name) and {{csscomputedendef}} (no parameter) may be used.
  5. Finally, the last step is to add a comment in the comment box beneath the article edit zone, then to click the SAVE CHANGES button at the top. The updated page should appear after a few seconds.

Step 2e — Update the CSS percentage values page

Onto the last database page! The next step will be about updating the CSS percentage values page. Go to the page and add an empty row at the same position in the tables. Then apply the folowing steps:

  1. Add the name of the CSS property in the first column (labeled "Property"), using the {{cssxref("")}} macro.

  2. Then add the percentage data in the second and last column.

    1. Quite a lot of properties don't accept percentage values; in these cases see the {{csscssnopercentagedef}} macro, which takes the property name as its single parameter, as a start tag.
    2. For the properties accepting percentage values, use the {{csscsspercentagedef}} macro. The first argument is the property name, and the second is a text explaining what the percentage refers to.
  3. Finally, the last step is to add a comment in the comment box beneath the article edit zone, then to click the SAVE CHANGES button at the top. The updated page should appear after a few seconds.

Step 3 — Creating the CSS property page

Preperations finished! Now we can add the actual CSS property page. The easiest way to create a new CSS property page is to copy the content of an existing page and to edit it. We will go through the different steps now.

Cloning a page is currently broken on MDN. That's why we need to go through these somewhat more complex steps. Please vote for (bug 870691).

  1. First open the following page and copy its content to your clipboard.
  2. Remove animation-name$edit from the URL and replace it by the name of the CSS property you want to create a document for, then hit RETURN. You should have an empty page, at the right position in the hierarchy and with the right title.
  3. Insert the content of the clipboard inside the page: you now have the correct structure already.
  4. Change the summary to fit, but keep it starting the same way : "The your-property CSS property…". Explain briefly what this property is for.
  5. If the property is not experimental, remove the {{SeeCompatTable}} macro. A property is not experimental if it is on the standard track (that is, in an official spec), its spec is a Candidate Recommendation, a Proposed Recommendation, or a Recommendation, and it is not listed as a feature at risk in it. If the property is not on the standard track, replace the macro by the {{Not_standard}} macro.
  6. Replace the parameter of the {{cssbox("animation-name")}} macro by the name of the CSS property you are documenting. This will allow you to build the summary box using the data you entered in step 2.
  7. Replace the example of the syntax by relevant ones. Keep them very simple and don't forget that a lot of people don't understand a formal syntax so it needs to be simple and exhaustive. Keep the inherit, initial, and unset keywords examples at the end. It reminds users that these are valid values, too.
  8. Under the chapter Values, put the meaning of each value. If it is a keyword, don't forget to mark it as code (select it and press CTRL-O). Each description should start by "Is a" followed by the type of the value, or indicating it is a keyword.
  9. Clear the Examples chapter, we will add its content later on.
  10. Update the specification table. For information about how to do it, read this tutorial.
  11. Update the compatibility information. For information about how to do it, read this tutorial.
  12. Update the See also section with relevant links. Do not link to specs here and usually link to internal documents. External documents are welcome, but only if they bring really good information. There are spam or SEO links often, so don't worry if external links are removed sometimes. Just start the discussion if you still find it useful and want to see it back.
  13. Add the relevant tags: you need to add CSS, CSS Property, and Reference. You also need to add Experimental or Non-standard if this is the case. Finally you also need to add a CSS XYZ tag, where XYZ stands for the group of CSS properties it belongs to. It is often the spec short name. All these tags are used to generate quicklinks and other niceties.

At any point, you can save by hitting the SAVE button. You can continue to edit right along. If you haven't saved your page until now, please do so! :-)

The last step is to add Examples. To do that follow this tutorial about live samples. Don't forget that we are in a document explaining one single property: you need to add examples that show how this  property is working in isolation, not how the whole specification is used. That means, examples for list-style-type will show what the different values generate, but not how to combine it with other property, pseudo-classes or pseudo-elements to generate nice effects; tutorials and guide can be written to show more.

Step 4 — Getting a review

You have documented your CSS property! Congratulations!

In order to have a good quality and consistency throughout the MDN CSS reference, it is good practice to request a review. Just click on the checkbox at the bottom of the article (in edit mode), and, optional, if you want to have a more personal review helping you to improve editorial skills, ask for it on the dev-mdc mailing list.

Step 5 — Integrating the new page in the MDN

Now that your page is created, you want it to be found by the readers. Adding tags helped about this already as it allowed it to appear in the quicklinks to related CSS pages. Also you want it to appear on the CSS index page. If the newly documented property is on the standard track and at least one major browser is implementing it, it deserves to be listed this. Only administrator can add it there, so contact the CSS driver on IRC (currently at #mdn ping teoli) or file a documentation bug requesting it.

Also, if the property is implemented by Firefox, you need to check that it is listed, and linked! in the correct Firefox for developers MDN page. The new CSS property is likely already listed in the HTML section, just be sure that its name links back to your newly created page.

Help the 'CSS' documentation project…
Topic driver : Jean-Yves Perrier (IRC nickname: teoli)
Look at the current status of the 'CSS' documentation.
Don't hesitate to contact us on #mdn or on the dev-mdc mailing-list:

Document Tags and Contributors

Contributors to this page: Sebastianz, stephaniehobson, dharkness, FredB, Sheppy, teoli, fscholz
Last updated by: Sebastianz,
Hide Sidebar