1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
# Org Table Standard
Applies to: `**/*.org`
Every org table in project docs follows one shape. Wide tables overflow the
page in exported PDF/docx and run off the edge of the org buffer; this is the
standing fix. Promoted from the work project's local convention 2026-06-11.
## Three requirements
1. **Max width 120 columns — measured at render width.** The whole table
line, leading/trailing pipes included, is ≤120 characters as the table
*renders* (exported output, or the org buffer). An org link counts as its
visible label, not its full `[[target][label]]` source, because export and
the live buffer show only the label. This is the one place source width
and render width diverge; **never split a link** to chase a source-width
number — the render is what overflows the page. Non-link cells have no
source/render gap.
2. **Multi-line cells.** When a cell's text would push the row past 120, wrap
it onto continuation rows: repeat the row with the overflow column's text
continued and the other columns left blank, as many continuation rows as
the content needs. Never truncate content to hit the width; wrap it.
3. **A rule under the header and under every logical row.** Put a horizontal
rule (`|---+---|`) after the header and after every data row, closing rule
included. Each logical row then reads as a bordered block, and the rules
are what mark where a logical row (with its continuation lines) ends.
Example — the logical row "arch-00" wrapped across two physical rows, rules
between every row:
| Document | Doc Status | Notes |
|----------+------------+----------------------------------|
| arch-00 | Current | Source-of-truth spec; references |
| | | arch-NN as authority |
|----------+------------+----------------------------------|
| arch-01 | Current | Linear introduction for |
| | | first-time readers |
|----------+------------+----------------------------------|
## How to apply
When authoring or editing any table, produce this shape from the start. When
a table already violates it, reformat in place — preserve every cell's
content and any links verbatim, only change the layout.
Tooling (in every project's `.ai/scripts/` via the template sync):
- `wrap-org-table.el` reflows tables to the standard mechanically:
`emacs --batch -q -l .ai/scripts/wrap-org-table.el [--width=120] FILE.org`.
It wraps over-budget cells onto continuation rows, adds the rules, measures
links at label width, and never splits a token or a link. Re-running on a
conformant table is a no-op.
- `lint-org.el` flags violating tables as judgment items (checker
`org-table-standard`) during its sweep — width overruns, missing rules, or
both — and names the helper in the message.
The helper can't fix a table whose single narrowest-possible columns still
exceed the budget (some token or link label is just too wide). That table
needs restructuring — merge or drop columns, shorten labels — which is a
judgment call: the lint item stays until a human reshapes it.
|
