tiennm99/styleguide
1
0 Fork 0
mirror of https://github.com/tiennm99/styleguide.git synced 2026-10-14 02:16:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

mdstyle: pull in updates from internal styleguide

Browse Source
This commit is contained in:
Mike Frysinger committed 2024-07-02 01:07:19 -04:00
1 parent 6acd1e5afd
commit 1ae7350b45
1 file changed
+496 -110
Download Patch File Download Diff File Expand all files Collapse all files
docguide/style.md
+496 -110
View File
@@ -1,42 +1,74 @@
# Markdown style guide
Much of what makes Markdown great is the ability to write plain text, and get
Much of what makes Markdown refreshing 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.*
1. *Source text is readable and portable.*
2. *The Markdown corpus is maintainable over time and across teams.*
3. *The syntax is simple and easy to remember.*
Contents:
1. [Capitalization](#capitalization)
1. [Document layout](#document-layout)
1. [Table of contents](#table-of-contents)
1. [Character line limit](#character-line-limit)
1. [Trailing whitespace](#trailing-whitespace)
1. [Headings](#headings)
1. [ATX-style headings](#atx-style-headings)
1. [Use unique, complete names for headings](#use-unique-complete-names-for-headings)
1. [Add spacing to headings](#add-spacing-to-headings)
1. [Use a single H1 heading](#use-a-single-h1-heading)
1. [Capitalization of titles and headers](#capitalization-of-titles-and-headers)
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. [Use code span for escaping](#use-code-span-for-escaping)
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. [Declare the language](#declare-the-language)
1. [Escape newlines](#escape-newlines)
1. [Use fenced code blocks instead of indented code blocks](#use-fenced-code-blocks-instead-of-indented-code-blocks)
1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
1. [Links](#links)
1. [Use explicit paths for links within Markdown](#use-explicit-paths-for-links-within-markdown)
1. [Avoid relative paths unless within the same directory](#avoid-relative-paths-unless-within-the-same-directory)
1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
1. [Reference links](#reference-links)
1. [Use reference links for long links](#use-reference-links-for-long-links)
1. [Use reference links to reduce duplication](#use-reference-links-to-reduce-duplication)
1. [Define reference links after their first use](#define-reference-links-after-their-first-use)
1. [Images](#images)
1. [Prefer lists to tables](#prefer-lists-to-tables)
1. [Tables](#tables)
1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
## Capitalization
Use the original names of products, tools and binaries, preserving the
capitalization. E.g.:
```markdown
# Markdown style guide
`Markdown` is a dead-simple platform for internal engineering documentation.
```
and not
```markdown
# markdown bad style guide example
`markdown` is a dead-simple platform for internal engineering documentation.
```
## Document layout
In general, most documents benefit from some variation of the following layout:
In general, documents benefit from some variation of the following layout:
```markdown
# Document Title
@@ -54,73 +86,149 @@ Content.
* 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. `# Document title`: The first heading should be a level-one heading, ideally
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. `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 doesn't know the most basic information 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).
put `[TOC]` after the short introduction. See [`[TOC]` documentation][TOC-docs].
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.
to know more or didn't find what they needed.
[TOC-docs]: https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.md#Table-of-contents
## Table of contents
### Use a `[TOC]` directive
Use a [`[TOC]` directive][TOC-docs] unless all
of your content is above the fold[^above] on a laptop.
[^above]: Content is "above the fold" if it is visible when the page is first
displayed. Content is "below the fold" if it is hidden until the user
scrolls down the page on a computer or literally unfolds a document
such as a newspaper.
### Place the `[TOC]` directive after the introduction
Place the `[TOC]` directive after your page's introduction and before the first
H2 heading. For example:
```markdown
# My Page
This is my introduction **before** the TOC.
[TOC]
## My first H2
```
```markdown
# My Page
[TOC]
This is my introduction **after** the TOC where it should not be.
## My first H2
```
For 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 and
to the right of the page. However, `[TOC]` placement matters a lot when screen
readers or keyboard controls are involved.
That's because `[TOC]` inserts the HTML for the table of contents into the DOM
wherever 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't
read it until they get to the end of the document.
## Character line limit
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:
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 the
more our documents are formatted according to similar rules, the better
these tools will work. For example, Code Search doesn't soft wrap.
* **Quality**. The more engineers use their well-worn coding habits when
creating and editing Markdown content, the better the quality. Markdown takes
advantage of the excellent review culture we already have.
### Exceptions
Exceptions to the 80-character rule include:
* Links
* Tables
* Headings
* Code blocks
This means that lines with links are allowed to extend past column 80, along
with any relevant punctuation:
```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).
* See the
[foo docs](https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.md).
and find the logfile.
```
Often, inserting a newline before a long link preserves readability while
minimizing the overflow:
However, note that text before and after the link gets wrapped.
Tables may also run long. However, there are
[best practices for creating short, readable tables](#tables).
```markdown
Lorem ipsum dolor sit amet. See the
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
for details.
Foo | Bar | Baz
----------------------------------------------------------------------------- | --- | ---
Somehow-unavoidable-long-cell-filled-with-content-that-simply-refuses-to-wrap | Foo | Bar
```
## Trailing whitespace
Don't use trailing whitespace, use a trailing backslash.
Don't use trailing whitespace. Use a trailing backslash to break lines.
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.
that two spaces at the end of a line should insert a `<br />` tag. However, many
directories have a presubmit check for trailing whitespace, 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.
Use a trailing backslash, sparingly:
```markdown
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 newlines
will create a paragraph tag; get used to that.
## Headings
### ATX-style headings
```markdown
# 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
with the rest of the heading syntax. An editor has to ask: Does `---` mean H1 or
H2?
```markdown
@@ -128,6 +236,34 @@ Heading - do you remember what level? DO NOT DO THIS.
---------
```
### 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:
```markdown
## Foo
### Summary
### Example
## Bar
### Summary
### Example
```
prefer:
```markdown
## Foo
### Foo summary
### Foo example
## Bar
### Bar summary
### Bar example
```
### Add spacing to headings
Prefer spacing after `#` and newlines before and after:
@@ -135,7 +271,7 @@ Prefer spacing after `#` and newlines before and after:
```markdown
...text before.
# Heading 1
## Heading 2
Text after...
```
@@ -145,10 +281,22 @@ Lack of spacing makes it a little harder to read in source:
```markdown
...text before.
#Heading 1
##Heading 2
Text after... DO NOT DO THIS.
```
### Use a single H1 heading
Use one H1 heading as the title of your document. Subsequent headings should be
H2 or deeper. See [Document layout](#document-layout) for more information.
### Capitalization of titles and headers
Follow the guidance for
[capitalization](https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings)
in the
[Google Developer Documentation Style Guide](https://developers.google.com/style/).
## Lists
### Use lazy numbering for long lists
@@ -176,19 +324,19 @@ numbered lists, because it's nicer to read in source:
### Nested list spacing
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
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.
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.
* 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.
* 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:
@@ -204,11 +352,11 @@ for wrapped text:
```markdown
* Foo,
wrapped.
wrapped with a 4-space indent.
1. 2 spaces
and 4 space indenting.
2. 2 spaces again.
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 can
@@ -227,8 +375,8 @@ suffice for both kinds of lists:
### Inline
&#96;Backticks&#96; designate `inline code`, and will render all wrapped content
literally. Use them for short code quotations and field names:
&#96;Backticks&#96; designate `inline code` that will be rendered literally. Use
them for short code quotations, field names, and more:
```markdown
You'll want to run `really_cool_script.sh arg`.
@@ -236,20 +384,27 @@ 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:
Use inline code when referring to file types in a generic sense, rather than a
specific existing 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.
### 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:
```markdown
An example Markdown shortlink would be: `Markdown/foo/Markdown/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 codeblock:
For code quotations longer than a single line, use a fenced code block:
<pre>
```python
@@ -263,11 +418,18 @@ def Foo(self, bar):
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
#### Use fenced code blocks instead of indented code blocks
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:
Four-space indenting is also interpreted as a code block. However, we strongly
recommend fencing for all code blocks.
Indented code blocks can sometimes look cleaner in the source, but they have
several drawbacks:
* You cannot specify the language. Some Markdown features are tied to language
specifiers.
* The beginning and end of the code block are ambiguous.
* Indented code blocks are harder to search for in Code Search.
```markdown
You'll need to run:
@@ -285,21 +447,21 @@ And again:
#### Escape newlines
Because most commandline snippets are intended to be copied and pasted directly
Because most command-line 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
$ blaze 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:
If you need a code block within a list, make sure to indent it so as to not
break the list:
```markdown
* Bullet.
@@ -327,94 +489,318 @@ additional spaces from the list indentation:
Long links make source Markdown difficult to read and break the 80 character
wrapping. **Wherever possible, shorten your links**.
### Use informative Markdown link titles
### Use explicit paths for links within Markdown
Markdown link syntax allows you to set a link title, just as HTML does. Use it
wisely.
Use the explicit path for Markdown links. For example:
Titling your links as "link" or "here" tells the reader precisely nothing when
quickly scanning your doc and is a waste of space:
```markdown
[...](/path/to/other/markdown/page.md)
```
You don't need to use the entire qualified URL:
```markdown
[...](https://bad-full-url.example.com/path/to/other/markdown/page.md)
```
### Avoid relative paths unless within the same directory
Relative paths are fairly safe within the same directory. For example:
```markdown
[...](other-page-in-same-dir.md)
[...](/path/to/another/dir/other-page.md)
```
Avoid relative links if you need to specify other directories with `../`:
```markdown
[...](../../bad/path/to/another/dir/other-page.md)
```
### 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:
```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.
See the Markdown guide for more info: [link](markdown.md), or check out the
style guide [here](style.md).
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 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).
See the [Markdown guide](markdown.md) for more info, or check out the
[style guide](style.md).
Check out a
[typical test result](https://example.com/foo/bar).
```
### Reference
For long links or image URLs, you may want to split the link use from the link
definition, like this:
<!-- Known bug: We use a zero-width non-breaking space (U+FEFF) here to prevent -->
<!-- reference links from rendering within code blocks. -->
```markdown
See the [Markdown style guide][style], which has suggestions for making docs more
readable.
[style]: http://Markdown/corp/Markdown/docs/reference/style.md
```
#### Use reference links for long links
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:
```markdown
DO NOT DO THIS.
The [style guide][style_guide] says not to use reference links unless you have
to.
[style_guide]: https://google.com/Markdown-style
```
Just inline it instead:
```markdown
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 use
a reference link:
```markdown
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:
```markdown
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:
```markdown
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
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
We recommend putting reference link definitions just before the next heading, at
the end of the section in which they're first used. If your editor has its own
opinion 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 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 at 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:
```markdown
# Header FOR A BAD DOCUMENT
Some text with a [link][link_def].
Some more text with the same [link][link_def].
## Header 2
... lots of text ...
## Header 3
Some more text using a [different_link][different_link_def].
[link_def]: http://reallyreallyreallylonglink.com
[different_link_def]: http://differentreallyreallylonglink.com
```
Instead, put it just before the header following its first use:
```markdown
# Header
Some 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 3
Some more text using a [different_link][different_link_def].
[different_link_def]: http://differentreallyreallylonglink.com
```
## Images
See [image syntax](https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.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).
* Use images when it's easier to *show* a reader something than to *describe
it*. For example, explaining how to navigate a UI is often easier with an
image than text.
* Make sure to provide appropriate text to describe your image. Readers who
are not sighted cannot see your image and still need to understand the
content! See the alt text best practices below.
## Prefer lists to tables
## 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**.
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:
```markdown
Fruit | Attribute | Notes
--- | --- | --- | ---
Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
DO NOT DO THIS
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.
```
[Lists](#lists) and subheadings usually suffice to present the same information
in a slightly less compact, though much more edit-friendly way:
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](#lists) and subheadings sometimes suffice to present the same
information. Let's see this data in list form:
```markdown
## Fruits
Both types are highly popular, sweet, and grow on trees.
### Apple
* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
Apples keep doctors away.
### Banana
* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet
* [Convenient](http://cs/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* 16 degrees average acute curvature.
Contrary to popular belief, most apes prefer mangoes.
Contrary to popular belief, most apes prefer mangoes. Don't you?
See the [design doc][banana_v2] for the newest hotness in bananiels.
```
However, there are times when a small table is called for:
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:
```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
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://google3/airspeed.h
[tornado_proofing]: http://google3/kansas/
[tosche_station]: http://google3/power_converter.h
```
Note that [reference links](#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, reconsider whether you really
need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
all needs already.
need it. Except for [big tables](#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
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. See
[Philosophy](philosophy.md).
Gitiles does not render HTML.