Skip to content

Markdown guidelines

Jump to bottom
Sam Richard edited this page Jan 20, 2022 · 2 revisions

Headings

ATX-style headings

✔️

# Heading 1

## Heading 2

Headings with = or - underlines can be annoying to maintain and don't fit with the rest of the heading syntax. The user has to ask: Does --- mean H1 or H2?

🚫

Heading - do you remember what level?
---------

Use unique, complete names for headings

Use unique and fully descriptive names for each heading, even for sub-sections. Since link anchors are constructed from headings, this helps ensure that the automatically constructed anchor links are intuitive and clear.

For example, instead of:

🚫

## Foo
### Summary
### Example
## Bar
### Summary
### Example

prefer:

✔️

## Foo
### Foo Summary
### Foo Example
## Bar
### Bar Summary
### Bar Example

Add spacing to headings

Prefer spacing after # and newlines before and after:

✔️

...text before.

## Heading 2

Text after...

Lack of spacing makes it a little harder to read in source:

🚫

...text before.

##Heading 2
Text after...

Do not use H1s in markdown; use titles in frontmatter instead

Capitalization of titles and headers

Follow the guidance for capitalization in the Google Developer Documentation Style Guide.

Lists

Use lazy numbering for long lists

Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use "lazy" numbering:

✔️

1.  Foo.
1.  Bar.
    1.  Foofoo.
    1.  Barbar.
1.  Baz.

However, if the list is small and you don't anticipate changing it, prefer fully numbered lists, because it's nicer to read in source:

✔️

1.  Foo.
2.  Bar.
3.  Baz.

Nested list spacing

When nesting lists, use a 4 space indent for both numbered and bulleted lists:

✔️

1.  2 spaces after a numbered list.
    4 space indent for wrapped text.
2.  2 spaces again.

*   3 spaces after a bullet.
    4 space indent for wrapped text.
    1.  2 spaces after a numbered list.
        8 space indent for the wrapped text of a nested list.
    2.  Looks nice, don't it?
*   3 spaces after a bullet.

The following works, but it's very messy:

🚫

* One space,
with no indent for wrapped text.
     1. Irregular nesting...

Even when there's no nesting, using the 4 space indent makes layout consistent for wrapped text:

✔️

*   Foo,
    wrapped.

1.  2 spaces
    and 4 space indenting.
2.  2 spaces again.

Code

Text marked as code means:

  1. Render literally. This is a message to the Markdown renderer.
  2. Wrap with <code> tags. This communicates an intent to your reader.

Both are valid usage, and usually overlap.

The definition of "code" here is loose: learn to use code any time you want to show that the text should be precisely as you enter it, such as:

  • Code snippets
  • Command line snippets
  • File names
  • Fake example paths and URLs

Inline

`Backticks` designate inline code that will be rendered literally. Use them for short code quotations, field names, and more:

✔️

You'll want to run `really_cool_script.sh arg`.

Pay attention to the `foo_bar_whammy` field in that table.

Use inline code when referring to file types in a generic sense, rather than a specific existing file:

✔️

Be sure to update your `METADATA` and `README.md`!

Use code span for escaping

When you don't want text to be processed as normal Markdown, like a fake path or example URL that would lead to a bad autolink, wrap it in backticks:

✔️

An example g3doc shortlink would be: `g3doc/foo/g3doc/bar.md`

An example query might be: `https://www.google.com/search?q=$TERM`

Codeblocks

For code quotations longer than a single line, use a fenced codeblock:

✔️

```python
def Foo(self, bar):
  self.bar = bar
```

Only if you need to use three backticks in a code block, which would prematurely end the codeblock, enclose the backticked codeblock in CommonMark tildes:

✔️

~~~markdown
```python
def Foo(self, bar):
  self.bar = bar
```
~~~

Declare the language

It is best practice to explicitly declare the language, so that neither the syntax highlighter nor the next editor must guess.

Use fenced codeblocks instead of indented codeblocks

Four-space indenting is also interpreted as a codeblock. However, we strongly recommend using fenced codeblocks for all codeblocks.

Indented codeblocks can sometimes look cleaner in the source, but they have several drawbacks:

  • You cannot specify the language. Some features are tied to language specifiers.
  • The beginning and end of the codeblock is ambiguous.
  • Indented codeblocks are harder to search for in Code Search.

Escape newlines

Because most commandline snippets are intended to be copied and pasted directly into a terminal, it's best practice to escape any newlines. Use a single backslash at the end of the line:

✔️

```shell
blaze run :target -- --flag --foo=longlonglonglonglongvalue \
  --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
```

Nest codeblocks within lists

If you need a codeblock within a list, make sure to indent it so as to not break the list:

✔️

*   Bullet.

    ```c++
    int foo;
    ```

*   Next bullet.

Links

Long links make source Markdown difficult to read. Wherever possible, shorten your links.

Use informative Markdown link titles

Markdown link syntax allows you to set a link title: use it wisely. Users often do not read documents, they scan them.

Links catch the eye. But titling your links "here", "link", or simply duplicating the target URL tells the hasty reader precisely nothing and is a waste of space:

🚫

See the Markdown guide for more info: [link](https://google.com). Or, check out the
style guide [here](https://google.com).

Check out a typical test result:
[https://google.com)

Instead, write the sentence naturally, then go back and wrap the most appropriate phrase with the link:

✔️

See the [Markdown guide](https://google.com) for more info. Or, check out the
[style guide](https://google.com).

Check out a
[typical test result](https://google.com)

Use reference links carefully {#reference_links}

For long links or image URLs, you may want to split the link use from the link definition, like this:

✔️

See the [g3doc style guide][style], which has suggestions for making docs more
readable.

[style]: https://google.com

Use reference links for long links {#reference_links_long}

Use reference links where the length of the link would detract from the readability of the surrounding text if it were inlined. Reference links make it harder to see the destination of a link in source text, and add additional syntax.

In this example, reference link usage is not appropriate, because the link is not long enough to disrupt the flow of the text:

🚫

The [style guide][style_guide] says not to use reference links unless you have
to.

[style_guide]: http://google.com

In this example, the link destination is long enough that it makes sense to use a reference link:

✔️

The [style guide] says not to use reference links unless you have to.

[style guide]: https://docs.google.com/document/d/13HQBxfhCwx8lVRuN2Wf6poqvAfVeEXmFVcawP5I6B3c/edit

Use reference links more often in tables. It is particularly important to keep table content short, since Markdown does not provide a facility to break text in cell tables across multiple lines, and smaller tables are more readable.

For example, this table's readability is worsened by inline links:

🚫

Site                                                             | Description
---------------------------------------------------------------- | -----------------------
[site 1](http://google.com/excessively/long/path/example_site_1) | This is example site 1.
[site 2](http://google.com/excessively/long/path/example_site_2) | This is example site 2.

Instead, use reference links to keep the line length manageable:

✔️

Site     | Description
-------- | -----------------------
[site 1] | This is example site 1.
[site 2] | This is example site 2.

[site 1]: http://google.com/excessively/long/path/example_site_1
[site 2]: http://google.com/excessively/long/path/example_site_2

Use reference links to reduce duplication {#reference_links_dedupe}

Consider using reference links when referencing the same link destination multiple times in a document, to reduce duplication.

Define reference links after their first use {#reference_links_define}

We recommend putting reference link definitions just before the next heading, at the end of the section in which they're first used.

We define a "section" as all text between two headings. Think of reference links like footnotes, and the current section like the current page.

This arrangement makes it easy to find the link destination in source view, while keeping the flow of text free from clutter. In long documents with lots of reference links, it also prevents "footnote overload" at the bottom of the file, which makes it difficult to pick out the relevant link destination.

There is one exception to this rule: reference link definitions that are used in multiple sections should go to the end of the document. This avoids dangling links when a section is updated or moved.

In the following example, the reference definition is far from its initial use, which makes the document harder to read:

🚫

# Header

Some text with a [link][link_def].

Some more text.

## Header 2

... lots of text ...

## Header 3

Some more text using [link][link_def].

[link_def]: http://reallyreallyreallylonglink.com

Instead, put it just before the header following its first use:

✔️

# Header

Some text with a [link][link_def].

Some more text.

[link_def]: http://reallyreallyreallylonglink.com

## Header 2

... lots of text ...

## Header 3

Some more text using [link][link_def].

Use tables wisely {#tables}

Use tables when they make sense: for the presentation of tabular data that needs to be scanned quickly.

Avoid using tables when your data could easily be presented in a list. Lists are much easier to write and read in Markdown.

For example:

🚫

Fruit  | Metrics      | Grows on | Acute curvature    | Attributes                                                                                                  | Notes
------ | ------------ | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------
Apple  | Very popular | Trees    |                    | [Juicy](http://cs/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet               | Apples keep doctors away.
Banana | Very popular | Trees    | 16 degrees average | [Convenient](http://cs/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes. Don't you? See the [design doc][banana_v2] for the newest hotness in bananiels.

This table illustrates a few typical problems:

  • Poor distribution: Several columns don't differ across rows, and some cells are empty. This is usually a sign that your data may not benefit from tabular display.

  • Unbalanced dimensions: There are a small number of rows relative to columns. When this ratio is unbalanced in either direction, a table becomes little more than an inflexible format for text.

  • Rambling prose in some cells. Tables should tell a succinct story at a glance.

Lists and subheadings sometimes suffice to present the same information. Let's see this data in list form:

✔️

## Fruits

Both types are highly popular, sweet, and grow on trees.

### Apple

*   [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
*   Firm

Apples keep doctors away.

### Banana

*   [Convenient](http://cs/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
*   Soft
*   16 degrees average acute curvature.

Contrary to popular belief, most apes prefer mangoes. Don't you?

See the [design doc][banana_v2] for the newest hotness in bananiels.

The list form is more spacious, and arguably therefore much easier for the reader to find what interests her in this case.

However, there are times a table is the best choice. When you have:

  • Relatively uniform data distribution across two dimensions.
  • Many parallel items with distinct attributes.

In those cases, a table format is just the thing. In fact, a compact table can improve readability:

✔️

Transport        | Favored by     | Advantages
---------------- | -------------- | -----------------------------------------------
Swallow          | Coconuts       | [Fast when unladen][airspeed]
Bicycle          | Miss Gulch     | [Weatherproof][tornado_proofing]
X-34 landspeeder | Whiny farmboys | [Cheap][tosche_station] since the X-38 came out

[airspeed]: http://somereference/airspeed.h
[tornado_proofing]: http://something/kansas/
[tosche_station]: http://urlthingy/power_converter.h

Note that reference links are used to keep the table cells manageable.

Strongly prefer Markdown to HTML

Please prefer standard Markdown syntax wherever possible and avoid HTML hacks. If you can't seem to accomplish what you want:

  1. Discuss with the team
  2. Reconsider whether you really need it. Except for big tables, Markdown meets almost all needs already.

Every bit of HTML hacking reduces the readability and portability of our Markdown corpus. This in turn limits the usefulness of integrations with other tools, which may either present the source as plain text or render it.

Clone this wiki locally