Skip to content

Latest commit

 

History

History
473 lines (325 loc) · 13.4 KB

style.md

File metadata and controls

473 lines (325 loc) · 13.4 KB

Markdown style guide

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:

  1. Document layout
  2. Trailing whitespace
  3. Headings
    1. ATX-style headings
    2. Add spacing to headings
  4. Text styling
    1. Special characters
  5. Lists
    1. Ordered lists
    2. Undrdered lists
    3. Nested list spacing
  6. Named anchors
  7. Code
    1. Generic code block
    2. Inline code blocks with language identifier
    3. Escape newlines
    4. Nest codeblocks within lists
  8. Links
    1. Internal Links
    2. External Links
  9. Images
    1. Static image or animated gif
    2. Linked image
  10. Videos
  11. Tables
  12. Horizontal rule
  13. Prefer lists to tables
  14. Samples

Document layout

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
  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>.

  2. 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.

  3. 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?"

  4. [TOC]: If you use hosting that supports table of contents, such as Gitiles, put [TOC] after the short introduction. See [TOC] documentation.

  5. ## Topic: The rest of your headings should start from level 2.

  6. ## Related information: Put miscellaneous information at the bottom for the user who wants to know more or didn't find what she needed.

Trailing whitespace

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.

Headings

ATX-style headings

## 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 H2?

Heading - do you remember what level? DO NOT DO THIS.
---------

Add spacing to headings

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").

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.

Third-level heading

Fourth-level heading

Text styling

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.

Special characters

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, &#42; for a *).

Lists

Ordered lists

  1. This
  2. Is
  3. An
  4. Ordered
  5. List

Unordered lists

  • This
  • is
  • a
  • bulleted
  • list

Nested list spacing

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.

Links

Internal Links

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".

To link to a Markdown file in the same repo, use relative links, including the ".md" at the end of the filename.

To link to a header in a Markdown file in the same repo, use relative linking + hashtag linking.

External Links

To link to an external file, use the full URL as the link.

If a URL appears in a Markdown file, it will be transformed into a clickable link.

Named anchors

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

Code

Generic code block

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'})
    }
}

Inline code blocks with language identifier

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.

Supported Languages

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).

C#

```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

```python
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
    print "iteration {iteration} is {name}".format(iteration=i, name=name)
```

Bash

```bash
$ mkdir ~/bin/$ PATH=~/bin:$PATH
$ sudo vim /usr/local/bin/git-proxy
```

Escape newlines

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
```

Nest codeblocks within lists

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.

Images

Static Image or Animated gif

this is the alt text

Linked Image

alt text for linked image

Videos

Currently, you can embed both YouTube videos with the following syntax:

YouTube

To get the video's correct URL, right-click on the video, select Copy Embed Code, and copy the URL from the <iframe> element.

[![VIDEO](<youtube_video_link>)](<youtube_video_link>)

For example:

[![An Introduction to Tizen .NET](https://youtube.com/embed/NdvWwU0gKt8)](https://youtube.com/embed/NdvWwU0gKt8)

You can use HTML for videos.

Tables

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.

Horizontal rule


Prefer lists to 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.

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

Lists 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

Samples

API Guide Sample