-
-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
5 changed files
with
662 additions
and
0 deletions.
There are no files selected for viewing
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,380 @@ | ||
<!DOCTYPE html> | ||
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> | ||
<head> | ||
<meta charset="utf-8" /> | ||
<meta name="generator" content="pandoc" /> | ||
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> | ||
<meta name="dcterms.date" content="2020-07-01" /> | ||
<title>CSV Tables in Markdown — Pandoc Filter for CSV Tables</title> | ||
<style> | ||
code{white-space: pre-wrap;} | ||
span.smallcaps{font-variant: small-caps;} | ||
span.underline{text-decoration: underline;} | ||
div.column{display: inline-block; vertical-align: top; width: 50%;} | ||
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} | ||
ul.task-list{list-style: none;} | ||
pre > code.sourceCode { white-space: pre; position: relative; } | ||
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } | ||
pre > code.sourceCode > span:empty { height: 1.2em; } | ||
code.sourceCode > span { color: inherit; text-decoration: inherit; } | ||
div.sourceCode { margin: 1em 0; } | ||
pre.sourceCode { margin: 0; } | ||
@media screen { | ||
div.sourceCode { overflow: auto; } | ||
} | ||
@media print { | ||
pre > code.sourceCode { white-space: pre-wrap; } | ||
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } | ||
} | ||
pre.numberSource code | ||
{ counter-reset: source-line 0; } | ||
pre.numberSource code > span | ||
{ position: relative; left: -4em; counter-increment: source-line; } | ||
pre.numberSource code > span > a:first-child::before | ||
{ content: counter(source-line); | ||
position: relative; left: -1em; text-align: right; vertical-align: baseline; | ||
border: none; display: inline-block; | ||
-webkit-touch-callout: none; -webkit-user-select: none; | ||
-khtml-user-select: none; -moz-user-select: none; | ||
-ms-user-select: none; user-select: none; | ||
padding: 0 4px; width: 4em; | ||
color: #aaaaaa; | ||
} | ||
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } | ||
div.sourceCode | ||
{ } | ||
@media screen { | ||
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } | ||
} | ||
code span.al { color: #ff0000; font-weight: bold; } /* Alert */ | ||
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ | ||
code span.at { color: #7d9029; } /* Attribute */ | ||
code span.bn { color: #40a070; } /* BaseN */ | ||
code span.bu { } /* BuiltIn */ | ||
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ | ||
code span.ch { color: #4070a0; } /* Char */ | ||
code span.cn { color: #880000; } /* Constant */ | ||
code span.co { color: #60a0b0; font-style: italic; } /* Comment */ | ||
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ | ||
code span.do { color: #ba2121; font-style: italic; } /* Documentation */ | ||
code span.dt { color: #902000; } /* DataType */ | ||
code span.dv { color: #40a070; } /* DecVal */ | ||
code span.er { color: #ff0000; font-weight: bold; } /* Error */ | ||
code span.ex { } /* Extension */ | ||
code span.fl { color: #40a070; } /* Float */ | ||
code span.fu { color: #06287e; } /* Function */ | ||
code span.im { } /* Import */ | ||
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ | ||
code span.kw { color: #007020; font-weight: bold; } /* Keyword */ | ||
code span.op { color: #666666; } /* Operator */ | ||
code span.ot { color: #007020; } /* Other */ | ||
code span.pp { color: #bc7a00; } /* Preprocessor */ | ||
code span.sc { color: #4070a0; } /* SpecialChar */ | ||
code span.ss { color: #bb6688; } /* SpecialString */ | ||
code span.st { color: #4070a0; } /* String */ | ||
code span.va { color: #19177c; } /* Variable */ | ||
code span.vs { color: #4070a0; } /* VerbatimString */ | ||
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ | ||
</style> | ||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/ickc/markdown-latex-css/css/common.min.css" /> | ||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/ickc/markdown-latex-css/fonts/fonts.min.css" /> | ||
<!--[if lt IE 9]> | ||
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script> | ||
<![endif]--> | ||
</head> | ||
<body> | ||
<header id="title-block-header"> | ||
<h1 class="title">CSV Tables in Markdown — Pandoc Filter for CSV Tables</h1> | ||
<p class="date">July 1, 2020</p> | ||
</header> | ||
<nav id="TOC" role="doc-toc"> | ||
<ul> | ||
<li><a href="#pantable"><span class="toc-section-number">1</span> <code>pantable</code></a> | ||
<ul> | ||
<li><a href="#example"><span class="toc-section-number">1.1</span> Example</a></li> | ||
<li><a href="#install-and-use"><span class="toc-section-number">1.2</span> Install and Use</a></li> | ||
<li><a href="#syntax"><span class="toc-section-number">1.3</span> Syntax</a></li> | ||
</ul></li> | ||
<li><a href="#pantable2csv"><span class="toc-section-number">2</span> <code>pantable2csv</code></a></li> | ||
<li><a href="#related-filters"><span class="toc-section-number">3</span> Related Filters</a></li> | ||
</ul> | ||
</nav> | ||
<!-- [](https://travis-ci.org/ickc/pantable) --> | ||
<p><img src="https://github.com/ickc/pantable/workflows/Python%20package/badge.svg" alt="Python package" /> <a href="https://github.com/ickc/pantable/releases"><img src="https://img.shields.io/github/tag/ickc/pantable.svg?label=github+release" alt="GitHub Releases" /></a> <a href="https://pypi.python.org/pypi/pantable/"><img src="https://img.shields.io/pypi/v/pantable.svg" alt="PyPI version" /></a> <a href="https://pypi.python.org/pypi/pantable/"><img src="https://img.shields.io/pypi/status/pantable.svg" alt="Development Status" /></a> <a href="https://pypi.python.org/pypi/pantable/"><img src="https://img.shields.io/pypi/pyversions/pantable.svg" alt="Python version" /></a> <a href="https://pypi.python.org/pypi/pantable/"><img src="https://img.shields.io/pypi/dm/pantable.svg" alt="Downloads" /></a> <img src="https://img.shields.io/pypi/l/pantable.svg" alt="License" /> <!-- [](https://coveralls.io/github/ickc/pantable) --> <!-- [](https://scrutinizer-ci.com/g/ickc/pantable/) --></p> | ||
<p><strong>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 <a href="https://github.com/jgm/pandoc/issues/1024" class="uri">https://github.com/jgm/pandoc/issues/1024</a>, <a href="https://github.com/sergiocorreia/panflute/issues/142" class="uri">https://github.com/sergiocorreia/panflute/issues/142</a>. Until that is resolved, please stick with 2.9.2.1 or below when used together with pantable.</strong></p> | ||
<p>The pantable package comes with 2 pandoc filters, <code>pantable.py</code> and <code>pantable2csv.py</code>. <code>pantable</code> is the main filter, introducing a syntax to include CSV table in markdown source. <code>pantable2csv</code> complements <code>pantable</code>, is the inverse of <code>pantable</code>, which convert native pandoc tables into the CSV table format defined by <code>pantable</code>.</p> | ||
<p>Some example uses are:</p> | ||
<ol> | ||
<li><p>You already have tables in CSV format.</p></li> | ||
<li><p>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.</p></li> | ||
<li><p>You want lower-level control on the table and column widths.</p></li> | ||
<li><p>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.<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a></p></li> | ||
</ol> | ||
<h1 data-number="1" id="pantable"><span class="header-section-number">1</span> <code>pantable</code></h1> | ||
<p>This allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.</p> | ||
<h2 data-number="1.1" id="example"><span class="header-section-number">1.1</span> Example</h2> | ||
<p>Also see the README in <a href="https://ickc.github.io/pantable/">GitHub Pages</a>. There’s a <a href="https://ickc.github.io/pantable/README.pdf">LaTeX output</a> too.</p> | ||
<pre><code>```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$$ | ||
```</code></pre> | ||
<p>becomes</p> | ||
<table style="width:67%;"> | ||
<caption><em>Awesome</em> <strong>Markdown</strong> Table</caption> | ||
<colgroup> | ||
<col style="width: 9%" /> | ||
<col style="width: 25%" /> | ||
<col style="width: 31%" /> | ||
</colgroup> | ||
<thead> | ||
<tr class="header"> | ||
<th style="text-align: right;"><p>First row</p></th> | ||
<th style="text-align: center;"><p>defaulted to be header row</p></th> | ||
<th><p>can be disabled</p></th> | ||
</tr> | ||
</thead> | ||
<tbody> | ||
<tr class="odd"> | ||
<td style="text-align: right;"><p>1</p></td> | ||
<td style="text-align: center;"><p>cell can contain <strong>markdown</strong></p></td> | ||
<td><p>It can be aribrary block element:</p> | ||
<ul> | ||
<li>following standard markdown syntax</li> | ||
<li>like this</li> | ||
</ul></td> | ||
</tr> | ||
<tr class="even"> | ||
<td style="text-align: right;"><p>2</p></td> | ||
<td style="text-align: center;"><p>Any markdown syntax, e.g.</p></td> | ||
<td><p><br /><span class="math display"><em>E</em> = <em>m</em><em>c</em><sup>2</sup></span><br /></p></td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
<p>(The equation might not work if you view this on PyPI.)</p> | ||
<h2 data-number="1.2" id="install-and-use"><span class="header-section-number">1.2</span> Install and Use</h2> | ||
<p>Install:</p> | ||
<div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="ex">pip</span> install -U pantable</span></code></pre></div> | ||
<p>Use:</p> | ||
<div class="sourceCode" id="cb3"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1"></a><span class="ex">pandoc</span> -F pantable -o README.html README.md</span></code></pre></div> | ||
<h2 data-number="1.3" id="syntax"><span class="header-section-number">1.3</span> Syntax</h2> | ||
<p>Fenced code blocks is used, with a class <code>table</code>. See <a href="#example">Example</a>.</p> | ||
<p>Optionally, YAML metadata block can be used within the fenced code block, following standard pandoc YAML metadata block syntax. 7 metadata keys are recognized:</p> | ||
<dl> | ||
<dt><code>caption</code></dt> | ||
<dd><p>the caption of the table. If omitted, no caption will be inserted. Default: disabled.</p> | ||
</dd> | ||
<dt><code>alignment</code></dt> | ||
<dd><p>a string of characters among <code>L,R,C,D</code>, case-insensitive, corresponds to Left-aligned, Right-aligned, Center-aligned, Default-aligned respectively. e.g. <code>LCRD</code> for a table with 4 columns. Default: <code>DDD...</code></p> | ||
</dd> | ||
<dt><code>width</code></dt> | ||
<dd><p>a list of relative width corresponding to the width of each columns. e.g.</p> | ||
<div class="sourceCode" id="cb4"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb4-1"><a href="#cb4-1"></a><span class="kw">-</span><span class="at"> width</span></span> | ||
<span id="cb4-2"><a href="#cb4-2"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fl">0.1</span></span> | ||
<span id="cb4-3"><a href="#cb4-3"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fl">0.2</span></span> | ||
<span id="cb4-4"><a href="#cb4-4"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fl">0.3</span></span> | ||
<span id="cb4-5"><a href="#cb4-5"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fl">0.4</span></span></code></pre></div> | ||
<p>Default: auto calculated from the length of each line in table cells.</p> | ||
</dd> | ||
<dt><code>table-width</code></dt> | ||
<dd><p>the relative width of the table (e.g. relative to <code>\linewidth</code>). default: 1.0</p> | ||
</dd> | ||
<dt><code>header</code></dt> | ||
<dd>If it has a header row or not. True/False/yes/NO are accepted, case-insensitive. default: True | ||
</dd> | ||
<dt><code>markdown</code></dt> | ||
<dd>If CSV table cell contains markdown syntax or not. Same as above. Default: False | ||
</dd> | ||
<dt><code>include</code></dt> | ||
<dd>the path to an CSV file, can be relative/absolute. If non-empty, override the CSV in the CodeBlock. default: None | ||
</dd> | ||
<dt><code>include-encoding</code></dt> | ||
<dd>if specified, the file from <code>include</code> will be decoded according to this encoding, else assumed to be UTF-8. | ||
</dd> | ||
<dt><code>csv-kwargs</code></dt> | ||
<dd><p>If specified, should be a dictionary passed to <code>csv.reader</code> as options. e.g.</p> | ||
<div class="sourceCode" id="cb5"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb5-1"><a href="#cb5-1"></a><span class="pp">---</span></span> | ||
<span id="cb5-2"><a href="#cb5-2"></a><span class="fu">csv-kwargs</span><span class="kw">:</span></span> | ||
<span id="cb5-3"><a href="#cb5-3"></a><span class="at"> </span><span class="fu">dialect</span><span class="kw">:</span><span class="at"> unix</span></span> | ||
<span id="cb5-4"><a href="#cb5-4"></a><span class="at"> </span><span class="fu">key</span><span class="kw">:</span><span class="at"> value...</span></span> | ||
<span id="cb5-5"><a href="#cb5-5"></a><span class="co">...</span></span></code></pre></div> | ||
</dd> | ||
<dt><code>pipe_tables</code></dt> | ||
<dd><p>If True, a pipe table will be constructed directly in markdown syntax instead of via AST. <code>markdown</code> is implied to be True. <code>header</code> will be overridden as true because <code>pipe_tables</code> must has header in pandoc.</p> | ||
<p>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 <code>markdown: True</code> case because previously per cell a subprocess to execute pandoc the parse the markdown to AST is needed.</p> | ||
</dd> | ||
<dt><code>grid_tables</code></dt> | ||
<dd><p>If True, a grid table will be constructed directly in markdown syntax instead of via AST. <code>markdown</code> is implied to be True. <code>header</code> can be used together with this.</p> | ||
<p>This trades correctness for speed. This should be more robust than <code>pipe_tables</code> since the <code>grid_tables</code> syntax supports everything the pandoc AST supports. This however depends on an external dependency. Install it by either <code>pip install terminaltables</code> or <code>conda install terminaltables</code>.</p> | ||
</dd> | ||
<dt><code>raw_markdown</code></dt> | ||
<dd><p>If 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 <code>markdown-grid_tables...</code> is used. Note that this should only be used if the output format is markdown.</p> | ||
</dd> | ||
</dl> | ||
<p>When the metadata keys is invalid, the default will be used instead. Note that width and table-width accept fractions as well.</p> | ||
<h1 data-number="2" id="pantable2csv"><span class="header-section-number">2</span> <code>pantable2csv</code></h1> | ||
<p>This one is the inverse of <code>pantable</code>, a panflute filter to convert any native pandoc tables into the CSV table format used by pantable.</p> | ||
<p>Effectively, <code>pantable</code> forms a “CSV Reader”, and <code>pantable2csv</code> forms a “CSV Writer”. It allows you to convert back and forth between these 2 formats.</p> | ||
<p>For example, in the markdown source:</p> | ||
<pre><code>+--------+---------------------+--------------------------+ | ||
| 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</code></pre> | ||
<p>running <code class="sourceCode bash"><span class="ex">pandoc</span> -F pantable2csv -o output.md input.md</code>, it becomes</p> | ||
<pre><code>``` {.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$$ | ||
```</code></pre> | ||
<h1 data-number="3" id="related-filters"><span class="header-section-number">3</span> Related Filters</h1> | ||
<p>The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.</p> | ||
<ul> | ||
<li><a href="https://github.com/baig/pandoc-csv2table">baig/pandoc-csv2table: A Pandoc filter that renders CSV as Pandoc Markdown Tables.</a></li> | ||
<li><a href="https://github.com/mb21/pandoc-placetable">mb21/pandoc-placetable: Pandoc filter to include CSV data (from file or URL)</a></li> | ||
<li><a href="https://github.com/sergiocorreia/panflute/blob/1ddcaba019b26f41f8c4f6f66a8c6540a9c5f31a/docs/source/csv-tables.py">sergiocorreia/panflute/csv-tables.py</a></li> | ||
</ul> | ||
<table> | ||
<colgroup> | ||
<col style="width: 8%" /> | ||
<col style="width: 25%" /> | ||
<col style="width: 15%" /> | ||
<col style="width: 16%" /> | ||
<col style="width: 34%" /> | ||
</colgroup> | ||
<thead> | ||
<tr class="header"> | ||
<th></th> | ||
<th>pandoc-csv2table</th> | ||
<th>pandoc-placetable</th> | ||
<th>panflute example</th> | ||
<th>pantable</th> | ||
</tr> | ||
</thead> | ||
<tbody> | ||
<tr class="odd"> | ||
<td>caption</td> | ||
<td>caption</td> | ||
<td>caption</td> | ||
<td>title</td> | ||
<td>caption</td> | ||
</tr> | ||
<tr class="even"> | ||
<td>aligns</td> | ||
<td>aligns = LRCD</td> | ||
<td>aligns = LRCD</td> | ||
<td></td> | ||
<td>aligns = LRCD</td> | ||
</tr> | ||
<tr class="odd"> | ||
<td>width</td> | ||
<td></td> | ||
<td>widths = "0.5 0.2 0.3"</td> | ||
<td></td> | ||
<td>width: [0.5, 0.2, 0.3]</td> | ||
</tr> | ||
<tr class="even"> | ||
<td>table-width</td> | ||
<td></td> | ||
<td></td> | ||
<td></td> | ||
<td>table-width: 1.0</td> | ||
</tr> | ||
<tr class="odd"> | ||
<td>header</td> | ||
<td>header = yes | no</td> | ||
<td>header = yes | no</td> | ||
<td>has_header: True | False</td> | ||
<td>header: True | False | yes | NO</td> | ||
</tr> | ||
<tr class="even"> | ||
<td>markdown</td> | ||
<td></td> | ||
<td>inlinemarkdown</td> | ||
<td></td> | ||
<td>markdown: True | False | yes | NO</td> | ||
</tr> | ||
<tr class="odd"> | ||
<td>source</td> | ||
<td>source</td> | ||
<td>file</td> | ||
<td>source</td> | ||
<td>include</td> | ||
</tr> | ||
<tr class="even"> | ||
<td>others</td> | ||
<td>type = simple | multiline | grid | pipe</td> | ||
<td></td> | ||
<td></td> | ||
<td></td> | ||
</tr> | ||
<tr class="odd"> | ||
<td></td> | ||
<td></td> | ||
<td>delimiter</td> | ||
<td></td> | ||
<td></td> | ||
</tr> | ||
<tr class="even"> | ||
<td></td> | ||
<td></td> | ||
<td>quotechar</td> | ||
<td></td> | ||
<td></td> | ||
</tr> | ||
<tr class="odd"> | ||
<td></td> | ||
<td></td> | ||
<td>id (wrapped by div)</td> | ||
<td></td> | ||
<td></td> | ||
</tr> | ||
<tr class="even"> | ||
<td>Notes</td> | ||
<td></td> | ||
<td></td> | ||
<td></td> | ||
<td>width are auto-calculated when width is not specified</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
<section class="footnotes" role="doc-endnotes"> | ||
<hr /> | ||
<ol> | ||
<li id="fn1" role="doc-endnote"><p>In pandoc 1.19, grid-tables is improved to support all features available to the AST too.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li> | ||
</ol> | ||
</section> | ||
</body> | ||
</html> |
Binary file not shown.
Oops, something went wrong.