Note: You can’t use block level tags (paragraphs or lists) inside Markdown tables, so if you need separate paragraphs inside a cell, use <br/><br/>.

HTML Tables

If you need a more sophisticated table syntax, use HTML syntax for the table. Although you’re using HTML, you can use Markdown inside the table cells by adding markdown="span" as an attribute for the td tag, as shown in the following table. You can also control the column widths.

<table><colgroup><colwidth="30%"/><colwidth="70%"/></colgroup><thead><trclass="header"><th>Field</th><th>Description</th></tr></thead><tbody><tr><tdmarkdown="span">First column **fields**</td><tdmarkdown="span">Some descriptive text. This is a markdown link to [Google](http://google.com). Or see [some link][mydoc_tags].</td></tr><tr><tdmarkdown="span">Second column **fields**</td><tdmarkdown="span">Some more descriptive text.
</td></tr></tbody></table>

Result:

Field

Description

First column fields

Some descriptive text. This is a markdown link to Google. Or see some link.

Second column fields

Some more descriptive text.

jQuery DataTables

You also have the option of using a jQuery DataTable, which gives you some additional capabilities. To use a jQuery DataTable in a page, include datatable: true in a page’s frontmatter. This tells the default layout to load the necessary CSS and javascript bits and to include a $(document).ready() function that initializes the DataTables library.

You can change the options used to initialize the DataTables library by editing the call to $('table.display').DataTable() in the default layout. The available options for Datatables are described in the DataTable documentation, which is excellent.

You also must add a class of display to your tables. You can change the class, but then you’ll need to change the trigger defined in the $(document).ready() function in the default layout from table.display to the class you prefer.

You can also add page-specific triggers (by copying the <script></script> block from the default layout into the page) and classes, which lets you use different options on different tables.

If you use an HTML table, adding class="display" to the <table> tag is sufficient.

Markdown, however, doesn’t allow you to add classes to tables, so you’ll need to use a trick: add <div class="datatable-begin"></div> before the table and <div class="datatable-end"></div> after the table. The default layout includes a jQuery snippet that automagically adds the display class to any table it finds between those two markers. So you can start with this (we’ve trimmed the descriptions for display):