mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
Google Documentation Guide
Includes Markdown Style Guide See docguide/README.md
This commit is contained in:
parent
43d738ab8b
commit
edccafae5a
10
docguide/README.md
Normal file
10
docguide/README.md
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# Google documentation guide
|
||||||
|
|
||||||
|
* [Markdown styleguide](style.md)
|
||||||
|
* [Best practices](best_practices.md)
|
||||||
|
* [README files](READMEs.md)
|
||||||
|
* [Philosophy](philosophy.md)
|
||||||
|
|
||||||
|
## See also
|
||||||
|
|
||||||
|
* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.
|
69
docguide/READMEs.md
Normal file
69
docguide/READMEs.md
Normal file
|
@ -0,0 +1,69 @@
|
||||||
|
# README.md files
|
||||||
|
|
||||||
|
About README.md files.
|
||||||
|
|
||||||
|
1. [Overview](#overview)
|
||||||
|
1. [Guidelines](#guidelines)
|
||||||
|
1. [Filename](#filename)
|
||||||
|
1. [Contents](#contents)
|
||||||
|
1. [Example](#example)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
`README.md` files are Markdown files that describe a directory.
|
||||||
|
GitHub and Gitiles renders it when you browse the directory.
|
||||||
|
|
||||||
|
For example, the file /README.md is rendered when you view the contents of the
|
||||||
|
containing directory:
|
||||||
|
|
||||||
|
https://github.com/google/styleguide/tree/gh-pages
|
||||||
|
|
||||||
|
Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
|
||||||
|
index:
|
||||||
|
|
||||||
|
https://gerrit.googlesource.com/gitiles/
|
||||||
|
|
||||||
|
## Guidelines
|
||||||
|
|
||||||
|
**`README.md` files are intended to provide orientation for engineers browsing
|
||||||
|
your code, especially first-time users.** The `README.md` is likely the first
|
||||||
|
file a reader encounters when they browse a directory that
|
||||||
|
contains your code. In this way, it acts as a landing page for the directory.
|
||||||
|
|
||||||
|
We recommend that top-level directories for your code have an up-to-date
|
||||||
|
`README.md` file. This is especially important for package directories that
|
||||||
|
provide interfaces for other teams.
|
||||||
|
|
||||||
|
### Filename
|
||||||
|
|
||||||
|
Use `README.md`.
|
||||||
|
|
||||||
|
Files named `README` are not displayed in the directory view in Gitiles.
|
||||||
|
|
||||||
|
### Contents
|
||||||
|
|
||||||
|
At minimum, every package-level `README.md` should include or point to the
|
||||||
|
following information:
|
||||||
|
|
||||||
|
1. **What** is in this package/library and what's it used for.
|
||||||
|
2. **Who** to contact.
|
||||||
|
3. **Status**: whether this package/library is deprecated, or not for general
|
||||||
|
release, etc.
|
||||||
|
4. **More info**: where to go for more detailed documentation, such as:
|
||||||
|
* An overview.md file for more detailed conceptual information.
|
||||||
|
* Any API documentation for using this package/library.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# APIs
|
||||||
|
|
||||||
|
This is the top-level directory for all externally-visible APIs, plus some
|
||||||
|
private APIs under `internal/` directories.
|
||||||
|
See [API Style Guide](docs/apistyle.md) for more information.
|
||||||
|
|
||||||
|
*TL;DR*: API definitions and configurations should be defined in `.proto` files,
|
||||||
|
checked into `apis/`.
|
||||||
|
|
||||||
|
...
|
||||||
|
```
|
1
docguide/VERSION
Normal file
1
docguide/VERSION
Normal file
|
@ -0,0 +1 @@
|
||||||
|
1.0
|
115
docguide/best_practices.md
Normal file
115
docguide/best_practices.md
Normal file
|
@ -0,0 +1,115 @@
|
||||||
|
# Documentation Best Practices
|
||||||
|
|
||||||
|
"Say what you mean, simply and directly." - [Brian Kernighan]
|
||||||
|
(http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
1. [Minimum viable documentation](#minimum-viable-documentation)
|
||||||
|
1. [Update docs with code](#update-docs-with-code)
|
||||||
|
1. [Delete dead documentation](#delete-dead-documentation)
|
||||||
|
1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
|
||||||
|
|
||||||
|
## Minimum viable documentation
|
||||||
|
|
||||||
|
A small set of fresh and accurate docs are better than a sprawling, loose
|
||||||
|
assembly of "documentation" in various states of disrepair.
|
||||||
|
|
||||||
|
Write short and useful documents. Cut out everything unnecessary, while also
|
||||||
|
making a habit of continually massaging and improving every doc to suit your
|
||||||
|
changing needs. **Docs work best when they are alive but frequently trimmed,
|
||||||
|
like a bonsai tree**.
|
||||||
|
|
||||||
|
This guide encourages engineers to take ownership of their docs and keep
|
||||||
|
them up to date with the same zeal we keep our tests in good order. Strive for
|
||||||
|
this.
|
||||||
|
|
||||||
|
* Identify what you really need: release docs, API docs, testing guidelines.
|
||||||
|
* Delete cruft frequently and in small batches.
|
||||||
|
|
||||||
|
## Update docs with code
|
||||||
|
|
||||||
|
**Change your documentation in the same CL as the code change**. This keeps your
|
||||||
|
docs fresh, and is also a good place to explain to your reviewer what you're
|
||||||
|
doing.
|
||||||
|
|
||||||
|
A good reviewer can at least insist that docstrings, header files, README.md
|
||||||
|
files, and any other docs get updated alongside the CL.
|
||||||
|
|
||||||
|
## Delete dead documentation
|
||||||
|
|
||||||
|
Dead docs are bad. They misinform, they slow down, they incite despair in
|
||||||
|
engineers and laziness in team leads. They set a precedent for leaving behind
|
||||||
|
messes in a code base. If your home is clean, most guests will be clean without
|
||||||
|
being asked.
|
||||||
|
|
||||||
|
Just like any big cleaning project, **it's easy to be overwhelmed**. If your
|
||||||
|
docs are in bad shape:
|
||||||
|
|
||||||
|
* Take it slow, doc health is a gradual accumulation.
|
||||||
|
* First delete what you're certain is wrong, ignore what's unclear.
|
||||||
|
* Get your whole team involved. Devote time to quickly scan every doc and make
|
||||||
|
a simple decision: Keep or delete?
|
||||||
|
* Default to delete or leave behind if migrating. Stragglers can always be
|
||||||
|
recovered.
|
||||||
|
* Iterate.
|
||||||
|
|
||||||
|
## Prefer the good over the perfect
|
||||||
|
|
||||||
|
Your documentation should be as good as possible within a reasonable time frame.
|
||||||
|
The standards for an documentation review are different from the
|
||||||
|
standards for code reviews. Reviewers can and should ask for improvements, but
|
||||||
|
in general, the author should always be able to invoke the "Good Over Perfect
|
||||||
|
Rule". It's preferable to allow authors to quickly submit changes that improve
|
||||||
|
the document, instead of forcing rounds of review until it's "perfect". Docs are
|
||||||
|
never perfect, and tend to gradually improve as the team learns what they really
|
||||||
|
need to write down.
|
||||||
|
|
||||||
|
## Documentation is the story of your code
|
||||||
|
|
||||||
|
Writing excellent code doesn't end when your code compiles or even if your
|
||||||
|
test coverage reaches 100%. It's easy to write something a computer understands,
|
||||||
|
it's much harder to write something both a human and a computer understand. Your
|
||||||
|
mission as a Code Health-conscious engineer is to **write for humans first,
|
||||||
|
computers second.** Documentation is an important part of this skill.
|
||||||
|
|
||||||
|
There's a spectrum of engineering documentation that ranges from terse comments
|
||||||
|
to detailed prose:
|
||||||
|
|
||||||
|
1. **Inline comments**: The primary purpose of inline comments is to provide
|
||||||
|
information that the code itself cannot contain, such as why the code is
|
||||||
|
there.
|
||||||
|
|
||||||
|
2. **Method and class comments**:
|
||||||
|
|
||||||
|
* **Method API documentation**: The header / Javadoc / docstring
|
||||||
|
comments that say what methods do and how to use them. This
|
||||||
|
documentation is **the contract of how your code must behave**. The
|
||||||
|
intended audience is future programmers who will use and modify your
|
||||||
|
code.
|
||||||
|
|
||||||
|
It is often reasonable to say that any behavior documented here should
|
||||||
|
have a test verifying it. This documentation details what arguments the
|
||||||
|
method takes, what it returns, any "gotchas" or restrictions, and what
|
||||||
|
exceptions it can throw or errors it can return. It does not usually
|
||||||
|
explain why code behaves a particular way unless that's relevant to a
|
||||||
|
developer's understanding of how to use the method. "Why" explanations
|
||||||
|
are for inline comments. Think in practical terms when writing method
|
||||||
|
documentation: "This is a hammer. You use it to pound nails."
|
||||||
|
|
||||||
|
* **Class / Module API documentation**: The header / Javadoc / docstring
|
||||||
|
comments for a class or a whole file. This documentation gives a brief
|
||||||
|
overview of what the class / file does and often gives a few short
|
||||||
|
examples of how you might use the class / file.
|
||||||
|
|
||||||
|
Examples are particularly relevant when there's several distinct ways to
|
||||||
|
use the class (some advanced, some simple). Always list the simplest
|
||||||
|
use case first.
|
||||||
|
|
||||||
|
3. **README.md**: A good README.md orients the new user to the directory and
|
||||||
|
points to more detailed explanation and user guides:
|
||||||
|
* What is this directory intended to hold?
|
||||||
|
* Which files should the developer look at first? Are some files an API?
|
||||||
|
* Who maintains this directory and where I can learn more?
|
||||||
|
|
||||||
|
See the [README.md guidelines](READMEs.md).
|
71
docguide/philosophy.md
Normal file
71
docguide/philosophy.md
Normal file
|
@ -0,0 +1,71 @@
|
||||||
|
# Philosophy
|
||||||
|
|
||||||
|
埏埴以為器,當其無,有器之用.
|
||||||
|
|
||||||
|
*Clay becomes pottery through craft, but it's the emptiness that makes a pot
|
||||||
|
useful.*
|
||||||
|
|
||||||
|
\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
1. [Radical simplicity](#radical-simplicity)
|
||||||
|
1. [Readable source text](#readable-source-text)
|
||||||
|
1. [Minimum viable documentation](#minimum-viable-documentation)
|
||||||
|
1. [Better is better than perfect](#better-is-better-than-perfect)
|
||||||
|
|
||||||
|
## Radical simplicity
|
||||||
|
|
||||||
|
* **Scalability and interoperability** are more important than a menagerie of
|
||||||
|
unessential features. Scale comes from simplicity, speed, and ease.
|
||||||
|
Interoperability comes from unadorned, digestable content.
|
||||||
|
|
||||||
|
* **Fewer distractions** make for better writing and more productive reading.
|
||||||
|
|
||||||
|
* **New features should never interfere with the simplest use case** and should
|
||||||
|
remain invisible to users who don't need them.
|
||||||
|
|
||||||
|
* **This guide is designed for the average engineer** -- the busy,
|
||||||
|
just-want-to-go-back-to-coding engineer. Large and complex documentation is
|
||||||
|
possible but not the primary focus.
|
||||||
|
|
||||||
|
* **Minimizing context switching makes people happier.** Engineers should be
|
||||||
|
able to interact with documentation using the same tools they use to read and
|
||||||
|
write code.
|
||||||
|
|
||||||
|
## Readable source text
|
||||||
|
|
||||||
|
* **Plain text not only suffices, it is superior**. Markdown itself is not
|
||||||
|
essential to this formula, but it is the best and most widely supported
|
||||||
|
solution right now. HTML is generally not encouraged.
|
||||||
|
|
||||||
|
* **Content and presentation should not mingle**. It should always be possible
|
||||||
|
to ditch the renderer and read the essential information at source. Users
|
||||||
|
should never have to touch the presentation layer if they don't want to.
|
||||||
|
|
||||||
|
* **Portability and future-proofing leave room for the unimagined integrations
|
||||||
|
to come**, and are best achieved by keeping the source as human-readable as
|
||||||
|
possible.
|
||||||
|
|
||||||
|
* **Static content is better than dynamic**, because content should not depend
|
||||||
|
on the features of any one server. However, **fresh is better than stale**. We
|
||||||
|
strive to balance these needs.
|
||||||
|
|
||||||
|
## Minimum viable documentation
|
||||||
|
|
||||||
|
* **Docs thrive when they're treated like tests**: a necessary chore one learns
|
||||||
|
to savor because it rewards over time.
|
||||||
|
See [Best Practices](best_practices.md).
|
||||||
|
|
||||||
|
* **Brief and utilitarian is better than long and exhaustive**. The vast
|
||||||
|
majority of users need only a small fraction of the author's total knowledge,
|
||||||
|
but they need it quickly and often.
|
||||||
|
|
||||||
|
## Better is better than perfect
|
||||||
|
|
||||||
|
* **Incremental improvement is better than prolonged debate**. Patience and
|
||||||
|
tolerance of imperfection allow projects to evolve organically.
|
||||||
|
|
||||||
|
* **Don't lick the cookie, pass the plate**. We're drowning in potentially
|
||||||
|
impactful projects. Choose only those you can really handle and release those
|
||||||
|
you can't.
|
420
docguide/style.md
Normal file
420
docguide/style.md
Normal file
|
@ -0,0 +1,420 @@
|
||||||
|
# Markdown style guide
|
||||||
|
|
||||||
|
Much of what makes Markdown great is the ability to write plain text, and get
|
||||||
|
great 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 wherever
|
||||||
|
possible.
|
||||||
|
|
||||||
|
We seek to balance three goals:
|
||||||
|
|
||||||
|
1. *Source text is readable and portable.*
|
||||||
|
2. *Markdown files are maintainable over time and across teams.*
|
||||||
|
3. *The syntax is simple and easy to remember.*
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
1. [Document layout](#document-layout)
|
||||||
|
1. [Character line limit](#character-line-limit)
|
||||||
|
1. [Trailing whitespace](#trailing-whitespace)
|
||||||
|
1. [Headings](#headings)
|
||||||
|
1. [ATX-style headings](#atx-style-headings)
|
||||||
|
1. [Add spacing to headings](#add-spacing-to-headings)
|
||||||
|
1. [Lists](#lists)
|
||||||
|
1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
|
||||||
|
1. [Nested list spacing](#nested-list-spacing)
|
||||||
|
1. [Code](#code)
|
||||||
|
1. [Inline](#inline)
|
||||||
|
1. [Codeblocks](#codeblocks)
|
||||||
|
1. [Declare the language](#declare-the-language)
|
||||||
|
1. [Escape newlines](#escape-newlines)
|
||||||
|
1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
|
||||||
|
1. [Links](#links)
|
||||||
|
1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
|
||||||
|
1. [Images](#images)
|
||||||
|
1. [Prefer lists to tables](#prefer-lists-to-tables)
|
||||||
|
1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
|
||||||
|
|
||||||
|
## Document layout
|
||||||
|
|
||||||
|
In general, most documents benefit from some variation of the following layout:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Document Title
|
||||||
|
|
||||||
|
Short introduction.
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
## Topic
|
||||||
|
|
||||||
|
Content.
|
||||||
|
|
||||||
|
## See also
|
||||||
|
|
||||||
|
* https://link-to-more-info
|
||||||
|
```
|
||||||
|
|
||||||
|
1. `# Document Title`: The first heading should be a level one heading, and
|
||||||
|
should ideally be the same or nearly the same as the filename. The first
|
||||||
|
level one heading is used as the page `<title>`.
|
||||||
|
|
||||||
|
1. `author`: *Optional*. If you'd like to claim ownership of the document or
|
||||||
|
if you are very proud of it, add yourself under the title. However,
|
||||||
|
revision history generally suffices.
|
||||||
|
|
||||||
|
1. `Short introduction.` 1-3 sentences providing a high-level overview of the
|
||||||
|
topic. Imagine yourself as a complete newbie, who landed on your "Extending
|
||||||
|
Foo" doc and needs to know the most basic assumptions you take for granted.
|
||||||
|
"What is Foo? Why would I extend it?"
|
||||||
|
|
||||||
|
1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
|
||||||
|
put `[TOC]` after the short introduction. See
|
||||||
|
[`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
|
||||||
|
|
||||||
|
1. `## Topic`: The rest of your headings should start from level 2.
|
||||||
|
|
||||||
|
1. `## See also`: Put miscellaneous links at the bottom for the user who wants
|
||||||
|
to know more or didn't find what she needed.
|
||||||
|
|
||||||
|
## Character line limit
|
||||||
|
|
||||||
|
Obey the character line limit wherever possible. Long URLs and tables are the
|
||||||
|
usual suspects when breaking the rule. (Headings also can't be wrapped, but we
|
||||||
|
encourage keeping them short.) Otherwise, wrap your text:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
|
||||||
|
hendrerit, id nobis saperet fuisset ius.
|
||||||
|
|
||||||
|
* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
|
||||||
|
interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
|
||||||
|
```
|
||||||
|
|
||||||
|
Often, inserting a newline before a long link preserves readability while
|
||||||
|
minimizing the overflow:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Lorem ipsum dolor sit amet. See the
|
||||||
|
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
|
||||||
|
for details.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Trailing whitespace
|
||||||
|
|
||||||
|
Don't use trailing whitespace, use a trailing backslash.
|
||||||
|
|
||||||
|
The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
|
||||||
|
that two spaces at the end of a line should insert a `<br />` tag. However, many
|
||||||
|
directories have a trailing whitespace presubmit check in place, and many IDEs
|
||||||
|
will clean it up anyway.
|
||||||
|
|
||||||
|
Best practice is to avoid the need for a `<br />` altogether. Markdown creates
|
||||||
|
paragraph tags for you simply with newlines: get used to that.
|
||||||
|
|
||||||
|
## Headings
|
||||||
|
|
||||||
|
### ATX-style headings
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## 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?
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Heading - do you remember what level? DO NOT DO THIS.
|
||||||
|
---------
|
||||||
|
```
|
||||||
|
|
||||||
|
### Add spacing to headings
|
||||||
|
|
||||||
|
Prefer spacing after `#` and newlines before and after:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
...text before.
|
||||||
|
|
||||||
|
# Heading 1
|
||||||
|
|
||||||
|
Text after...
|
||||||
|
```
|
||||||
|
|
||||||
|
Lack of spacing makes it a little harder to read in source:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
...text before.
|
||||||
|
|
||||||
|
#Heading 1
|
||||||
|
Text after... DO NOT DO THIS.
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
1. Foo.
|
||||||
|
2. Bar.
|
||||||
|
3. Baz.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Nested list spacing
|
||||||
|
|
||||||
|
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
* 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 consistent
|
||||||
|
for wrapped text:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
* Foo,
|
||||||
|
wrapped.
|
||||||
|
|
||||||
|
1. 2 spaces
|
||||||
|
and 4 space indenting.
|
||||||
|
2. 2 spaces again.
|
||||||
|
```
|
||||||
|
|
||||||
|
However, when lists are small, not nested, and a single line, one space can
|
||||||
|
suffice for both kinds of lists:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
* Foo
|
||||||
|
* Bar
|
||||||
|
* Baz.
|
||||||
|
|
||||||
|
1. Foo.
|
||||||
|
2. Bar.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code
|
||||||
|
|
||||||
|
### Inline
|
||||||
|
|
||||||
|
`Backticks` designate `inline code`, and will render all wrapped content
|
||||||
|
literally. Use them for short code quotations and field names:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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 an abstract sense, rather than a
|
||||||
|
specific file:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Be sure to update your `README.md`!
|
||||||
|
```
|
||||||
|
|
||||||
|
Backticks are the most common approach for "escaping" Markdown metacharacters;
|
||||||
|
in most situations where escaping would be needed, code font just makes sense
|
||||||
|
anyway.
|
||||||
|
|
||||||
|
### Codeblocks
|
||||||
|
|
||||||
|
For code quotations longer than a single line, use a codeblock:
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
```python
|
||||||
|
def Foo(self, bar):
|
||||||
|
self.bar = bar
|
||||||
|
```
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
#### Declare the language
|
||||||
|
|
||||||
|
It is best practice to explicitly declare the language, so that neither the
|
||||||
|
syntax highlighter nor the next editor must guess.
|
||||||
|
|
||||||
|
#### Indented codeblocks are sometimes cleaner
|
||||||
|
|
||||||
|
Four-space indenting is also interpreted as a codeblock. These can look
|
||||||
|
cleaner and be easier to read in source, but there is no way to specify the
|
||||||
|
language. We encourage their use when writing many short snippets:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
You'll need to run:
|
||||||
|
|
||||||
|
bazel run :thing -- --foo
|
||||||
|
|
||||||
|
And then:
|
||||||
|
|
||||||
|
bazel run :another_thing -- --bar
|
||||||
|
|
||||||
|
And again:
|
||||||
|
|
||||||
|
bazel run :yet_again -- --baz
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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:
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
```shell
|
||||||
|
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
|
||||||
|
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
|
||||||
|
```
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
#### Nest codeblocks within lists
|
||||||
|
|
||||||
|
If you need a codeblock within a list, make sure to indent it so as to not break
|
||||||
|
the list:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
* Bullet.
|
||||||
|
|
||||||
|
```c++
|
||||||
|
int foo;
|
||||||
|
```
|
||||||
|
|
||||||
|
* Next bullet.
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also create a nested code block with 4 spaces. Simply indent 4
|
||||||
|
additional spaces from the list indentation:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
* Bullet.
|
||||||
|
|
||||||
|
int foo;
|
||||||
|
|
||||||
|
* Next bullet.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Links
|
||||||
|
|
||||||
|
Long links make source Markdown difficult to read and break the 80 character
|
||||||
|
wrapping. **Wherever possible, shorten your links**.
|
||||||
|
|
||||||
|
### Use informative Markdown link titles
|
||||||
|
|
||||||
|
Markdown link syntax allows you to set a link title, just as HTML does. Use it
|
||||||
|
wisely.
|
||||||
|
|
||||||
|
Titling your links as "link" or "here" tells the reader precisely nothing when
|
||||||
|
quickly scanning your doc and is a waste of space:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
See the syntax guide for more info: [link](syntax_guide.md).
|
||||||
|
Or, check out the style guide [here](style_guide.md).
|
||||||
|
DO NOT DO THIS.
|
||||||
|
```
|
||||||
|
|
||||||
|
Instead, write the sentence naturally, then go back and wrap the most
|
||||||
|
appropriate phrase with the link:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
See the [syntax guide](syntax_guide.md) for more info.
|
||||||
|
Or, check out the [style guide](style_guide.md).
|
||||||
|
```
|
||||||
|
|
||||||
|
## Images
|
||||||
|
|
||||||
|
Use images sparingly, and prefer simple screenshots. This guide is designed
|
||||||
|
around the idea that plain text gets users down to the business of communication
|
||||||
|
faster with less reader distraction and author procrastination. However, it's
|
||||||
|
sometimes very helpful to show what you mean.
|
||||||
|
|
||||||
|
See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
|
||||||
|
|
||||||
|
## Prefer lists to tables
|
||||||
|
|
||||||
|
Any tables in your Markdown should be small. Complex, large tables are difficult
|
||||||
|
to read in source and most importantly, **a pain to modify later**.
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Fruit | Attribute | Notes
|
||||||
|
--- | --- | --- | ---
|
||||||
|
Apple | [Juicy](http://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
|
||||||
|
Banana | [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
|
||||||
|
|
||||||
|
DO NOT DO THIS
|
||||||
|
```
|
||||||
|
|
||||||
|
[Lists](#lists) and subheadings usually suffice to present the same information
|
||||||
|
in a slightly less compact, though much more edit-friendly way:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Fruits
|
||||||
|
|
||||||
|
### Apple
|
||||||
|
|
||||||
|
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
|
||||||
|
* Firm
|
||||||
|
* Sweet
|
||||||
|
|
||||||
|
Apples keep doctors away.
|
||||||
|
|
||||||
|
### Banana
|
||||||
|
|
||||||
|
* [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
|
||||||
|
* Soft
|
||||||
|
* Sweet
|
||||||
|
|
||||||
|
Contrary to popular belief, most apes prefer mangoes.
|
||||||
|
```
|
||||||
|
|
||||||
|
However, there are times when a small table is called for:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Transport | Favored by | Advantages
|
||||||
|
--- | --- | ---
|
||||||
|
Swallow | Coconuts | Otherwise unladen
|
||||||
|
Bicycle | Miss Gulch | Weatherproof
|
||||||
|
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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, reconsider whether you really
|
||||||
|
need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
|
||||||
|
all needs already.
|
||||||
|
|
||||||
|
Every bit of HTML or Javascript hacking reduces the readability and portability.
|
||||||
|
This in turn limits the usefulness of integrations with
|
||||||
|
other tools, which may either present the source as plain text or render it. See
|
||||||
|
[Philosophy](philosophy.md).
|
||||||
|
|
||||||
|
Gitiles does not render HTML.
|
Loading…
Reference in New Issue
Block a user