CSV Tables in Markdown: Pandoc Filter for CSV Tables
Project description
.. This README is auto-generated from `docs/README.md`. Do not edit this file directly.
=====================================================
CSV Tables in Markdown — Pandoc Filter for CSV Tables
=====================================================
:Date: November 30, 2016
.. role:: math(raw)
:format: html latex
..
.. contents::
:depth: 3
..
|Build Status| |GitHub Releases| |PyPI version| |Development Status|
|Python version| |License| |Coveralls|
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]_
``pantable``
============
This allows CSV tables, optionally containing markdown syntax (disabled
by default), to be put in markdown as a fenced code blocks.
Example
-------
Also see the README in `GitHub
Pages <https://ickc.github.io/pantable/>`__. There’s a `LaTeX
output <https://ickc.github.io/pantable/README.pdf>`__ too.
::
```table
---
caption: '*Awesome* **Markdown** Table'
alignment: RC
table-width: 0.7
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 | 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 | .. math:: E = mc^2 |
| | syntax, e.g. | |
+--------+---------------------+--------------------------+
Table: *Awesome* **Markdown** Table
(The equation might not work if you view this on PyPI.)
Install and Use
---------------
Install:
.. code:: bash
pip install -U pantable
Use:
.. code:: bash
pandoc -F pantable -o README.html README.md
Syntax
------
Fenced code blocks is used, with a class ``table``. See
`Example <#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:
- ``caption``: the caption of the table. If omitted, no caption will be
inserted. Default: disabled.
- ``alignment``: a 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...``
- ``width``: a list of relative width corresponding to the width of
each columns. e.g.
.. code:: yaml
- width
- 0.1
- 0.2
- 0.3
- 0.4
Default: auto calculated from the length of each line in table cells.
- ``table-width``: the relative width of the table (e.g. relative to
``\linewidth``). default: 1.0
- ``header``: If it has a header row or not. True/False/yes/NO are
accepted, case-insensitive. default: True
- ``markdown``: If CSV table cell contains markdown syntax or not. Same
as above. Default: False
- ``include``: the path to an CSV file, can be relative/absolute. If
non-empty, override the CSV in the CodeBlock. default: None
When the metadata keys is invalid, the default will be used instead.
Related Filters
---------------
The followings are pandoc filters written in Haskell that provide
similar functionality. This filter is born after testing with theirs.
- `baig/pandoc-csv2table: A Pandoc filter that renders CSV as Pandoc
Markdown Tables. <https://github.com/baig/pandoc-csv2table>`__
- `mb21/pandoc-placetable: Pandoc filter to include CSV data (from file
or URL) <https://github.com/mb21/pandoc-placetable>`__
- `sergiocorreia/panflute/csv-tables.py <https://github.com/sergiocorreia/panflute/blob/1ddcaba019b26f41f8c4f6f66a8c6540a9c5f31a/docs/source/csv-tables.py>`__
+-------+---------------------+------------+-----------+----------------------------+
| | pandoc-csv2table | pandoc-pla | panflute | pantable |
| | | cetable | example | |
+=======+=====================+============+===========+============================+
| capti | caption | caption | title | caption |
| on | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| align | aligns = LRCD | aligns = L | | aligns = LRCD |
| s | | RCD | | |
+-------+---------------------+------------+-----------+----------------------------+
| width | | widths = " | | width: [0.5, 0.2, 0.3] |
| | | 0.5 0.2 0. | | |
| | | 3" | | |
+-------+---------------------+------------+-----------+----------------------------+
| table | | | | table-width: 1.0 |
| -widt | | | | |
| h | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| heade | header = yes \| no | header = y | header: T | header: True \| False \| y |
| r | | es \| no | rue \| Fa | es \| NO |
| | | | lse | |
+-------+---------------------+------------+-----------+----------------------------+
| markd | | inlinemark | | markdown: True \| False \| |
| own | | down | | yes \| NO |
+-------+---------------------+------------+-----------+----------------------------+
| sourc | source | file | source | include |
| e | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| other | type = simple \| mu | | | |
| s | ltiline \| grid \| | | | |
| | pipe | | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | delimiter | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | quotechar | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | id (wrappe | | |
| | | d by div) | | |
+-------+---------------------+------------+-----------+----------------------------+
| Notes | | | | width are auto-calculated |
| | | | | when width is not specifie |
| | | | | d |
+-------+---------------------+------------+-----------+----------------------------+
``pantable2csv``
================
This 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:
.. code:: markdown
+--------+---------------------+--------------------------+
| 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** Table
running ``pandoc -F pantable2csv -o output.md input.md``, it becomes
.. code:: markdown
``` {.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$$
```
.. [1]
In pandoc 1.19, grid-tables is improved to support all features
available to the AST too.
.. |Build Status| image:: https://travis-ci.org/ickc/pantable.svg?branch=master
:target: https://travis-ci.org/ickc/pantable
.. |GitHub Releases| image:: https://img.shields.io/github/tag/ickc/pantable.svg?label=github+release
:target: https://github.com/ickc/pantable/releases
.. |PyPI version| image:: https://img.shields.io/pypi/v/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |Development Status| image:: https://img.shields.io/pypi/status/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |Python version| image:: https://img.shields.io/pypi/pyversions/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |License| image:: https://img.shields.io/pypi/l/pantable.svg
.. |Coveralls| image:: https://img.shields.io/coveralls/ickc/pantable.svg
:target: https://coveralls.io/github/ickc/pantable
=====================================================
CSV Tables in Markdown — Pandoc Filter for CSV Tables
=====================================================
:Date: November 30, 2016
.. role:: math(raw)
:format: html latex
..
.. contents::
:depth: 3
..
|Build Status| |GitHub Releases| |PyPI version| |Development Status|
|Python version| |License| |Coveralls|
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]_
``pantable``
============
This allows CSV tables, optionally containing markdown syntax (disabled
by default), to be put in markdown as a fenced code blocks.
Example
-------
Also see the README in `GitHub
Pages <https://ickc.github.io/pantable/>`__. There’s a `LaTeX
output <https://ickc.github.io/pantable/README.pdf>`__ too.
::
```table
---
caption: '*Awesome* **Markdown** Table'
alignment: RC
table-width: 0.7
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 | 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 | .. math:: E = mc^2 |
| | syntax, e.g. | |
+--------+---------------------+--------------------------+
Table: *Awesome* **Markdown** Table
(The equation might not work if you view this on PyPI.)
Install and Use
---------------
Install:
.. code:: bash
pip install -U pantable
Use:
.. code:: bash
pandoc -F pantable -o README.html README.md
Syntax
------
Fenced code blocks is used, with a class ``table``. See
`Example <#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:
- ``caption``: the caption of the table. If omitted, no caption will be
inserted. Default: disabled.
- ``alignment``: a 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...``
- ``width``: a list of relative width corresponding to the width of
each columns. e.g.
.. code:: yaml
- width
- 0.1
- 0.2
- 0.3
- 0.4
Default: auto calculated from the length of each line in table cells.
- ``table-width``: the relative width of the table (e.g. relative to
``\linewidth``). default: 1.0
- ``header``: If it has a header row or not. True/False/yes/NO are
accepted, case-insensitive. default: True
- ``markdown``: If CSV table cell contains markdown syntax or not. Same
as above. Default: False
- ``include``: the path to an CSV file, can be relative/absolute. If
non-empty, override the CSV in the CodeBlock. default: None
When the metadata keys is invalid, the default will be used instead.
Related Filters
---------------
The followings are pandoc filters written in Haskell that provide
similar functionality. This filter is born after testing with theirs.
- `baig/pandoc-csv2table: A Pandoc filter that renders CSV as Pandoc
Markdown Tables. <https://github.com/baig/pandoc-csv2table>`__
- `mb21/pandoc-placetable: Pandoc filter to include CSV data (from file
or URL) <https://github.com/mb21/pandoc-placetable>`__
- `sergiocorreia/panflute/csv-tables.py <https://github.com/sergiocorreia/panflute/blob/1ddcaba019b26f41f8c4f6f66a8c6540a9c5f31a/docs/source/csv-tables.py>`__
+-------+---------------------+------------+-----------+----------------------------+
| | pandoc-csv2table | pandoc-pla | panflute | pantable |
| | | cetable | example | |
+=======+=====================+============+===========+============================+
| capti | caption | caption | title | caption |
| on | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| align | aligns = LRCD | aligns = L | | aligns = LRCD |
| s | | RCD | | |
+-------+---------------------+------------+-----------+----------------------------+
| width | | widths = " | | width: [0.5, 0.2, 0.3] |
| | | 0.5 0.2 0. | | |
| | | 3" | | |
+-------+---------------------+------------+-----------+----------------------------+
| table | | | | table-width: 1.0 |
| -widt | | | | |
| h | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| heade | header = yes \| no | header = y | header: T | header: True \| False \| y |
| r | | es \| no | rue \| Fa | es \| NO |
| | | | lse | |
+-------+---------------------+------------+-----------+----------------------------+
| markd | | inlinemark | | markdown: True \| False \| |
| own | | down | | yes \| NO |
+-------+---------------------+------------+-----------+----------------------------+
| sourc | source | file | source | include |
| e | | | | |
+-------+---------------------+------------+-----------+----------------------------+
| other | type = simple \| mu | | | |
| s | ltiline \| grid \| | | | |
| | pipe | | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | delimiter | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | quotechar | | |
+-------+---------------------+------------+-----------+----------------------------+
| | | id (wrappe | | |
| | | d by div) | | |
+-------+---------------------+------------+-----------+----------------------------+
| Notes | | | | width are auto-calculated |
| | | | | when width is not specifie |
| | | | | d |
+-------+---------------------+------------+-----------+----------------------------+
``pantable2csv``
================
This 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:
.. code:: markdown
+--------+---------------------+--------------------------+
| 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** Table
running ``pandoc -F pantable2csv -o output.md input.md``, it becomes
.. code:: markdown
``` {.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$$
```
.. [1]
In pandoc 1.19, grid-tables is improved to support all features
available to the AST too.
.. |Build Status| image:: https://travis-ci.org/ickc/pantable.svg?branch=master
:target: https://travis-ci.org/ickc/pantable
.. |GitHub Releases| image:: https://img.shields.io/github/tag/ickc/pantable.svg?label=github+release
:target: https://github.com/ickc/pantable/releases
.. |PyPI version| image:: https://img.shields.io/pypi/v/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |Development Status| image:: https://img.shields.io/pypi/status/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |Python version| image:: https://img.shields.io/pypi/pyversions/pantable.svg
:target: https://pypi.python.org/pypi/pantable/
.. |License| image:: https://img.shields.io/pypi/l/pantable.svg
.. |Coveralls| image:: https://img.shields.io/coveralls/ickc/pantable.svg
:target: https://coveralls.io/github/ickc/pantable
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pantable-0.4.1.tar.gz
(16.0 kB
view hashes)
