8. DataTables Markdown

Markdown is a plain text formatting syntax, initially created by John Gruber and now widely used on the web. It is designed to provide an easy to use set of formatting rules which can be applied to a document, converting it from an easily readable and editable plain text format to HTML.

The DataTables project uses an extended form of Markdown in an number of areas:

Forum posts
Web-site page comments
DataTables reference source

Syntax

DataTables Markdown follows the same rules as GitHub Flavoured Markdown with a couple of extensions (see below). The most common Markdown rules used by DataTables are documented below, but for full documentation of the syntax supported in Markdown, please refer to:

Extensions

If you know Markdown already, you will be interested in the extensions DataTables makes use of. These are primarily to add the ability to easily link to different DataTables reference documentation, or highlight different types of inline code:

Markdown syntax	Action	Example Markdown	Example rendered
`-api x`	Link to the reference documentation for API method x	`-api row().data()`	`row().data()`
`-button x`	Link to the reference documentation for button x	`-button pdf`	`pdf`
`-event x`	Link to the reference documentation for event x	`-event draw`	`draw`
`-init x`	Link to the reference documentation for initialisation option x	`-init scrollY`	`scrollY`
`-type x`	Link to the reference documentation for data type x	`-type row-selector`	`row-selector`
`-tag x`	Highlight code as an HTML tag	`-tag tbody`	`tbody`
`-path x`	Highlight code as a file path	`-path /home/datatables`	`/home/datatables`
`-string x`	Highlight code as a string literal	`-string full_numbers`	`full_numbers`

The `-api x`, `-event x`, `-init x` and `-button x` code links can optionally be prefixed with an e to indicate that it is an Editor API, event, option or button that is being documented (Editor has its own documentation).

Common rules

For the most part Markdown is transparent. Simply type a comment / post as you normally would and Markdown will format it as HTML. Having said that, there are some common rules that you might want to use when writing a comment / post.

Links

Links can be created automatically by simply typing a web address that starts with http:// or https:// and DataTables Markdown will automatically convert it to be an HTML link. The other method is to explicitly create a link using the syntax [text](address). For example:

Markdown example:

[DataTables](http://datatables.net)
[DataTables on GitHub](https://github.com/DataTables/)

Rendered example:

DataTables
DataTables on GitHub

Italics / Bold

Markdown uses the * and _ characters interchangeably for italic and bold text (although the closing character(s) must match the opening character(s)!). A word or phrase enclosed by a single * or _ is shown as italic text. A word or phrase enclosed by a double ** or __ is shown as bold text.

Markdown example:

This is *italic text* as _is this_. Meanwhile, this is **bold text**, as __is this__.

Rendered example:

This is italic text as is this. Meanwhile, this is bold text, as is this.

Quotes

Quotes in Markdown operate similar to the quotes that we are all familiar with in e-mails - that is to say, each line that is quoted is preceded by a > character and a space. Blocks of text can be quoted by prefixing each line in the block with a > character - Markdown will automatically combine them into a single block quote.

Markdown example:

> Quoted text

Rendered example:

Quoted text

Lists

A unordered list is created by prefixing a line with a star and space (*). An ordered list is created by prefixing a line with a number, period and space (1.):

Markdown example:

* List item
* Another list item

1. Ordered list
1. Second item

Rendered example:

List item
Another list item

Ordered list
Second item

Code

There are two styles of showing code available in DataTables Markdown:

Inline code
Code blocks

Inline code

Inline code highlighting is useful when referring to variable names and the like in a sentence. The code is indicated using the ` symbol. Remember also that in DataTables Markdown you can use `-* _x_` to indicate that an initialisation option, API method, event or type is to be shown as inline code with a link to the reference documentation (see above).

Markdown example:

When using `-init scrollX` set its value to be `true`.

Rendered example:

When using scrollX set its value to be true.

Code blocks with syntax highlighting

The second type of code display DataTables Markdown uses matches GitHub Flavoured Markdown to display larger sections of code. This is done with three ` characters followed optionally by a language identifier for the syntax highlighting language (js, html, xml, css or php) and then a newline. The block is terminated by a line with three more ` characters.

Markdown example:

  ```js
  $(document).ready( function () {
    var table = $('#myTable').DataTable();
    // ...
  } );
  ```

Rendered example:

$(document).ready( function () {
  var table = $('#myTable').DataTable();
  // ...
} );