Markdown: document Gitiles flavor
Change-Id: Ifc33c51df6ea145be76a766611daaf254c5528d4
diff --git a/Documentation/markdown.md b/Documentation/markdown.md
new file mode 100644
index 0000000..3a532c2
--- /dev/null
+++ b/Documentation/markdown.md
@@ -0,0 +1,616 @@
+# Markdown
+
+The [Gitiles](https://code.google.com/p/gitiles/) source browser
+automatically renders `*.md` Markdown files into HTML for simplified
+documentation.
+
+[TOC]
+
+## Access controls
+
+Access controls for documentation is identical to source code.
+
+Documentation stored with source files shares the same permissions.
+Documentation stored in a separate Git repository can use different
+access controls. If Gerrit Code Review is being used, branch level
+read permissions can be used to grant or restrict access to any
+documentation branches.
+
+## READMEs
+
+Files named `README.md` are automatically displayed below the file's
+directory listing. For the top level directory this mirrors the
+standard [GitHub](https://github.com/) presentation.
+
+*** promo
+README.md files are meant to provide orientation for developers
+browsing the repository, especially first-time users.
+***
+
+We recommend that Git repositories have an up-to-date top-level
+`README.md` file.
+
+## Markdown syntax
+
+Gitiles supports the core Markdown syntax described in
+[Markdown Basics]. Additional extensions are supported
+to more closely match [GitHub Flavored Markdown] and
+simplify documentation writing.
+
+[Markdown Basics]: http://daringfireball.net/projects/markdown/basics
+[GitHub Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
+
+### Paragraphs
+
+Paragraphs are one or more lines of consecutive text, followed by
+one or more blank lines. Line breaks within a paragraph are ignored
+by the parser, allowing authors to line-wrap text at any comfortable
+column width.
+
+```
+Documentation writing can be fun and profitable
+by helping users to learn and solve problems.
+
+After documentation is written, it needs to be published on the
+web where it can be easily accessed for reading.
+```
+
+### Headings
+
+Headings can be indicated by starting the line with one or more `#`
+marks. The number of `#` used determines the depth of the heading in
+the document outline. Headings 1 through 6 (`######`) are supported.
+
+```
+# A level one (H1) heading
+## A level two (H2) heading
+### A level three (H3) heading
+```
+
+Headings can also use the less popular two line `======` and `------`
+forms to create H1 and H2 level headers:
+
+```
+A first level header
+====================
+
+A second level header
+---------------------
+```
+
+This form is discouraged as maintaining the length of the `===` or
+`---` lines to match the preceding line can be tedious work that is
+unnecessary with the `#` headers.
+
+### Lists
+
+A bullet list:
+
+```
+* Fruit
+ * Orange
+ * Pear
+* Cake
+```
+
+will render into HTML as:
+
+* Fruit
+ * Orange
+ * Pear
+* Cake
+
+The second level items (above Orange, Pear) must be indented with more
+spaces than the item they are nested under. Above 2 spaces were used.
+
+A numbered list:
+
+```
+1. Fruit
+ 1. Orange
+ 2. Pear
+5. Cake
+```
+
+will render into HTML as:
+
+1. Fruit
+ 1. Orange
+ 2. Pear
+5. Cake
+
+List items will be renumbered sequentially by the browser, which is
+why `5` above displays as `2`. Even with this feature it is a good
+idea to maintain list item numbers in the source Markdown to simplify
+reading the source file.
+
+Like bullet lists, numbered lists can be nested by using more leading
+space than the prior list item.
+
+### Tables
+
+Simple tables are supported with column alignment. The first line is
+the header row and subsequent lines are data rows:
+
+```
+| Food | Calories | Tasty? |
+|-------|---------:|:------:|
+| Apple | 95 | Yes |
+| Pear | 102 | Yes |
+| Hay | 977 | |
+[Food and its benefits]
+```
+
+will render as:
+
+| Food | Calories | Tasty? |
+|-------|---------:|:------:|
+| Apple | 95 | Yes |
+| Pear | 102 | Yes |
+| Hay | 977 | |
+[Food and its benefits]
+
+Placing `:` in the separator line indicates how the column should be
+aligned. A colon on the left side is a **left-aligned** column; a
+colon on the right-most side is **right-aligned**; a colon on both
+sides is **center-aligned**.
+
+An optional table title can be placed under the table in brackets
+(`[...]`).
+
+Cells may span multiple columns and include formatting accepted within
+paragraphs such as emphasis, images or links:
+
+| | Grouping ||
+| First Header | Second Header | Third Header |
+| ------------ | :-----------: | -----------: |
+| Content | *Long Cell* ||
+| Content | **Cell 2** | Cell 3 |
+
+the above table was created by:
+
+```
+| | Grouping ||
+| First Header | Second Header | Third Header |
+| ------------ | :-----------: | -----------: |
+| Content | *Long Cell* ||
+| Content | **Cell 2** | Cell 3 |
+```
+
+Empty table cells are indicated by whitespace between the column
+dividers (`| |`) while multiple column cells omit the whitespace.
+
+### Emphasis
+
+Emphasize paragraph text with *italic* and **bold** styles. Either `_`
+or `*` can be used for italic (1 character) and bold text (2
+characters). This allows styles to be mixed within a statement:
+
+```
+Emphasize paragraph text with *italic* and **bold** text.
+
+**It is _strongly_ encouraged to review documentation for typos.**
+```
+
+**It is _strongly_ encouraged to review documentation for typos.**
+
+Emphasis within_words_is_ignored which helps write technical
+documentation. Literal \*bold* can be forced by prefixing the
+opening `*` with \ such as `\*bold*`.
+
+### Strikethrough
+
+Text can be ~~struck out~~ within a paragraph:
+
+```
+Text can be ~~struck out~~ within a paragraph.
+```
+
+Note two tildes are required (`~~`) on either side of the struck out
+section of text.
+
+### Smart quotes
+
+'Single', "double" and <<double angle>> quotes in paragraph text are
+replaced with smart quotes. Apostrophes (this doc's text), ellipses
+("...") and dashes ("--" and "---") are also replaced with HTML
+entities to make the documentation appear typeset.
+
+To force use of the ASCII characters prefix with \, for example `\'`
+for a \' normal single quote.
+
+### Blockquotes
+
+Blockquoted text can be used to stand off text obtained from
+another source:
+
+```
+Sir Winston Churchill once said:
+
+> A lie gets halfway around the world before the truth has a
+> chance to get its pants on.
+```
+
+renders as:
+
+Sir Winston Churchill once said:
+
+> A lie gets halfway around the world before the truth has a
+> chance to get its pants on.
+
+### Code (inline)
+
+Use `backticks` to markup inline code within a paragraph:
+
+```
+Use `backticks` to markup inline code within a paragraph.
+```
+
+### Code (blocks)
+
+Create a fenced code block using three backticks before and after a
+block of code, preceeded and followed by blank lines:
+
+```
+ This is a simple hello world program in C:
+
+ ```
+ #include <stdio.h>
+
+ int main() {
+ printf("Hello, World.\n");
+ return 0;
+ }
+ ```
+
+ To compile it use `gcc hello.c`.
+```
+
+Text within a fenced code block is taken verbatim and is not
+processed for Markdown markup.
+
+### Horizontal rules
+
+A horizontal rule can be inserted using GitHub style `--` surrounded
+by blank lines. Alternatively repeating `-` or `*` and space on a
+line will also create a horizontal rule:
+
+```
+--
+
+- - - -
+
+* * * *
+```
+
+### Links
+
+Wrap text in `[brackets]` and the link destination in parens
+`(http://...)` such as:
+
+```
+Visit [this site](http://example.com/) for more examples.
+```
+
+Links can also use references to obtain URLs from elsewhere in the
+same document. This style can be useful if the same URL needs to be
+mentioned multiple times, is too long to cleanly place within text,
+or the link is within a table cell:
+
+```
+Search for [markdown style][1] examples.
+
+[1]: https://www.google.com/?gws_rd=ssl#q=markdown+style+guide
+```
+
+References can be simplified if the text alone is sufficient:
+
+```
+Visit [Google] to search the web.
+
+[Google]: https://www.google.com/
+```
+
+Automatic hyperlinking can be used where the link text should
+obviously also be the URL:
+
+```
+Use https://www.google.com/ to search the web.
+```
+
+Well formed URLs beginning with `https://`, `http://`, and `mailto:`
+are used as written for the link's destination. Malformed URLs may be
+replaced with `#zSoyz` to prevent browser evaluation of dangerous
+content.
+
+HTML escaping of URL characters such as `&` is handled internally by
+the parser/formatter. Documentation writers should insert the URL
+literally and allow the parser and formatter to make it HTML safe.
+
+Relative links such as `../src/api.md` are resolved relative to the
+current markdown's file path within the Git repository. Absolute
+links such as `/src/api.md` are resolved relative to the top of the
+enclosing Git repository, but within the same branch or Git commit.
+Links may point to any file in the repository. A link to a `*.md`
+file will present the rendered markdown, while a link to a source file
+will display the syntax highlighted source.
+
+### Images
+
+Similar to links but begin with `!` to denote an image reference:
+
+```
+
+```
+
+For images the text in brackets will be included as the alt text for
+screen readers.
+
+Well formed image URLs beginning with `https://` and `http://` will be
+used as written for the `<img src="...">` attribute. Malformed URLs
+will be replaced with a broken `data:` reference to prevent browsers
+from trying to load a bad destination.
+
+Relative and absolute links to image files within the Git repository
+(such as `../images/banner.png`) are resolved during rendering by
+inserting the base64 encoding of the image using a `data:` URI. Only
+PNG (`*.png`), JPEG (`*.jpg` or `*.jpeg`) and GIF (`*.gif`) image
+formats are supported when referenced from the Git repository.
+
+The Gitiles `markdown.imageLimit` configuration variable sets an upper
+byte limit for inserted image files. Unsupported extensions or files
+larger than this threshold (default 256K) will display a broken image.
+
+*** note
+_Inline image caching_
+
+Gitiles allows browsers to locally cache rendered markdown pages.
+Cache invalidation is triggered by the markdown file being modified
+and having a different SHA-1 in Git. Inlined images may need a
+documentation file update to be refreshed when viewed through unstable
+URLs like `/docs/+/master/index.md`.
+***
+
+### HTML
+
+HTML tags are not supported. HTML will be dropped on the floor by the
+parser with no warnings, and no output from that section of the
+document.
+
+There is a small exception for the `<iframe>` element, see
+[HTML IFrame](#HTML-IFrame) below.
+
+## Markdown extensions
+
+Gitiles includes additional extensions to the Markdown language that
+make documentation writing for the web easier without using raw HTML.
+
+### Table of contents
+
+Place `[TOC]` surrounded by blank lines to insert a generated
+table of contents extracted from the H1, H2, and H3 headers
+used within the document:
+
+```
+# Title
+
+[TOC]
+
+## Section 1
+Blah blah...
+
+## Section 2
+Go on...
+```
+
+H1 headers are omitted from the table of contents if there is only one
+level one header present. This allows H1 to be used as the document
+title without creating an unnecessary entry in the table of contents.
+
+Element ids to create anchors are automatically generated by filtering
+the text of the header. For example above `Section 1` will have the
+anchor `#Section-1`. To create an anchor letters and digits are used
+(after removing accents), spaces are replaced with `-`, and other
+characters are replaced with `_`. Changing the title of a section
+will (most likely) change its anchor.
+
+### Notification, aside, promotion blocks
+
+Similar to fenced code blocks these blocks start and end with `***`,
+are surrounded by blank lines, and include the type of block on the
+opening line.
+
+#### Note
+
+```
+*** note
+**Warning:** watch out for nested formatting.
+***
+```
+
+*** note
+**Warning:** watch out for nested formatting.
+***
+
+#### Aside
+
+```
+*** aside
+An aside can stand off less interesting text.
+***
+```
+
+*** aside
+An aside can stand off less interesting text.
+***
+
+#### Promo
+
+```
+*** promo
+Promotions can raise awareness of an important concept.
+***
+```
+
+*** promo
+Promotions can raise awareness of an important concept.
+***
+
+### Column layout
+
+Gitiles markdown includes support for up to 4 columns of text within
+the width of the page.
+
+|||---|||
+#### Columns
+
+can save space.
+
+#### Prettify
+
+the page layout.
+
+*** promo
+#### Can be
+
+trendy.
+***
+|||---|||
+
+A column layout is denoted by a block starting and ending with the
+sequence `|||---|||`. Within the layout a new column is started for
+each header or note/promo/aside block and all text and formatting flow
+into that column until a new column is started.
+
+```
+|||---|||
+#### Columns
+
+can save space.
+
+#### Prettify
+
+the page layout.
+
+*** promo
+#### Can be
+
+trendy.
+***
+|||---|||
+```
+
+### HTML IFrame
+
+Although HTML is stripped the parser has special support for a limited
+subset of `<iframe>` elements:
+
+```
+<iframe src="https://example.com/embed" height="200px" width="400px"></iframe>
+```
+
+The parser allows whitespace including newlines between attributes,
+but strictly limits the supported attribute set to:
+
+src
+: An `https://` or `http://` URL of the page to embed inside of an
+iframe at this position in the document. Malformed URLs will cause
+the iframe to be silently dropped. _(required)_
+
+height
+: CSS pixel height such as `250px` defining the amount of vertical
+space to give to the embedded content. Only `px` units are supported;
+a malformed dimension will drop the iframe. _(required)_
+
+width
+: CSS pixel width such as `250px` or a precentage such as `80%`
+defining the amount of horizontal space to give to the embedded
+content. Only `px` units or `%` are supported; a malformed dimension
+will drop the iframe. _(required)_
+
+frameborder
+: By default a border is drawn around the iframe by the browser. The
+border can be hidden by adding `frameborder="0"` to the iframe tag.
+_(optional)_
+
+Embedded source URLs must also be whitelisted by the Gitiles
+`markdown.allowiframe` configuration variable.
+
+## Site layout
+
+Gitiles includes additional support to create functional documentation
+sites served directly from Git repositories.
+
+### Navigation bar
+
+A top level navigation bar is automatically included on all pages if
+there is a `navbar.md` file present in the top of the repository.
+This file should be a simple bulleted list of links to include in the
+navigation bar.
+
+```
+* [Home](/index.md)
+* [Markdown](/docs/markdown.md)
+* [Configuration](/docs/configuration.md)
+```
+
+Links are resolved relative to the current page, not `navbar.md`.
+Links to other files within the repository should use absolute paths
+to ensure they are resolved correctly from any Markdown file within
+the repository.
+
+### Site title
+
+A site wide banner is displayed on all Markdown pages if `navbar.md`
+includes a H1 header. The text of the header is display on the left
+side of the banner.
+
+```
+# Gitiles
+
+* [Home](/index.md)
+```
+
+### Site logo
+
+An optional logo image is displayed in the banner to the left of the
+site title if a `[logo]` reference exists in `navbar.md`. This image
+should be no taller than 45 px.
+
+```
+# Gitiles
+
+[logo]: /images/site_logo.png
+```
+
+See [images](#Images) above for acceptable URLs and how repository
+relative paths are handled by inline data URIs.
+
+### Home link
+
+Both the site logo (if present) and site title are wrapped in a link
+if the `[home]` reference is declared in `navbar.md`. This is
+typically also used in the outline for the navigation bar:
+
+```
+# Gitiles
+
+* [Home][home]
+* [Markdown](/docs/markdown.md)
+
+[home]: /index.md
+```
+
+### Page title
+
+Titles for pages are extracted from the first H1 heading appearing in
+the document. This is traditionally placed on the first line of the
+markdown file, e.g.:
+
+```
+# Markdown
+```
+
+The title is included in the HTML `<title>` element and also in the
+right side of the banner if `navbar.md` defines a
+[site title](#Site-title).
