Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/richdom2185/jekyll-fancy-tables
A GitHub Pages-compatible, no-JavaScript fancy tables-generator using extended Markdown syntax.
https://github.com/richdom2185/jekyll-fancy-tables
github-pages jekyll jekyll-plugin markdown
Last synced: 3 months ago
JSON representation
A GitHub Pages-compatible, no-JavaScript fancy tables-generator using extended Markdown syntax.
- Host: GitHub
- URL: https://github.com/richdom2185/jekyll-fancy-tables
- Owner: RichDom2185
- Created: 2022-11-09T23:47:46.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T16:43:40.000Z (4 months ago)
- Last Synced: 2024-10-12T21:16:13.244Z (3 months ago)
- Topics: github-pages, jekyll, jekyll-plugin, markdown
- Language: Liquid
- Homepage: https://richarddominick.me/jekyll-fancy-tables/
- Size: 53.7 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Jekyll Pure Liquid Fancy Tables
> View the demo [here](https://richdom2185.github.io/jekyll-fancy-tables).
GitHub Pages only allows a specific set of [plugins](https://pages.github.com/versions/) to run, hence, additional plugins like [jeffreytse/jekyll-spaceschip](https://github.com/jeffreytse/jekyll-spaceship) cannot work.
Inspired by that plugin, and the approach used in [allejo/jekyll-toc](https://github.com/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:
```html
{% capture content %}{% include fancy-tables.liquid html=content %}{% endcapture %}
{{ content }}
```
**Alternative:** Replace `{{ content }}` directly:
* Before:
```html
{{ content }}
```
* After:
```html
{% include fancy-tables.liquid html=content %}
```
#### As an Include Expression
_See [Advanced Usage: Rendering Individual Tables Only](#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:
```text
| This | table | looks | quite | ugly |
|-----------|-------|-------|-------|---------|
| Sometimes | you | don't | want | headers |
```
After:
```text
|-----------|-------|-------|-------|---------|
| 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
```text
| OMG, I span 3 columns! \ \ |
|------------------------|------|------|
| That's... | very | nice |
```
* Breaks don't have to be aligned to anything
```text
| OMG, I span 3 columns! \\|
|------------|------|------|
| That's... | very | nice |
```
* Non-blank cells will be joined together with a space
```text
| 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 `^^`
```text
|------------------------|---------|
| 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
```text
|---------------|---------|
| 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](https://gist.github.com/RichDom2185/26166ba51cf432b90a0afb04993d0640).
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](#as-a-html-layout), you will have to wrap the include statement in a `div` element to prevent the markdown preprocessor from parsing it again:
```html
{% include fancy-tables.liquid markdown=table %}
```
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](https://github.com/RichDom2185/jekyll-fancy-tables/issues).
### 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](https://github.com/RichDom2185/jekyll-fancy-tables/issues)).
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!](https://github.com/RichDom2185/jekyll-fancy-tables/issues))_