Much of what makes Markdown refreshing is the ability to write plain text and getgreat formatted output as a result. To keep the slate clean for the next author,your Markdown should be simple and consistent with the whole corpus whereverpossible.
We seek to balance three goals:
Contents:
A small set of fresh and accurate docs is better than a sprawling, looseassembly of “documentation” in various states of disrepair.
TheMarkdown way encourages engineers to take ownership of their docs andkeep them up to date with the same zeal we keep our tests in good order. Strivefor this.
The standards for an internal documentation review are different from thestandards for code reviews. Reviewers should ask for improvements, but ingeneral, the author should always be able to invoke the “Better/Best Rule.”
Fast iteration is your friend. To get long-term improvement,authors must stayproductive when making short-term improvements. Set lower standards for eachCL, so thatmore such CLs can happen.
As a reviewer of a documentation CL:
As an author:
Use the original names of products, tools and binaries, preserving thecapitalization. E.g.:
# Markdown style guide`Markdown` is a dead-simple platform for internal engineering documentation.and not
# markdown bad style guide example`markdown` is a dead-simple platform for internal engineering documentation.In general, documents benefit from some variation of the following layout:
# Document TitleShort introduction.[TOC]## TopicContent.## See also* https://link-to-more-info# Document title: The first heading should be a level-one heading, ideallythe same or nearly the same as the filename. The first level-one heading isused as the page<title>.
author:Optional. If you’d like to claim ownership of the document orif you are very proud of it, add yourself under the title. However,revision history generally suffices.
Short introduction. 1–3 sentences providing a high-level overview of thetopic. Imagine yourself as a complete newbie who landed on your “Extending Foo” docand doesn’t know the most basic information you take for granted. “What isFoo? Why would I extend it?”
[TOC]: if you use hosting that supports table of contents, such as Gitiles,put[TOC] after the short introduction. See[TOC] documentation.
## Topic: The rest of your headings should start from level 2.
## See also: Put miscellaneous links at the bottom for the user who wantsto know more or didn’t find what they needed.
[TOC] directiveUse a[TOC] directive unless allof your content is above the fold1 on a laptop.
[TOC] directive after the introductionPlace the[TOC] directive after your page’s introduction and before the firstH2 heading. For example:
# My PageThis is my introduction**before** the TOC.[TOC]## My first H2# My Page[TOC]This is my introduction**after** the TOC where it should not be.## My first H2For users who read your documentation visually, it doesn’t matter where your[TOC] directive is placed, as Markdown always displays the TOC toward the top andto the right of the page. However,[TOC] placement matters a lot when screenreaders or keyboard controls are involved.
That’s because[TOC] inserts the HTML for the table of contents into the DOMwherever you’ve included the directive in your Markdown file. If, for example,you place the directive at the very bottom of your file, screen readers won’tread it until they get to the end of the document.
Markdown content follows the residual convention of an 80-character line limit.Why? Because it’s what most of us do for code.
Tooling integration: All our tooling is designed around code, so themore our documents are formatted according to similar rules, the betterthese tools will work. For example, Code Search doesn’t soft wrap.
Quality. The more engineers use their well-worn coding habits whencreating and editing Markdown content, the better the quality. Markdown takesadvantage of the excellent review culture we already have.
Exceptions to the 80-character rule include:
This means that lines with links are allowed to extend past column 80, alongwith any relevant punctuation:
* See the[foo docs](https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.md). and find the logfile.However, note that text before and after the link gets wrapped.
Tables may also run long. However, there arebest practices for creating short, readable tables.
Foo | Bar | Baz----------------------------------------------------------------------------- | --- | ---Somehow-unavoidable-long-cell-filled-with-content-that-simply-refuses-to-wrap | Foo | BarDon’t use trailing whitespace. Use a trailing backslash to break lines.
TheCommonMark spec decreesthat two spaces at the end of a line should insert a<br /> tag. However, manydirectories have a presubmit check for trailing whitespace, and many IDEs willclean it up anyway.
Use a trailing backslash, sparingly:
For some reason I just really want a break here,\though it's probably not necessary.Best practice is to avoid the need for a<br /> altogether. A pair of newlineswill create a paragraph tag; get used to that.
# Heading 1## Heading 2Headings with= or- underlines can be annoying to maintain and don’t fitwith the rest of the heading syntax. An editor has to ask: Does--- mean H1 orH2?
Heading - do you remember what level? DO NOT DO THIS.---------Use unique and fully descriptive names for each heading, even for sub-sections.Since link anchors are constructed from headings, this helps ensure that theautomatically-constructed anchor links are intuitive and clear.
For example, instead of:
## Foo### Summary### Example## Bar### Summary### Exampleprefer:
## Foo### Foo summary### Foo example## Bar### Bar summary### Bar examplePrefer spacing after# and newlines before and after:
...text before.## Heading 2Text after...Lack of spacing makes it a little harder to read in source:
...text before.##Heading 2Text after... DO NOT DO THIS.Use one H1 heading as the title of your document. Subsequent headings should beH2 or deeper. SeeDocument layout for more information.
Follow the guidance forcapitalizationin theGoogle Developer Documentation Style Guide.
Markdown is smart enough to let the resulting HTML render your numbered listscorrectly. 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 fullynumbered lists, because it’s nicer to read in source:
1. Foo.2. Bar.3. Baz.When nesting lists, use a 4-space indent for both numbered and bulleted lists:
1. Use 2 spaces after the item number, so the text itself is indented 4 spaces. Use a 4-space indent for wrapped text.2. Use 2 spaces again for the next item.* Use 3 spaces after a bullet, so the text itself is indented 4 spaces. Use a 4-space indent for wrapped text. 1. Use 2 spaces with numbered lists, as before. Wrapped text in a nested list needs an 8-space indent. 2. Looks nice, doesn't it?* Back to the bulleted list, indented 3 spaces.The following works, but it’s very messy:
* One space,with no indent for wrapped text. 1. Irregular nesting... DO NOT DO THIS.Even when there’s no nesting, using the 4 space indent makes layout consistentfor wrapped text:
* Foo, wrapped with a 4-space indent.1. Two spaces for the list item and 4 spaces before wrapped text.2. Back to 2 spaces.However, when lists are small, not nested, and a single line, one space cansuffice for both kinds of lists:
* Foo* Bar* Baz.1. Foo.2. Bar.`Backticks` designateinline code that will be rendered literally. Usethem 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 aspecific existing file:
Be sure to update your`README.md`!When you don’t want text to be processed as normal Markdown, like a fake path orexample URL that would lead to a bad autolink, wrap it in backticks:
An example Markdown shortlink would be:`Markdown/foo/Markdown/bar.md`An example query might be:`https://www.google.com/search?q=$TERM`For code quotations longer than a single line, use a fenced code block:
```pythondef Foo(self, bar): self.bar = bar```
It is best practice to explicitly declare the language, so that neither thesyntax highlighter nor the next editor must guess.
Four-space indenting is also interpreted as a code block. However, we stronglyrecommend fencing for all code blocks.
Indented code blocks can sometimes look cleaner in the source, but they haveseveral drawbacks:
You'll need to run: bazel run :thing -- --fooAnd then: bazel run :another_thing -- --barAnd again: bazel run :yet_again -- --bazBecause most command-line snippets are intended to be copied and pasted directlyinto a terminal, it’s best practice to escape any newlines. Use a singlebackslash at the end of the line:
```shell$ bazel run :target -- --flag --foo=longlonglonglonglongvalue \ --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue```
If you need a code block within a list, make sure to indent it so as to notbreak the list:
* Bullet. ```c++ int foo; ```* Next bullet.You can also create a nested code block with 4 spaces. Simply indent 4additional spaces from the list indentation:
* Bullet. int foo;* Next bullet.Long links make source Markdown difficult to read and break the 80 characterwrapping.Wherever possible, shorten your links.
Use the explicit path for Markdown links. For example:
[...](/path/to/other/markdown/page.md)You don’t need to use the entire qualified URL:
[...](https://bad-full-url.example.com/path/to/other/markdown/page.md)Relative paths are fairly safe within the same directory. For example:
[...](other-page-in-same-dir.md)[...](/path/to/another/dir/other-page.md)Avoid relative links if you need to specify other directories with../:
[...](../../bad/path/to/another/dir/other-page.md)Markdown link syntax allows you to set a link title. Use it wisely. Users oftendo not read documents; they scan them.
Links catch the eye. But titling your links “here,” “link,” or simplyduplicating the target URL tells the hasty reader precisely nothing and is awaste of space:
DO NOT DO THIS.See the Markdown guide for more info:[link](markdown.md), or check out thestyle guide[here](/styleguide/docguide/style.html).Check out a typical test result:[https://example.com/foo/bar](https://example.com/foo/bar).Instead, write the sentence naturally, then go back and wrap the mostappropriate phrase with the link:
See the[Markdown guide](markdown.md) for more info, or check out the[style guide](/styleguide/docguide/style.html).Check out a[typical test result](https://example.com/foo/bar).For long links or image URLs, you may want to split the link use from the linkdefinition, like this:
See the[Markdown style guide][style], which has suggestions for making docs morereadable.[style]: http://Markdown/corp/Markdown/docs/reference/style.mdUse reference links where the length of the link would detract from thereadability of the surrounding text if it were inlined. Reference links make itharder to see the destination of a link in source text, and add additionalsyntax.
In this example, reference link usage is not appropriate, because the link isnot long enough to disrupt the flow of the text:
DO NOT DO THIS.The[style guide][style_guide] says not to use reference links unless you haveto.[style_guide]: https://google.com/Markdown-styleJust inline it instead:
https://google.com/Markdown-style says not to use reference links unless you have to.In this example, the link destination is long enough that it makes sense to usea reference link:
The [style guide] says not to use reference links unless you have to.[style guide]: https://docs.google.com/document/d/13HQBxfhCwx8lVRuN2Wf6poqvAfVeEXmFVcawP5I6B3c/editUse reference links more often in tables. It is particularly important to keeptable content short, since Markdown does not provide a facility to break text incell tables across multiple lines, and smaller tables are more readable.
For example, this table’s readability is worsened by inline links:
DO NOT DO THIS.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_2Consider using reference links when referencing the same link destinationmultiple times in a document, to reduce duplication.
We recommend putting reference link definitions just before the next heading, atthe end of the section in which they’re first used. If your editor has its ownopinion about where they should go, don’t fight it; the tools always win.
We define a “section” as all text between two headings. Think of reference linkslike 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 ofreference 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 inmultiple sections should go at the end of the document. This avoids danglinglinks 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 FOR A BAD DOCUMENTSome text with a[link][link_def].Some more text with the same[link][link_def].## Header 2... lots of text ...## Header 3Some more text using a[different_link][different_link_def].[link_def]: http://reallyreallyreallylonglink.com[different_link_def]: http://differentreallyreallylonglink.comInstead, put it just before the header following its first use:
# HeaderSome text with a[link][link_def].Some more text with the same[link][link_def].[link_def]: http://reallyreallyreallylonglink.com## Header 2... lots of text ...## Header 3Some more text using a[different_link][different_link_def].[different_link_def]: http://differentreallyreallylonglink.comSeeimage syntax.
Use images sparingly, and prefer simple screenshots. This guide is designedaround the idea that plain text gets users down to the business of communicationfaster with less reader distraction and author procrastination. However, it’ssometimes very helpful to show what you mean.
Use tables when they make sense: for the presentation of tabular data that needsto be scanned quickly.
Avoid using tables when your data could easily be presented in a list. Lists aremuch easier to write and read in Markdown.
For example:
DO NOT DO THISFruit | 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 somecells are empty. This is usually a sign that your data may not benefit fromtabular display.
Unbalanced dimensions: There are a small number of rows relative tocolumns. When this ratio is unbalanced in either direction, a table becomeslittle more than an inflexible format for text.
Rambling prose in some cells. Tables should tell a succinct story at aglance.
Lists and subheadings sometimes suffice to present the sameinformation. Let’s see this data in list form:
## FruitsBoth types are highly popular, sweet, and grow on trees.### Apple*[Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)* FirmApples 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 thereader to find what interests her in this case.
However, there are times a table is the best choice. When you have:
In those cases, a table format is just the thing. In fact, a compact table canimprove 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 XP-38 came out[airspeed]: http://google3/airspeed.h[tornado_proofing]: http://google3/kansas/[tosche_station]: http://google3/power_converter.hNote thatreference links are used to keep the table cellsmanageable.
Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.If you can’t seem to accomplish what you want, reconsider whether you reallyneed it. Except forbig tables, Markdown meets almost all needsalready.
Every bit of HTML hacking reduces the readability and portability of ourMarkdown corpus. This in turn limits the usefulness of integrations with othertools, which may either present the source as plain text or render it. SeePhilosophy.
Gitiles does not render HTML.
Content is “above the fold” if it is visible when the page is firstdisplayed. Content is “below the fold” if it is hidden until the userscrolls down the page on a computer or literally unfolds a documentsuch as a newspaper. ↩