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

Use whichever format you prefer

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 code to use to present something, give guidance both for HTML and for 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 no need to 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.

Example of the HTML code to create a Key Point banner:

<aside class="key-point"><b>Key Point:</b> A colon indicates that
closely-related information follows.</aside>

Specifics:

  • Put the Key Point in an <aside> element.

  • Use title case for the phrase Key Point.

  • Put the phrase Key Point: (including the colon) in bold. (In HTML, use a <b> element.)

  • If the page has more than one key point, then use <p> or <ul> elements inside the <aside>.