Editing the style guide

This page provides guidance for editors at Google about how to write and edit pages in the style guide.

If you want to propose a change to the style guide but you're not part of the group that owns the style guide, then we recommend making your suggestion by using the Send feedback button on an appropriate page of the style guide.

Follow the style guide

In general, the guidance in the style guide applies to style guide pages as well as to documentation, so follow the style guide's guidelines as you edit the style guide.

HTML and Markdown

Choosing a format for a style guide page

If you're creating a new page, you can use HTML or Markdown, at your preference.

If you're editing an existing page, then don't change the file format. In particular, there are several style guide pages that are written in HTML specifically because they use formatting that's hard to replicate in Markdown. In theory, you can use HTML within a Markdown file, but in practice, there are many contexts where you can't.

Support Markdown in your guidance

When you provide guidance about what markup to use in a given situation, give guidance and examples for both HTML and Markdown.

(Some style guide pages don't yet follow this guidance.)

Formatting

A few miscellaneous code-formatting notes:

  • Don't go out of your way to manually reformat lines that you're not otherwise touching. There may be a reason that they're formatted the way they are.

  • If the editing tool that you're using automatically formats lines, then don't manually reformat it in some other way.

  • If possible, hard-wrap the lines that you're working on to 80 columns. But if doing so would be complicated or difficult, then don't.

  • Put an extra blank line before each heading, to make it easier for a human to scan the source document.

Key points

The Key Point banner at the top of the page is a way to briefly show the most important point in the page, so that a visitor to the page can quickly and easily check on the most common and most important style points. In some cases, you may include more than one key point in the Key Point banner, but even if the page has more than one key point, put all of the key points at the top of the page so readers can find them easily.

If a given page has no particular most important points, then leave out the Key Point banner.

Some style guide pages have a Key Point banner that summarizes the topic rather than presenting the most important point. We're working on removing such banners.