How to document a CSS property - The MDN project 编辑

As the CSS standards evolve, new properties are always being added. The MDN CSS Reference needs to be kept up to date with these developments. This document gives step-by-step instructions for creating a CSS property reference page.

Each CSS property reference page follows the same structure. This helps readers find information more easily, especially once they are familiar with the standard reference page format.

Step 1 — Decide which property to document

First, you will need to decide which property to document. The CSS Documentation status page lists properties that need to be documented. For details about the CSS property you will need to find a relevant specification for it (e.g., a W3C specification, a Mozilla Wiki page, or a bug report for a non-standard property used in rendering engines like Gecko or Blink).

Pro tips:

• 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!
• If the implementation and spec diverge, feel free to mention it in the implementation bug: it may be a bug in the implementation (and a follow-up bug will be filed), a delay in the publication of a new spec, or an error in the spec (in which case a spec bug is worth filing).

Step 2 — Check the database of CSS properties

Several characteristics of a CSS property, such as its syntax or if it can be animated, are mentioned in several pages and are therefore stored in an ad-hoc database. Macros that you'll use on the page need information about the property that is stored there, so start by checking that this information is there.

If not, contact an admin or a power user, either in the MDN Web Docs (Matrix) chat room, or, if nobody is available, by filing an issue report.

Step 3 — Creating the CSS property page

Preparations 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. Clone the following page, set the title to your-property (without capitals) and the slug to Web/CSS/your-property.
2. Change the summary to fit, but keep it starting the same way : "The your-property CSS property…". Explain briefly what this property is for.
3. If the property is not experimental, remove the {{SeeCompatTable}} macro. The purpose of this macro is to alert developers to the possibility that the feature may not yet have consistent support across browsers, and may change in the future as its specificaton evolves. Deciding whether a feature is experimental is a matter of judgement, and should include factors like:
   • Is the feature supported by several browsers?
   • Is the feature prefixed or behind a preference?
   • Is there any reason to think that the implementation of the feature will change in the future?
4. Replace the parameter of the {{cssinfo("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.
5. 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.
6. 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.
7. Clear the Examples chapter, we will add them at the end!
8. Update the specification table. For information about how to do it, read this tutorial.
9. Update the compatibility information. For information about how to do it, read this tutorial.
10. 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.
11. 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 MDN forum.

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 in Step 3 already helped with this, as it allowed the page 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 there. Only administrator can add it there, so contact MDN staff (via chat)  or file a documentation issue 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.

Contact us

• On Matrix: MDN Web Docs
• Discourse forum