@ -606,287 +609,431 @@ Index of /path/to/somewhere
</main>
<!-- var NONE -->
<footerclass="markup"><h1>Markdown: Syntax</h1>
<h2>Overview</h2>
<h3>Philosophy</h3>
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
<p>Readability, however, is emphasized above all else. A Markdown-formatted
document should be publishable as-is, as plain text, without looking
like it's been marked up with tags or formatting instructions. While
Markdown's syntax has been influenced by several existing text-to-HTML
filters -- including <ahref="http://docutils.sourceforge.net/mirror/setext.html">Setext</a>, <ahref="http://www.aaronsw.com/2002/atx/">atx</a>, <ahref="http://textism.com/tools/textile/">Textile</a>, <ahref="http://docutils.sourceforge.net/rst.html">reStructuredText</a>,
<ahref="http://www.triptico.com/software/grutatxt.html">Grutatext</a>, and <ahref="http://ettext.taint.org/doc/">EtText</a> -- the single biggest source of
inspiration for Markdown's syntax is the format of plain text email.</p>
<h2>Block Elements</h2>
<h3>Paragraphs and Line Breaks</h3>
<p>A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a
blank line -- a line containing nothing but spaces or tabs is considered
blank.) Normal paragraphs should not be indented with spaces or tabs.</p>
<p>The implication of the "one or more consecutive lines of text" rule is
that Markdown supports "hard-wrapped" text paragraphs. This differs
significantly from most other text-to-HTML formatters (including Movable
Type's "Convert Line Breaks" option) which translate every line break
character in a paragraph into a <code><br /></code> tag.</p>
<p>When you <em>do</em> want to insert a <code><br /></code> break tag using Markdown, you
end a line with two or more spaces, then type return.</p>
<h3>Headers</h3>
<p>Markdown supports two styles of headers, [Setext] [1] and [atx] [2].</p>
<p>Optionally, you may "close" atx-style headers. This is purely
cosmetic -- you can use this if you think it looks better. The
closing hashes don't even need to match the number of hashes
used to open the header. (The number of opening hashes
determines the header level.)</p>
<h3>Blockquotes</h3>
<p>Markdown uses email-style <code>></code> characters for blockquoting. If you're
familiar with quoting passages of text in an email message, then you
know how to create a blockquote in Markdown. It looks best if you hard
wrap the text and put a <code>></code> before every line:</p>
<blockquote>
<p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
<p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.</p>
</blockquote>
<p>Markdown allows you to be lazy and only put the <code>></code> before the first
line of a hard-wrapped paragraph:</p>
<blockquote>
<p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
</blockquote>
<blockquote>
<p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.</p>
</blockquote>
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
adding additional levels of <code>></code>:</p>
<blockquote>
<p>This is the first level of quoting.</p>
<blockquote>
<p>This is nested blockquote.</p>
</blockquote>
<p>Back to the first level.</p>
</blockquote>
<p>Blockquotes can contain other Markdown elements, including headers, lists,
<p><codeclass="language-plaintext highlighter-rouge">## Topic</code>: The rest of your headings should start from level 2.</p>
</li>
<li>
<p><codeclass="language-plaintext highlighter-rouge">## See also</code>: Put miscellaneous links at the bottom for the user who wants
to know more or didn’t find what she needed.</p>
</li>
</ol>
<h2id="character-line-limit">Character line limit</h2>
<p>Obey projects’ 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:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
hendrerit, id nobis saperet fuisset ius.
<spanclass="p">
*</span> Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
interesset. See the <spanclass="p">[</span><spanclass="nv">foo docs</span><spanclass="p">](</span><spanclass="sx">https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md</span><spanclass="p">)</span>.
</code></pre></div></div>
<p>Often, inserting a newline before a long link preserves readability while
minimizing the overflow:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>Lorem ipsum dolor sit amet. See the
<p>Headings with <codeclass="language-plaintext highlighter-rouge">=</code> or <codeclass="language-plaintext highlighter-rouge">-</code> underlines can be annoying to maintain and don’t fit
with the rest of the heading syntax. The user has to ask: Does <codeclass="language-plaintext highlighter-rouge">---</code> mean H1 or
H2?</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="gh">Heading - do you remember what level? DO NOT DO THIS.
---------
</span></code></pre></div></div>
<h3id="add-spacing-to-headings">Add spacing to headings</h3>
<p>Prefer spacing after <codeclass="language-plaintext highlighter-rouge">#</code> and newlines before and after:</p>
<h3id="nested-list-spacing">Nested list spacing</h3>
<p>When nesting lists, use a 4 space indent for both numbered and bulleted lists:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="p">1.</span> 2 spaces after a numbered list.
4 space indent for wrapped text.
<spanclass="p">2.</span> 2 spaces again.
<spanclass="p">
*</span> 3 spaces after a bullet.
4 space indent for wrapped text.
<spanclass="p"> 1.</span> 2 spaces after a numbered list.
8 space indent for the wrapped text of a nested list.
<spanclass="p"> 2.</span> Looks nice, don't it?
<spanclass="p">*</span> 3 spaces after a bullet.
</code></pre></div></div>
<p>The following works, but it’s very messy:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="p">*</span> One space,
with no indent for wrapped text.
<spanclass="p"> 1.</span> Irregular nesting... DO NOT DO THIS.
</code></pre></div></div>
<p>Even when there’s no nesting, using the 4 space indent makes layout consistent
<p>`Backticks` designate <codeclass="language-plaintext highlighter-rouge">inline code</code>, and will render all wrapped content
literally. Use them for short code quotations and field names:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>You'll want to run <spanclass="sb">`really_cool_script.sh arg`</span>.
Pay attention to the <spanclass="sb">`foo_bar_whammy`</span> field in that table.
</code></pre></div></div>
<p>Use inline code when referring to file types in an abstract sense, rather than a
specific file:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>Be sure to update your <spanclass="sb">`README.md`</span>!
</code></pre></div></div>
<p>Backticks are the most common approach for “escaping” Markdown metacharacters;
in most situations where escaping would be needed, code font just makes sense
anyway.</p>
<h3id="codeblocks">Codeblocks</h3>
<p>For code quotations longer than a single line, use a codeblock:</p>
<pre>
```python
def Foo(self, bar):
self.bar = bar
```
</pre>
</footer>
<h4id="declare-the-language">Declare the language</h4>
<p>It is best practice to explicitly declare the language, so that neither the
syntax highlighter nor the next editor must guess.</p>
<h4id="indented-codeblocks-are-sometimes-cleaner">Indented codeblocks are sometimes cleaner</h4>
<p>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:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>You'll need to run:<spanclass="sb">
bazel run :thing -- --foo
</span>And then:<spanclass="sb">
bazel run :another_thing -- --bar
</span>And again:<spanclass="sb">
bazel run :yet_again -- --baz
</span></code></pre></div></div>
<h4id="escape-newlines">Escape newlines</h4>
<p>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:</p>
<pre>
```shell
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
<p>Long links make source Markdown difficult to read and break the 80 character
wrapping. <strong>Wherever possible, shorten your links</strong>.</p>
<h3id="use-informative-markdown-link-titles">Use informative Markdown link titles</h3>
<p>Markdown link syntax allows you to set a link title, just as HTML does. Use it
wisely.</p>
<p>Titling your links as “link” or “here” tells the reader precisely nothing when
quickly scanning your doc and is a waste of space:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>See the syntax guide for more info: <spanclass="p">[</span><spanclass="nv">link</span><spanclass="p">](</span><spanclass="sx">syntax_guide.md</span><spanclass="p">)</span>.
Or, check out the style guide <spanclass="p">[</span><spanclass="nv">here</span><spanclass="p">](</span><spanclass="sx">style_guide.md</span><spanclass="p">)</span>.
DO NOT DO THIS.
</code></pre></div></div>
<p>Instead, write the sentence naturally, then go back and wrap the most
appropriate phrase with the link:</p>
<divclass="language-markdown highlighter-rouge"><divclass="highlight"><preclass="highlight"><code>See the <spanclass="p">[</span><spanclass="nv">syntax guide</span><spanclass="p">](</span><spanclass="sx">syntax_guide.md</span><spanclass="p">)</span> for more info.
Or, check out the <spanclass="p">[</span><spanclass="nv">style guide</span><spanclass="p">](</span><spanclass="sx">style_guide.md</span><spanclass="p">)</span>.
</code></pre></div></div>
<h2id="images">Images</h2>
<p>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
Apple | <spanclass="p">[</span><spanclass="nv">Juicy</span><spanclass="p">](</span><spanclass="sx">https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery</span><spanclass="p">)</span>, Firm, Sweet | Apples keep doctors away.
Banana | <spanclass="p">[</span><spanclass="nv">Convenient</span><spanclass="p">](</span><spanclass="sx">https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery</span><spanclass="p">)</span>, Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
DO NOT DO THIS
</code></pre></div></div>
<p><ahref="#lists">Lists</a> and subheadings usually suffice to present the same information
in a slightly less compact, though much more edit-friendly way:</p>