Jekyll Pure Liquid Fancy Tables

View the demo here.

GitHub Pages only allows a specific set of plugins to run, hence, additional plugins like jeffreytse/jekyll-spaceschip cannot work.

Inspired by that plugin, and the approach used in allejo/jekyll-toc, I wanted to add support for fancy tables in Pure Liquid.

Benefits:

• Fully compatible with GitHub Pages
• Easily customisable to your needs

Add it to your site

Step 1: Copy the required files

Copy the following files to your site's _includes folder:

• fancy-tables.liquid: The main parser to generate the tables
• capturehtml.liquid: Un-escapes HTML special characters, used to parse HTML tags inside pre-formatted code blocks

Step 2: Include it in your site

You can render fancy tables in your Jekyll site using one of two, non-mutually-exclusive ways:

As a HTML layout

Simply include it in any of the layouts you want to add support for:

Recommended: Reassign the layout's content variable. This approach ensures compatibility should you want to include additional features:

{% capture content %}{% include fancy-tables.liquid html=content %}{% endcapture %}
<!-- Some other stuff... -->
{{ content }}

Alternative: Replace {{ content }} directly:

• Before:

  <!-- Some other stuff... -->
  {{ content }}

• After:

  <!-- Some other stuff... -->
  {% include fancy-tables.liquid html=content %}

As an Include Expression

See Advanced Usage: Rendering Individual Tables Only.

Usage

Simply wrap your existing table in a fenced code block with the custom language called table. Example:

```table
| Fruits | Vegetables | Meat    |
|--------|------------|---------|
| Apple  | Potato     | Chicken |
```

This syntax was chosen for a couple reaons:

• Relatively easy parsing
• Prevents most formatters from accidentally breaking the table layout due to the non-standard syntax

Features

Note: For all examples below, where not specified, the markup is wrapped with ```table as per the usage section above.

1. Headerless Tables

Simply chop off the header line:

Before:

| This      | table | looks | quite | ugly    |
|-----------|-------|-------|-------|---------|
| Sometimes | you   | don't | want  | headers |

After:

|-----------|-------|-------|-------|---------|
| Sometimes | you   | don't | want  | headers |

Result:

Sometimes

you

don’t

want

headers

2. Column Span and Row Span

Column Span

• Works in table headers and table body

• Simply "break" the column separator to span multiple columns

  | OMG, I span 3 columns! \      \      |
  |------------------------|------|------|
  | That's...              | very | nice |
  

• Breaks don't have to be aligned to anything

  | OMG, I span 3 columns! \\|
  |------------|------|------|
  | That's...  | very | nice |
  

• Non-blank cells will be joined together with a space

  | OMG, I    \ span \ 3 columns! |
  |-----------|------|------------|
  | That's... | very | nice       |
  

The above 3 examples give the same result:

OMG, I span 3 columns!
That’s…	very	nice

Row Span

• Only works for the table body

• Simply prepend table cells with ^^

  |------------------------|---------|
  | Look, I span two rows! | Looks   |
  | ^^                     | pretty! |
  

  Result:

  Look, I span two rows!	Looks
  	pretty!

• Non-blank cells will be joined together with a line break

  |---------------|---------|
  | Look, I span  | Looks   |
  | ^^ two rows!  | pretty! |
  

  Result:

  Look, I span two rows!	Looks
  	pretty!

3. Individual Cell Alignment

• Simply add a section under ```alignment before closing the code block with ```. Specify left, right, or center-aligned using L, R, or C respectively

  ```table
  | _For padding_ | _For padding_ | _For padding_ |
  |---------------|---------------|---------------|
  | left          |    center     |         right |
  |    center     |         right | left          |
  |         right | left          |    center     |
  ```alignment
  CCC
  LCR
  CRL
  RLC
  ```
  

• Whitespace and capitalization do not matter

  ```table
  | _For padding_ | _For padding_ | _For padding_ |
  |---------------|---------------|---------------|
  | left          |    center     |         right |
  |    center     |         right | left          |
  |         right | left          |    center     |
  ```alignment
  cCClCrCrlrLc
  ```
  

The above 2 examples give the same result:

For padding	For padding	For padding
left	center	right
center	right	left
right	left	center

Advanced Usage

Rendering Individual Tables Only

Why would you use this?

This can be useful together with some creative tricks like using text substitution for lists in markdown tables.

If you only want to render certain tables, the extension also supports rendering directly from markdown. Simply include the following markup in your source file:

{% capture table %}
```table
| The Do-Re-Mi Song              \\|
|-----|---------------------|------|
| Doe | A deer, a female... | Deer |
```alignment
c
```
{% endcapture %}

{% include fancy-tables.liquid markdown=table %}

Note the use of the markdown argument instead of html.

Result:

The Do-Re-Mi Song
Doe	A deer, a female…	Deer

If used together with the HTML layout, you will have to wrap the include statement in a div element to prevent the markdown preprocessor from parsing it again:

<div markdown="0">{% include fancy-tables.liquid markdown=table %}</div>

Note: depending on your Jekyll site configuration, the markdown="0" attribute may or may not be needed.

Others

Bugs

Feel free to report any bugs in the issue tracker.

Additional styling

Keeping to the spirit of Markdown, in order to not make the syntax too complicated, style-related syntax is limited to table cell alignment only (but you are welcome to request for features in the issue tracker).

Having said that, the file also provides a data-nth-cell HTML attribute for each table cell (1-indexed), so you can style each individual cell using CSS/JS that way.

Planned additions

• Default column alignment
• Individual cell alignment: ignore all characters, not just whitespace
• ??? (suggest a feature here!)