Pandoc csv2table Filter

A Pandoc filter that replaces CSV content (either inside fenced code blocks or referenced CSV files) with Pandoc Table Markdown.

Installation

You can use this filter in two ways.

1. Install using Cabal: After installing Haskell platform, run:

   cabal install pandoc-csv2table
   

2. Use the single file filter: There is a gist hosting a single file version of this filter here. Clone it and make it an executable script by running:

   chmod +x pandoc-csv2table.hs
   

You can also use this filter in your Pandoc application by calling tablifyCsvlinks.

Usage

Referencing or including CSV

There are three ways to include CSV in your markdown.

1. Referencing CSV file in Image Links:

   ![This text will become the table caption](table.csv)
   

2. Referencing CSV file in Fenced Code Blocks:

   ```{.table caption="This is the **caption**" source="table.csv"}  
   ```
   

   Only code blocks having .table class will be processed.

3. Including CSV content inside Fenced Code Blocks:

   ```{.table aligns="LCR" caption="This is the **caption**" header="yes"}  
   Fruit, Quantity, Price  
   apples, 15, 3.24  
   oranges, 12, 2.22  
   ```
   

   Only code blocks having .table class will be processed.

CSV file or content can contain pandoc markdown. It will be parsed by the Pandoc Markdown Reader before being inserted as a table into the document.

Running the filter

Given the filename test.md, run the filter using command

pandoc --filter pandoc-csv2table -o test.html test.md

or

pandoc -t json test.md | pandoc-csv2table | pandoc -f json -o test.html

Examples

See example.md and the rendered pdf version in the Examples folder for more details on usage.

Options

You can specify a configuration string for image links and attributes for fenced code blocks. There are valid options for specifying

• Type of the table
• Column alignments
• Whether to treat the first line of the CSV file as header or not

Configuration String

It is included right before the closing square bracket without any space in between, as shown in the example below.


mylrcd is the configuration string. This will be rendered as a multiline table with a header with first column left-aligned, second right-aligned, third center-aligned, and the fourth one having default alignment. The config string will be removed from the caption after being processed.

The config string can contain following letters:

• s for simple table
• m for multiline table
• g for grid table
• p for pipe table
• y (from yes) when you want the first row of CSV file to be the header.
• n (from no) when you want to omit the header.
• l for left alignment of the column
• r for right alignment of the column
• c for ccenter alignment of the column
• d for default alignment of the column

You can specify l r c d for each column in a series. The extra letters will be ignored if they exceed the number of columns in the CSV file.

Attributes

You can specify header attributes in fecnced code blocks like this:

```{.table type="pipe" aligns="LCR" caption="A **caption**" header="yes"}  
Fruit, Quantity, Price  
apples, 15, 3.24  
oranges, 12, 2.22  
```

Note: .table must be included if the fenced code block is intended to be processed by this filter.

Valid attributes that you can specify in code blocks include:

• type of the table can be simple, multiline, grid (default), or pipe.
• header can be yes (default) or no
• caption is a string which can contain markdown.
• source is the path to a valid CSV file to be rendered as pandoc table. If present, the contents inside the fenced code blocks are ignored.
• aligns specify alignment for each column. Use L for left, R for right, C for center, and D for default.

License

Copyright © 2015-2023 Wasif Hasan Baig,Venkateswara Rao Mandela

Source code is released under the Terms and Conditions of MIT License.

Please refer to the License file in the project's root directory.