Skip to main content

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: December 4, 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: 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 | defaulted to be | can be disabled |
| row | header row | |
+========+====================+========================+
| 1 | cell can contain | It can be aribrary |
| | **markdown** | block 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].

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.
Note that width and table-width accept fractions as well.

``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:

::

+--------+---------------------+--------------------------+
| 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

::

``` {.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$$
```

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 ex | pantable |
| | | cetable | ample | |
+========+====================+============+=============+==========================+
| captio | caption | caption | title | caption |
| n | | | | |
+--------+--------------------+------------+-------------+--------------------------+
| aligns | aligns = LRCD | aligns = L | | aligns = LRCD |
| | | RCD | | |
+--------+--------------------+------------+-------------+--------------------------+
| width | | widths = " | | width: [0.5, 0.2, 0.3] |
| | | 0.5 0.2 0. | | |
| | | 3" | | |
+--------+--------------------+------------+-------------+--------------------------+
| table- | | | | table-width: 1.0 |
| width | | | | |
+--------+--------------------+------------+-------------+--------------------------+
| header | header = yes \| no | header = y | has\_header | header: True \| False \| |
| | | es \| no | : True \| F | yes \| NO |
| | | | alse | |
+--------+--------------------+------------+-------------+--------------------------+
| markdo | | inlinemark | | markdown: True \| False |
| wn | | down | | \| yes \| NO |
+--------+--------------------+------------+-------------+--------------------------+
| source | source | file | source | include |
+--------+--------------------+------------+-------------+--------------------------+
| others | type = simple \| m | | | |
| | ultiline \| grid \ | | | |
| | | pipe | | | |
+--------+--------------------+------------+-------------+--------------------------+
| | | delimiter | | |
+--------+--------------------+------------+-------------+--------------------------+
| | | quotechar | | |
+--------+--------------------+------------+-------------+--------------------------+
| | | id (wrappe | | |
| | | d by div) | | |
+--------+--------------------+------------+-------------+--------------------------+
| Notes | | | | width are auto-calculate |
| | | | | d when width is not spec |
| | | | | ified |
+--------+--------------------+------------+-------------+--------------------------+

.. [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


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pantable-0.11.1-py2-none-any.whl (20.7 kB) Copy SHA256 hash SHA256 Wheel py2
pantable-0.11.1-py3-none-any.whl (19.5 kB) Copy SHA256 hash SHA256 Wheel py3
pantable-0.11.1.tar.gz (15.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page