Skip to content

Commit b39a193

Browse files
Jab2870Jab2870
committed
Adds tables and documentation
1 parent 424064d commit b39a193

File tree

9 files changed

+539
-0
lines changed

9 files changed

+539
-0
lines changed

‎README.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,3 +127,52 @@ The `{REDACTED}` or `{SNIP}` shortcodes insert the `\codeSnip` or
127127

128128
The multi-line `{CODECOMMENT}` shortcode adds a centred "notes" box to the code
129129
block which can be useful for annotating code.
130+
131+
## YAML Tables
132+
133+
For the most part, we really like markdown. However, we don't like markdown
134+
tables. Any of them. So, what did we do? Make yet another way of doing them.
135+
136+
137+
![](https://imgs.xkcd.com/comics/standards.png)
138+
139+
In the most basic form, they look like this:
140+
141+
````
142+
143+
```table
144+
- Column 1: row1col1
145+
Column 2: row1col2
146+
Column 3: row1col3
147+
- Column 1: row2col1
148+
Column 3: row2col3
149+
Column 2: row2col2
150+
```
151+
````
152+
153+
![](./images/2025-06-13-14-15-26.png)
154+
155+
However, they are a fair few more options, so documentation for that is
156+
[here](docs/yaml-tables.md).
157+
158+
159+
## CSV Tables
160+
161+
It is also possible to include a CSV or TSV file as a table. You do this using
162+
the normal markdown image syntax:
163+
164+
For instance,
165+
166+
```markdown
167+
![Caption](path/to/file.csv)
168+
```
169+
170+
This will include a csv file as a table. The first row will be used as the table
171+
header. A caption is optional.
172+
173+
It is noteworthy that the same options (except transpose) that are available for
174+
yaml tables, are available for csv tables. For example:
175+
176+
```markdown
177+
![Caption](path/to/file.csv){align=XYZ}
178+
```

‎csv.lua

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
local csv = require("csv")
2+
local utils = require('includes/rcUtils')
3+
local rcTables = require('includes/rcTables')
4+
5+
local function rawLatex(filename, tableOptions, caption)
6+
local latex=""
7+
local file=""
8+
if pandoc.path.is_relative(filename) then
9+
for _,path in ipairs(PANDOC_STATE.resource_path) do
10+
file = string.format("%s/%s",path,filename)
11+
if utils.file_exists( file ) then
12+
break
13+
end
14+
file=utils.urldecode(file)
15+
if utils.file_exists( file ) then
16+
break
17+
end
18+
end
19+
else
20+
file=filename
21+
end
22+
23+
if utils.file_exists(file) then
24+
local f = csv.open(file)
25+
local header=true
26+
local firstCol=true
27+
local cols=0
28+
29+
for fields in f:lines() do
30+
firstCol=true
31+
if header then
32+
header=false
33+
cols=#fields;
34+
latex = latex .. rcTables.begin("\\textwidth",tableOptions.align,cols)
35+
if caption ~= nil then
36+
latex = latex .. string.format("\\caption{ %s }\\\\\n",caption)
37+
end
38+
39+
if tableOptions.grid then
40+
latex = latex .. '\\hline \n'
41+
end
42+
43+
latex = latex .. rcTables.headerrow(fields,tableOptions)
44+
45+
if tableOptions.grid then
46+
latex = latex .. '\\hline \n'
47+
end
48+
else
49+
latex = latex .. rcTables.row(fields,cols)
50+
51+
if tableOptions.grid then
52+
latex = latex .. '\\hline \n'
53+
end
54+
end
55+
end
56+
latex = latex .. "\\end{tabularx}"
57+
else
58+
-- We would get here if the file isn't found in any of the paths
59+
latex=string.format("\\colorbox{red}{The file \\texttt{%s} was not found}",filename:gsub('_','\\_'))
60+
end
61+
62+
return pandoc.RawBlock('latex',latex)
63+
end
64+
65+
function Para(el)
66+
if #el.content == 1 and el.content[1].tag == "Image" then
67+
-- This is an "image" without a caption
68+
local image = el.content[1]
69+
local tableOptions = rcTables.tableOptions(image.attr.attributes, image.attr.classes)
70+
if utils.ends_with(image.src,'.csv') or utils.ends_with(image.src,'.tsv') then
71+
return rawLatex(image.src,tableOptions)
72+
end
73+
end
74+
return el
75+
end
76+
77+
function Figure(el)
78+
-- Pandoc puts images inside a plain block inside the figure
79+
--
80+
-- (#) Figure {
81+
-- attr: Attr {
82+
-- ...
83+
-- }
84+
-- caption: {
85+
-- ...
86+
-- }
87+
-- content: Blocks[1] {
88+
-- [1] Plain {
89+
-- content: Inlines[1] {
90+
-- [1] Image {
91+
-- ..
92+
-- }
93+
-- }
94+
-- }
95+
-- }
96+
-- }
97+
if #el.content == 1 and #el.content[1].content == 1 and el.content[1].content[1].tag == "Image" then
98+
local caption=pandoc.utils.stringify(el.caption.long[1].content)
99+
100+
101+
local image = el.content[1].content[1]
102+
local tableOptions = rcTables.tableOptions(image.attr.attributes, image.attr.classes)
103+
if utils.ends_with(image.src,'.csv') or utils.ends_with(image.src,'.tsv') then
104+
return rawLatex(image.src, tableOptions, caption)
105+
end
106+
end
107+
return el
108+
end

‎docs/images/2025-06-13-14-33-31.png

Lines changed: 3 additions & 0 deletions
Loading

‎docs/images/2025-06-13-14-37-16.png

Lines changed: 3 additions & 0 deletions
Loading

‎docs/images/2025-06-13-14-40-11.png

Lines changed: 3 additions & 0 deletions
Loading

‎docs/yaml-tables.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# YAML Tables
2+
3+
For the most part, we really like markdown. However, we don't like markdown
4+
tables. Any of them. So, what did we do? Make yet another way of doing them.
5+
6+
![](https://imgs.xkcd.com/comics/standards.png)
7+
8+
In the most basic form, they look like this:
9+
10+
````
11+
```table
12+
- Column 1: row1col1
13+
Column 2: row1col2
14+
Column 3: row1col3
15+
- Column 1: row2col1
16+
Column 3: row2col3
17+
Column 2: row2col2
18+
```
19+
````
20+
21+
![](../images/2025-06-13-14-15-26.png)
22+
23+
24+
25+
These yaml tables have a number of options.
26+
27+
Adding the class `transpose`, as below, will transpose the table so the left
28+
most column is highlighted blue rather than the top row. For example:
29+
30+
````
31+
```{.table .transpose}
32+
Row 1: Data 1
33+
Row 2: Data 2
34+
Row 3: Data 3
35+
```
36+
````
37+
38+
![](./images/2025-06-13-14-33-31.png)
39+
40+
## Alignment / Width
41+
42+
In latex, these alignment options also determine the width of table columns.
43+
44+
`X`, `Y` and `Z` will align text left, centre and right respectively. Any
45+
columns with these alignments will have equal width based on remaining space.
46+
47+
`x`, `y` and `z` will also align text left, centre and right respectively.
48+
However, the width of the cell is determined by the contents of a cell.
49+
50+
Lastly `L[*]`, `C[*]` and `R[*]` will also align text left, centre and right
51+
respectively. However, the width of the cell is determined by the width
52+
specified in the brackets.
53+
54+
55+
So, for example,
56+
57+
````
58+
```{.table .transpose align=xX}
59+
col1row1: col2row1
60+
col1row2: col2row2
61+
```
62+
````
63+
64+
![](./images/2025-06-13-14-37-16.png)
65+
66+
## Header Rotation
67+
68+
69+
Adding `rotateHeader` to the class list will result in the table headers being
70+
written sideways in order to fit more columns in.
71+
72+
````
73+
```{.table align=YYY .rotateHeader}
74+
- Column 1: row1col1
75+
Column 2: row1col2
76+
Column 3: row1col3
77+
- Column 1: row2col1
78+
Column 3: row2col3
79+
Column 2: row2col2
80+
```
81+
````
82+
83+
![](./images/2025-06-13-14-40-11.png)
84+
85+

‎images/2025-06-13-14-15-26.png

Lines changed: 3 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)