July 1, 2020
+
Warning: panflute and pantable only support pandoc < 2.10 and is so far incompatible with pandoc 2.10+. This is because there’s a new AST change related to table spans. See https://github.com/jgm/pandoc/issues/1024, https://github.com/sergiocorreia/panflute/issues/142. Until that is resolved, please stick with 2.9.2.1 or below when used together with pantable.
+The pantable package comes with 2 pandoc filters, pantable.py and pantable2csv.py. pantable is the main filter, introducing a syntax to include CSV table in markdown source. pantable2csv complements pantable, is the inverse of pantable, which convert native pandoc tables into the CSV table format defined by pantable.
Some example uses are:
+You already have tables in CSV format.
You feel that directly editing markdown table is troublesome. You want a spreadsheet interface to edit, but want to convert it to native pandoc table for higher readability. And this process might go back and forth.
You want lower-level control on the table and column widths.
You want to use all table features supported by the pandoc’s internal AST table format, which is not possible in markdown for pandoc <= 1.18.1
pantableThis allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.
+Also see the README in GitHub Pages. There’s a LaTeX output too.
+```table
+---
+caption: '*Awesome* **Markdown** Table'
+alignment: RC
+table-width: 2/3
+markdown: True
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+- following standard markdown syntax
+- like this"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```becomes
+First row |
+defaulted to be header row |
+can be disabled |
+
|---|---|---|
1 |
+cell can contain markdown |
+It can be aribrary block element: +
|
+
2 |
+Any markdown syntax, e.g. |
+
|
+
(The equation might not work if you view this on PyPI.)
+Install:
+ +Use:
+ +Fenced code blocks is used, with a class table. See Example.
Optionally, YAML metadata block can be used within the fenced code block, following standard pandoc YAML metadata block syntax. 7 metadata keys are recognized:
+captionthe caption of the table. If omitted, no caption will be inserted. Default: disabled.
+alignmenta string of characters among L,R,C,D, case-insensitive, corresponds to Left-aligned, Right-aligned, Center-aligned, Default-aligned respectively. e.g. LCRD for a table with 4 columns. Default: DDD...
widtha list of relative width corresponding to the width of each columns. e.g.
+ +Default: auto calculated from the length of each line in table cells.
+table-widththe relative width of the table (e.g. relative to \linewidth). default: 1.0
headermarkdownincludeinclude-encodinginclude will be decoded according to this encoding, else assumed to be UTF-8.
+csv-kwargsIf specified, should be a dictionary passed to csv.reader as options. e.g.
pipe_tablesIf True, a pipe table will be constructed directly in markdown syntax instead of via AST. markdown is implied to be True. header will be overridden as true because pipe_tables must has header in pandoc.
This trades correctness for speed. It won’t be correct if any of the cell is multiline for example, resulting in an invalid pipe table. However, it is much faster comparing to previous markdown: True case because previously per cell a subprocess to execute pandoc the parse the markdown to AST is needed.
grid_tablesIf True, a grid table will be constructed directly in markdown syntax instead of via AST. markdown is implied to be True. header can be used together with this.
This trades correctness for speed. This should be more robust than pipe_tables since the grid_tables syntax supports everything the pandoc AST supports. This however depends on an external dependency. Install it by either pip install terminaltables or conda install terminaltables.
raw_markdownIf True, force output the table as a pipe table (which is tab-delimited.) This is sometimes useful if pandoc is very stubborn to not emit a pipe table even if markdown-grid_tables... is used. Note that this should only be used if the output format is markdown.
When the metadata keys is invalid, the default will be used instead. Note that width and table-width accept fractions as well.
+pantable2csvThis one is the inverse of pantable, a panflute filter to convert any native pandoc tables into the CSV table format used by pantable.
Effectively, pantable forms a “CSV Reader”, and pantable2csv forms a “CSV Writer”. It allows you to convert back and forth between these 2 formats.
For example, in the markdown source:
++--------+---------------------+--------------------------+
+| First | defaulted to be | can be disabled |
+| row | header row | |
++========+=====================+==========================+
+| 1 | cell can contain | It can be aribrary block |
+| | **markdown** | element: |
+| | | |
+| | | - following standard |
+| | | markdown syntax |
+| | | - like this |
++--------+---------------------+--------------------------+
+| 2 | Any markdown | $$E = mc^2$$ |
+| | syntax, e.g. | |
++--------+---------------------+--------------------------+
+
+: *Awesome* **Markdown** Tablerunning pandoc -F pantable2csv -o output.md input.md, it becomes
``` {.table}
+---
+alignment: DDD
+caption: '*Awesome* **Markdown** Table'
+header: true
+markdown: true
+table-width: 0.8055555555555556
+width: [0.125, 0.3055555555555556, 0.375]
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+- following standard markdown syntax
+- like this
+"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.
+| + | pandoc-csv2table | +pandoc-placetable | +panflute example | +pantable | +
|---|---|---|---|---|
| caption | +caption | +caption | +title | +caption | +
| aligns | +aligns = LRCD | +aligns = LRCD | ++ | aligns = LRCD | +
| width | ++ | widths = "0.5 0.2 0.3" | ++ | width: [0.5, 0.2, 0.3] | +
| table-width | ++ | + | + | table-width: 1.0 | +
| header | +header = yes | no | +header = yes | no | +has_header: True | False | +header: True | False | yes | NO | +
| markdown | ++ | inlinemarkdown | ++ | markdown: True | False | yes | NO | +
| source | +source | +file | +source | +include | +
| others | +type = simple | multiline | grid | pipe | ++ | + | + |
| + | + | delimiter | ++ | + |
| + | + | quotechar | ++ | + |
| + | + | id (wrapped by div) | ++ | + |
| Notes | ++ | + | + | width are auto-calculated when width is not specified | +
In pandoc 1.19, grid-tables is improved to support all features available to the AST too.↩︎
November 9, 2020
+
Warning: panflute and pantable only support pandoc < 2.10 and is so far incompatible with pandoc 2.10+. This is because there’s a new AST change related to table spans. See https://github.com/jgm/pandoc/issues/1024, https://github.com/sergiocorreia/panflute/issues/142. Until that is resolved, please stick with 2.9.2.1 or below when used together with pantable.
+The pantable package comes with 2 pandoc filters, pantable.py and pantable2csv.py. pantable is the main filter, introducing a syntax to include CSV table in markdown source. pantable2csv complements pantable, is the inverse of pantable, which convert native pandoc tables into the CSV table format defined by pantable.
Some example uses are:
+You already have tables in CSV format.
You feel that directly editing markdown table is troublesome. You want a spreadsheet interface to edit, but want to convert it to native pandoc table for higher readability. And this process might go back and forth.
You want lower-level control on the table and column widths.
You want to use all table features supported by the pandoc’s internal AST table format, which is not possible in markdown for pandoc <= 1.18.1
pantableThis allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.
+Also see the README in GitHub Pages. There’s a LaTeX output too.
+```table
+---
+caption: '*Awesome* **Markdown** Table'
+alignment: RC
+table-width: 2/3
+markdown: True
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+- following standard markdown syntax
+- like this"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```becomes
+First row |
+defaulted to be header row |
+can be disabled |
+
|---|---|---|
1 |
+cell can contain markdown |
+It can be aribrary block element: +
|
+
2 |
+Any markdown syntax, e.g. |
+
|
+
(The equation might not work if you view this on PyPI.)
+Install:
+ +Use:
+ +Fenced code blocks is used, with a class table. See Example.
Optionally, YAML metadata block can be used within the fenced code block, following standard pandoc YAML metadata block syntax. 7 metadata keys are recognized:
+captionthe caption of the table. If omitted, no caption will be inserted. Default: disabled.
+alignmenta string of characters among L,R,C,D, case-insensitive, corresponds to Left-aligned, Right-aligned, Center-aligned, Default-aligned respectively. e.g. LCRD for a table with 4 columns. Default: DDD...
widtha list of relative width corresponding to the width of each columns. e.g.
+ +Default: auto calculated from the length of each line in table cells.
+table-widththe relative width of the table (e.g. relative to \linewidth). default: 1.0
headermarkdownincludeinclude-encodinginclude will be decoded according to this encoding, else assumed to be UTF-8.
+csv-kwargsIf specified, should be a dictionary passed to csv.reader as options. e.g.
pipe_tablesIf True, a pipe table will be constructed directly in markdown syntax instead of via AST. markdown is implied to be True. header will be overridden as true because pipe_tables must has header in pandoc.
This trades correctness for speed. It won’t be correct if any of the cell is multiline for example, resulting in an invalid pipe table. However, it is much faster comparing to previous markdown: True case because previously per cell a subprocess to execute pandoc the parse the markdown to AST is needed.
grid_tablesIf True, a grid table will be constructed directly in markdown syntax instead of via AST. markdown is implied to be True. header can be used together with this.
This trades correctness for speed. This should be more robust than pipe_tables since the grid_tables syntax supports everything the pandoc AST supports. This however depends on an external dependency. Install it by either pip install terminaltables or conda install terminaltables.
raw_markdownIf True, force output the table as a pipe table (which is tab-delimited.) This is sometimes useful if pandoc is very stubborn to not emit a pipe table even if markdown-grid_tables... is used. Note that this should only be used if the output format is markdown.
When the metadata keys is invalid, the default will be used instead. Note that width and table-width accept fractions as well.
+pantable2csvThis one is the inverse of pantable, a panflute filter to convert any native pandoc tables into the CSV table format used by pantable.
Effectively, pantable forms a “CSV Reader”, and pantable2csv forms a “CSV Writer”. It allows you to convert back and forth between these 2 formats.
For example, in the markdown source:
++--------+---------------------+--------------------------+
+| First | defaulted to be | can be disabled |
+| row | header row | |
++========+=====================+==========================+
+| 1 | cell can contain | It can be aribrary block |
+| | **markdown** | element: |
+| | | |
+| | | - following standard |
+| | | markdown syntax |
+| | | - like this |
++--------+---------------------+--------------------------+
+| 2 | Any markdown | $$E = mc^2$$ |
+| | syntax, e.g. | |
++--------+---------------------+--------------------------+
+
+: *Awesome* **Markdown** Tablerunning pandoc -F pantable2csv -o output.md input.md, it becomes
``` {.table}
+---
+alignment: DDD
+caption: '*Awesome* **Markdown** Table'
+header: true
+markdown: true
+table-width: 0.8055555555555556
+width: [0.125, 0.3055555555555556, 0.375]
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+- following standard markdown syntax
+- like this
+"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.
+---
+Caption: Comparison
+include: comparison.csv
+...In pandoc 1.19, grid-tables is improved to support all features available to the AST too.↩︎