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.
All basic and GitHub Flavored Markdown (GFM) is supported. For more information on these, see:
Contents:
- Document layout
- Trailing whitespace
- Headings
- Text styling
- Lists
- Named anchors
- Code
- Links
- Images
- Videos
- Tables
- Horizontal rule
- Prefer lists to tables
- Samples
In general, most documents benefit from some variation of the following layout:
# Document Title
Short introduction.
[TOC]
## Topic
Content.
## Related information
- Dependencies
- See also
- https://link-to-more-info-
# 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>. -
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. -
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?" -
[TOC]: If you use hosting that supports table of contents, such as Gitiles, put[TOC]after the short introduction. See[TOC]documentation. -
## Topic: The rest of your headings should start from level 2. -
## Related information: Put miscellaneous information at the bottom for the user who wants to know more or didn't find what she needed.
Don't use trailing whitespace, use a trailing backslash.
The CommonMark spec 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.
## Heading 2Headings 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?
Heading - do you remember what level? DO NOT DO THIS.
---------Prefer spacing after # and newlines before and after:
...text before.
# Heading 1
Text after...Lack of spacing makes it a little harder to read in source:
...text before.
#Heading 1
Text after... DO NOT DO THIS.Use sentence-style capitalization. Always capitalize:
- The first word of a heading.
- The word following a colon in a title or heading (for example, "How to: Sort an array").
Use verb form to start headings:
## Use verb formDo not gerund form to start headings:
## Using verb form... DO NOT DO THIS.Headings should be done using atx-style, that is, use 1-6 hash characters (#) at the start of the line to indicate a heading, corresponding to HTML headings levels H1 through H6. Examples of first- and second-level headers are used above.
There must be only one first-level heading (H1) in your topic, which will be displayed as the on-page title.
If your heading finishes with a # character, you need to add an extra # character in the end in order for the title to render correctly. For example, # Async Programming in F# #.
Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title.
Bold Use for UI elements.
Code
Use for inline code, language keywords, package names, command-line commands, database table and column names, and URLs that you don't want to be clickable.
Use for files, folders, paths (for long items, split onto their own line), new terms.
Markdown uses special characters such as *, `, and # for formatting. If you wish to include one of these characters in your content, you must do one of two things:
- Put a backslash before the special character to "escape" it (for example,
\*for a *) - Use the HTML entity code for the character (for example,
*for a *).
- This
- Is
- An
- Ordered
- List
- This
- is
- a
- bulleted
- list
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
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:
- 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:
- 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:
- Foo
- Bar
- Baz.
1. Foo.
2. Bar.To link to a header in the same Markdown file (also known as anchor links), you'll need to find out the id of the header you're trying to link to. To confirm the ID, view the source of the rendered article, find the id of the header (for example, id="blockquote"), and link using # + id (for example, #blockquote).
The id is auto-generated based on the header text. So, for example, given a unique section named ## Step 2, the id would look like this id="step-2".
- For example: Links
To link to a Markdown file in the same repo, use relative links, including the ".md" at the end of the filename.
- For example: Readme file
To link to a header in a Markdown file in the same repo, use relative linking + hashtag linking.
- For example: Sample 1
To link to an external file, use the full URL as the link.
- For example: GitHub
If a URL appears in a Markdown file, it will be transformed into a clickable link.
- For example: http://www.github.com
Explicit anchors can be inserted anywhere in the document using .
Implicit anchors are automatically created for each heading. For example ## Section 1 will have the anchor section-1.
Anchor generation
- spaces are replaced with hyphens (-)
- other characters are replaced with underscores (_)
- runs of hyphens and underscores are collapsed
The recommended approach is to use code blocks with language identifiers as explained in the previous section to ensure the proper syntax highlighting in the documentation site. Use generic code blocks only when necessary.
function fancyAlert(arg) {
if(arg) {
$.docs({div:'#foo'})
}
}
It is best practice to explicitly declare the language, so that neither the syntax highlighter nor the next editor must guess.
Use three backticks (```) + a language ID to apply language-specific color coding to a code block. Here is the list of supported languages showing the markdown label for each language ID.
| Name | Markdown Label |
|---|---|
| C++ | cpp |
| C# | csharp |
| JavaScript | javascript |
| JSON | json |
| NodeJS | nodejs |
| PHP | php |
| Shell | shell, bash |
| Python | python |
| Ruby | ruby |
| SQL / T-SQL | sql |
| XAML | xaml |
| XML | xml |
The following are examples of code blocks using the language IDs for C# (```csharp), Python (```python), and Bash (```bash).
```csharp
using System;
namespace HelloWorld
{
class Hello
{
static void Main()
{
Console.WriteLine("Hello World!");
// Keep the console window open in debug mode.
Console.WriteLine("Press any key to exit.");
Console.ReadKey();
}
}
}
```
```python
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
print "iteration {iteration} is {name}".format(iteration=i, name=name)
```
```bash $ mkdir ~/bin/$ PATH=~/bin:$PATH $ sudo vim /usr/local/bin/git-proxy ```
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:
```shell bazel run :target -- --flag --foo=longlonglonglonglongvalue \ --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue ```
If you need a codeblock within a list, make sure to indent it so as to not break the list:
- 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:
- Bullet.
int foo;
- Next bullet.
Currently, you can embed both YouTube videos with the following syntax:
To get the video's correct URL, right-click on the video, select Copy Embed Code, and copy the URL from the <iframe> element.
[](<youtube_video_link>)For example:
[](https://youtube.com/embed/NdvWwU0gKt8)You can use HTML for videos.
| Tables | Are | Cool |
|---|---|---|
| col 1 is default | left-aligned | $1 |
| col 2 is | centered | $12 |
| col 3 is | right-aligned | $1600 |
You can use a Markdown table generator tool to help creating them more easily.
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.
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 THISLists and subheadings usually suffice to present the same information in a slightly less compact, though much more edit-friendly way:
## Fruits
### Apple
* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet
Apples keep doctors away.
### Banana
* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet
Contrary to popular belief, most apes prefer mangoes.However, there are times when a small table is called for:
Transport | Favored by | Advantages
--- | --- | ---
Swallow | Coconuts | Otherwise unladen
Bicycle | Miss Gulch | Weatherproof
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out