Markdown: update documentation to cover features
Change-Id: I7540142b62bfd683cbac0d9f5b59fc9fd4db382a
diff --git a/Documentation/markdown.md b/Documentation/markdown.md
index 2dfa85f..fdc3031 100644
--- a/Documentation/markdown.md
+++ b/Documentation/markdown.md
@@ -254,7 +254,7 @@
```
This is a simple hello world program in C:
- ```
+ ```c
#include <stdio.h>
int main() {
@@ -269,6 +269,59 @@
Text within a fenced code block is taken verbatim and is not
processed for Markdown markup.
+Syntax highlighting can optionally be enabled for common languages
+by adding the language name in lowercase on the opening line.
+Supported languages include:
+
+|||---||| 2,2,2,2,4
+
+#### Scripting
+* bash, sh
+* lua
+* perl
+* python, py
+* ruby
+* tcl
+
+### Web
+* css
+* dart
+* html
+* javascript, js
+* json
+
+#### Compiled
+* basic, vb
+* c
+* cpp (C++)
+* go
+* java
+* pascal
+* scala
+
+#### Markup
+* tex, latex
+* wiki
+* xml
+* xquery
+* xsl
+* yaml
+
+#### Other
+* clj (Clojure)
+* erlang
+* hs (Haskell)
+* lisp
+* [llvm](http://llvm.org/docs/LangRef.html)
+* matlab
+* ml (OCaml, SML, F#)
+* r
+* [rd](http://cran.r-project.org/doc/manuals/R-exts.html)
+* rust
+* sql
+* vhdl
+|||---|||
+
### Horizontal rules
A horizontal rule can be inserted using GitHub style `--` surrounded
@@ -337,10 +390,40 @@
### Named anchors
-Explicit anchors may be inserted into a document to make stable references.
-This is recommended at the end of a section header to avoid ambigous names.
-The following are identical and will wrap the section header inside of an
-anchor tag:
+Explicit anchors can be inserted anywhere in the document using
+`<a name="tag"></a>` or `{#tag}`.
+
+Implicit anchors are automatically created for each
+[heading](#Headings). For example `## Section 1` will have
+the anchor `Section-1`.
+
+*** note
+*Anchor generation*
+
+* letters and digits, after removing accents (á → a)
+* spaces are replaced with -
+* other characters are replaced with _
+* runs of - and _ are collapsed
+***
+
+If a document contains the same named subsection under different
+parents the parent anchor will prefix the subsections to
+disambiguate. For example the following document will have anchors
+`Running-Format` and `Coding-Format` and `Libraries` as that subsection
+is unique:
+
+```
+## Running
+### Format
+## Coding
+### Format
+### Libraries
+```
+
+When placed in a section header the explicit anchor will override
+the automatic anchor. The following are identical and associate
+the anchor `live-examples` with the section header instead of the
+automaticly generated name `Examples`.
```
## Examples {#live-examples}
@@ -369,9 +452,8 @@
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.
+Unsupported extensions or files larger than [image size](#Image-size)
+limit (default 256K) will display a broken image.
*** note
_Inline image caching_
@@ -419,12 +501,8 @@
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.
+Anchors are automatically extracted from the headers, see
+[named anchors](#Named-anchors).
### Notification, aside, promotion blocks
@@ -528,14 +606,14 @@
```
|||---||| :6,3
-# Right
+#### Right
|||---|||
```
renders as:
|||---||| :6,3
-# Right
+#### Right
|||---|||
### HTML IFrame
@@ -652,3 +730,49 @@
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).
+
+## Configuration
+
+The `gitiles.config` file supporting the site contains several
+configuration options that impact markdown rendering.
+
+### Disabling markdown
+
+Markdown can be completely disabled by setting render to false.
+
+```
+[markdown]
+ render = false
+```
+
+### Markdown size
+
+Markdown files are limited by default to 5 MiB of input text
+per file. This limit is configurable, but should not be raised
+beyond available memory.
+
+```
+[markdown]
+ inputLimit = 5M
+```
+
+### Image size
+
+Referenced [images are inlined](#Images) as base64 encoded URIs.
+The image limit places an upper bound on the byte size of input.
+
+```
+[markdown]
+ imageLimit = 256K
+```
+
+### Google Analytics
+
+[Google Analytics](https://www.google.com/analytics/) can be
+enabled on every rendered markdown page by adding the Property ID
+to the configuration file:
+
+```
+[google]
+ analyticsId = UA-XXXX-Y
+```
