diff --git a/.coveragerc b/.coveragerc
new file mode 100644
index 00000000..25176cb0
--- /dev/null
+++ b/.coveragerc
@@ -0,0 +1,10 @@
+[report]
+
+exclude_lines =
+ if __name__ == .__main__.:
+ def main
+ except ZeroDivisionError
+ return \[\]
+ return None
+ __version__
+ py2
diff --git a/.gitignore b/.gitignore
index 63f581b9..5ba5101e 100755
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,25 @@
# macOS files
.DS_Store
-test/*.pdf
\ No newline at end of file
+tests/reference_idempotent.native
+tests/*.native
+tests/*.pdf
+
+# python auxiliary
+__pycache__/
+.cache
+*.pyc
+
+# pypi
+dist/
+pantable.egg-info/
+
+# coverage
+.coverage
+htmlcov/
+
+# pycharm
+.idea/
+
+# rst2html
+README.html
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 00000000..2a9b9b5d
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,109 @@
+# os: linux and sudo: false is assumed, which means it is using container-based Ubuntu 12.04
+language: python
+cache: pip
+# build matrix: different python and pandoc versions
+python:
+ - "2.7"
+ - "3.3"
+ - "3.4"
+ - "3.5"
+ - "3.5-dev" # 3.5 development branch
+ - "3.6-dev" # 3.6 development branch
+ - "nightly" # currently points to 3.7-dev
+ # pypy (version info from [Changelogs — PyPy documentation](http://doc.pypy.org/en/latest/index-of-whatsnew.html))
+ - "pypy" # PyPy2.7 5.3.1 (CPython 2.7 compatible)
+ - "pypy3" # PyPy3 2.4.0 (CPython 3.2 compatible)
+env:
+ # - pandocVersion=1.13.2
+ # - pandocVersion=1.14
+ # - pandocVersion=1.14.0.1
+ # - pandocVersion=1.14.1
+ # - pandocVersion=1.15
+ # - pandocVersion=1.15.0.5
+ # - pandocVersion=1.15.0.6
+ # - pandocVersion=1.15.1
+ # - pandocVersion=1.15.2
+ # - pandocVersion=1.16
+ # - pandocVersion=1.16.0.1
+ # - pandocVersion=1.16.0.2
+ # - pandocVersion=1.17
+ # - pandocVersion=1.17.0.1
+ # - pandocVersion=1.17.0.2
+ # - pandocVersion=1.17.1
+ - pandocVersion=1.17.2
+ # - pandocVersion=1.18
+ - pandocVersion=latest
+matrix:
+ allow_failures:
+ - python: "3.5-dev"
+ - python: "3.6-dev"
+ - python: "nightly"
+ - python: "pypy3"
+ # - env: pandocVersion=1.13.2
+ # - env: pandocVersion=1.14
+ # - env: pandocVersion=1.14.0.1
+ # - env: pandocVersion=1.14.1
+ # - env: pandocVersion=1.15
+ # - env: pandocVersion=1.15.0.5
+ # - env: pandocVersion=1.15.0.6
+ # - env: pandocVersion=1.15.1
+ # - env: pandocVersion=1.15.2
+ fast_finish: true
+# download pandoc
+before_install:
+ - |
+ if [[ $pandocVersion == "latest" ]]; then
+ url="https://github.com/jgm/pandoc/releases/latest"
+ else
+ url="https://github.com/jgm/pandoc/releases/tag/$pandocVersion"
+ fi
+ path=$(curl -L $url | grep -o '/jgm/pandoc/releases/download/.*-amd64\.deb')
+ downloadUrl="https://github.com$path"
+ file=${path##*/}
+# install dependencies
+install:
+ # pandoc
+ - wget $downloadUrl &&
+ sudo dpkg -i $file
+ # latest pip dropped support for py3.2, which is the version of python in pypy3
+ - if [[ "$TRAVIS_PYTHON_VERSION" != "pypy3" ]]; then pip install -U pip; fi
+ - pip install -e .[test]
+before_script:
+ # pasteurize for py2 only, except setup.py & pantable/version.py
+ - |
+ if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]] || [[ "$TRAVIS_PYTHON_VERSION" == "pypy" ]]; then
+ mv setup.py setup.py.temp
+ mv pantable/version.py pantable/version.py.temp
+ pasteurize -wnj 4 .
+ mv setup.py.temp setup.py
+ mv pantable/version.py.temp pantable/version.py
+ fi
+# command to run tests
+script:
+ - make -j4 test
+after_success:
+ - if [[ "$pandocVersion" == "latest" ]] && [[ "$TRAVIS_PYTHON_VERSION" == "3.5" ]]; then coveralls; else printf "skip coveralls"; fi
+before_deploy:
+ # build unpasteurized python3 wheel
+ - python3 setup.py bdist_wheel
+ # pasteurize except setup.py & pantable/version.py
+ - |
+ mv setup.py setup.py.temp
+ mv pantable/version.py pantable/version.py.temp
+ pasteurize -wnj 4 .
+ mv setup.py.temp setup.py
+ mv pantable/version.py.temp pantable/version.py
+ # prepare wheel for py2
+ - pip2 install wheel
+ - python2 setup.py bdist_wheel
+deploy:
+ provider: pypi
+ user: ickc
+ password: $pypi_password
+ # do not add bdist_wheel here, since it is done above
+ distributions: "sdist"
+ skip_cleanup: true
+ on:
+ tags: true
+ python: "3.5"
+ condition: $pandocVersion = latest
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100755
index 00000000..9561fb10
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1 @@
+include README.rst
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..57f0a29e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,293 @@
+
+
+- [`pantable`](#pantable)
+ - [Example](#example)
+ - [Install and Use](#install-and-use)
+ - [Syntax](#syntax)
+- [`pantable2csv`](#pantable2csv)
+- [Related Filters](#related-filters)
+
+[](https://travis-ci.org/ickc/pantable) [](https://github.com/ickc/pantable/releases) [](https://pypi.python.org/pypi/pantable/) [](https://pypi.python.org/pypi/pantable/) [](https://pypi.python.org/pypi/pantable/)  [](https://coveralls.io/github/ickc/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:
+
+1. You already have tables in CSV format.
+
+2. 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.
+
+3. You want lower-level control on the table and column widths.
+
+4. 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]
+
+[1] In pandoc 1.19, grid-tables is improved to support all features available to the AST too.
+
+`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
+
+
+
AwesomeMarkdown Table
+
+
+
+
+
+
+
+
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 = mc2
+
+
+
+
+(The equation might not work if you view this on PyPI.)
+
+Install and Use
+---------------
+
+Install:
+
+``` bash
+pip install -U pantable
+```
+
+Use:
+
+``` 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.
+
+ ``` 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-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
+
+
+
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..d2b2639d
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,275 @@
+.. 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 `__. 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 | 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. `__
+- `mb21/pandoc-placetable: Pandoc filter to include CSV data (from file
+ or URL) `__
+- `sergiocorreia/panflute/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
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..c84642d9
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,188 @@
+---
+fontsize: 11pt
+documentclass: memoir
+classoption: article
+geometry: inner=1in, outer=1in, top=1in, bottom=1.25in
+title: CSV Tables in Markdown --- Pandoc Filter for CSV Tables
+...
+
+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:
+
+1. You already have tables in CSV format.
+
+2. 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.
+
+3. You want lower-level control on the table and column widths.
+
+4. 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.^[In pandoc 1.19, grid-tables is improved to support all features available to the AST too.]
+
+# `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
+
+```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$$
+```
+
+(The equation might not work if you view this on PyPI.)
+
+## Install and Use
+
+Install:
+
+```bash
+pip install -U pantable
+```
+
+Use:
+
+```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.
+
+ ```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`{.bash}, 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)
+
+```table
+---
+Caption: Comparison
+include: docs/comparison.csv
+...
+```
+
diff --git a/docs/README.pdf b/docs/README.pdf
new file mode 100644
index 00000000..c26a3365
Binary files /dev/null and b/docs/README.pdf differ
diff --git a/docs/badges.markdown b/docs/badges.markdown
new file mode 100644
index 00000000..086f15ab
--- /dev/null
+++ b/docs/badges.markdown
@@ -0,0 +1,9 @@
+[](https://travis-ci.org/ickc/pantable)
+[](https://github.com/ickc/pantable/releases)
+[](https://pypi.python.org/pypi/pantable/)
+[](https://pypi.python.org/pypi/pantable/)
+[](https://pypi.python.org/pypi/pantable/)
+
+
+[](https://coveralls.io/github/ickc/pantable)
+
diff --git a/docs/comparison.csv b/docs/comparison.csv
new file mode 100644
index 00000000..cfc920a9
--- /dev/null
+++ b/docs/comparison.csv
@@ -0,0 +1,13 @@
+,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
\ No newline at end of file
diff --git a/docs/example.csv b/docs/example.csv
new file mode 100644
index 00000000..93637e4d
--- /dev/null
+++ b/docs/example.csv
@@ -0,0 +1,3 @@
+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$$
\ No newline at end of file
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 00000000..0dd69916
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,308 @@
+
+
+
+
+
+
+ CSV Tables in Markdown — Pandoc Filter for CSV Tables
+
+
+
+
+
+
+
+
+
CSV Tables in Markdown — Pandoc Filter for CSV Tables
+
December 4, 2016
+
+
+
+
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
+
+
1pantable
+
This allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.
```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
+
+
AwesomeMarkdown Table
+
+
+
+
+
+
+
+
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 = mc2
+
+
+
+
(The equation might not work if you view this on PyPI.)
+
1.2 Install and Use
+
Install:
+
pip install -U pantable
+
Use:
+
pandoc -F pantable -o README.html README.md
+
1.3 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.
+
- 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.
+
2pantable2csv
+
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$$
+```
+
3 Related Filters
+
The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.
