Markdown

There are tons of guides out there already to introduce you to Markdown. Its universal popularity is why we chose it. Here’s just a quick example to give you a flavor of what’s supported:

/// This is a paragraph of regular text. 
/// 
/// This sentence has *two* _emphasized_ words (italics) and **two** 
/// __strong__ ones (bold). 
/// 
/// A blank line creates a separate paragraph. It has some `inline code` 
/// delimited using backticks. 
/// 
/// * Unordered lists. 
/// * Look like ASCII bullet lists. 
/// * You can also use `-` or `+`. 
/// 
/// 1. Numbered lists. 
/// 2. Are, well, numbered. 
/// 1. But the values don't matter. 
/// 
///     * You can nest lists too. 
///     * They must be indented at least 4 spaces. 
///     * (Well, 5 including the space after `///`.) 
/// 
/// Code blocks are fenced in triple backticks: 
/// 
/// ``` 
/// this.code 
///     .will 
///     .retain(its, formatting); 
/// ``` 
/// 
/// The code language (for syntax highlighting) defaults to Dart. You can 
/// specify it by putting the name of the language after the opening backticks: 
/// 
/// ```html 
/// <h1>HTML is magical!</h1> 
/// ``` 
/// 
/// Links can be: 
///
/// * https://www.just-a-bare-url.com 
/// * [with the URL inline](https://google.com) 
/// * [or separated out][ref link] 
/// 
/// [ref link]: https://google.com 
/// 
/// # A Header 
/// 
/// # A subsubheader 
/// 
///  If you need this many levels of headers, you're doing it wrong

PREFER

PREFER backtick fences for code blocks

Markdown has two ways to indicate a block of code: indenting the code four spaces on each line, or surrounding it in a pair of triple-backtick “fence” lines. The former syntax is brittle when used inside things like Markdown lists where indentation is already meaningful or when the code block itself contains indented code.

The backtick syntax avoids those indentation woes, lets you indicate the code’s language, and is consistent with using backticks for inline code.

/// You can use [CodeBlockExample] like this: 
/// 
/// ``` 
/// var example = CodeBlockExample(); 
/// print(example.isItGreat); 
// "Yes." 
/// ```

AVOID

AVOID using markdown excessively

When in doubt, format less. Formatting exists to illuminate your content, not replace it. Words are what matter.

AVOID using HTML for formatting

It may be useful to use it in rare cases for things like tables, but in almost all cases, if it’s too complex to express in Markdown, you’re better off not expressing it.