Related articles:

Tables

Complex Tables

I want to enable line-wrapping in cells of Org tables (or multi-line cells) for org_converter.rb in minimal-mistakes-plus. Currently Org Mode doesn’t natively support automatic line wrapping or multi-line cells in tables (or does it as of 2026?)

I understand that Emacs has the built-in table.el library that supports complex tables with multi-line cells, column- and row-spanning, and cell content justification. Org mode recognizes such tables and exports them properly.

For example, when running the command table-generate-source or org-export-dispatch to generate an HTML table from this text-based table:

Col1 Col2 Col3
foo foo1 Hello World
bar
zoo

The line wrapping, column- and row-spanning, and cell content justification are preserved:

<table>
  <tbody>
    <tr>
      <td align="left" valign="top">Col1</td>
      <td align="left" valign="top">Col2</td>
      <td align="left" valign="top">Col3</td>
    </tr>
    <tr>
      <td align="left" valign="top">
        foo<br>
      </td>
      <td align="left" valign="top">
        foo1<br>
      </td>
      <td align="left" valign="top">
        Hello<br>
        World</td>
    </tr>
    <tr>
      <td align="left" valign="top">bar</td>
      <td colspan="2" align="left" valign="top"></td>
    </tr>
    <tr>
      <td rowspan="2" align="left" valign="top">zoo</td>
      <td align="left" valign="top"></td>
      <td align="left" valign="top"></td>
    </tr>
    <tr>
      <td align="left" valign="top"></td>
      <td align="left" valign="top"></td>
    </tr>
  </tbody>
</table>

As I have tested the same table in minimal-mistakes-plus, org-ruby or org_converter.rb can’t produce the same table structure and preserve the said features. So I want to implement it on our own (or is there already a lib or plugin supporting this? Please check).

Then for alignment I want it to mimic what the variable table-detect-cell-alignment does as described below:

Detect cell contents alignment automatically.
When non-nil cell alignment is automatically determined by the
appearance of the current cell contents when recognizing tables as a
whole.  This applies to `table-recognize', `table-recognize-region'
and `table-recognize-table' but not to `table-recognize-cell'.

But there are problems I don’t like about the table.el tables:

  1. They don’t support headers natively, that is, there’s no way to generate <thead>
  2. They are less convenient to edit than Org tables.

So for the purpose of our implementation I want it to support headers by this rule: If the first row uses = (equal sign) for the horizontal ruler then it’s parsed as a header. For example:

Col1 Col2 Col3
foo foo1 Hello World
bar
zoo

Besides, I want to enable the same features when generating HTML from Org tables in the format:

Col1 Col2 Col3
foo foo1 Hello World
bar
zoo

which is an Org table with the following specifications:

  1. It’s processed specially as a complex table only when it’s marked by #+ATTR_ARGS: :complex t.
  2. When it’s a complex table rows (<tr>) are delimited by horizontal rulers, not lines.
  3. The first row is always interpreted as the header row.
  4. Column-spanning is indicated by the notation <span ... >. To merge several columns of the same row you put <span in the first cell and > in the last.
  5. Row-spanning is recognized automatically when there isn’t a horizontal ruler across several cells in a column but there are rulers across the cells of the same rows in other columns.

  6. #+ATTR_ARGS: can take other arguments:

    • :newlines: Whether to preserve newlines in the output HTML, either as <br> or linefeeds. If nil or unset, don’t preserve newlines, i.e., strip off all <br> and linefeeds in the cell. If t preserve newlines as <br>.

In this way, both table-2-emacs-table and table-2-org-table produce the same output:

<table>
  <thead>
    <tr>
      <th align="left" valign="top">Col1</th>
      <th align="left" valign="top">Col2</th>
      <th align="left" valign="top">Col3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="left" valign="top">
        foo<br>
      </td>
      <td align="left" valign="top">
        foo1<br>
      </td>
      <td align="left" valign="top">
        Hello<br>
        World</td>
    </tr>
    <tr>
      <td align="left" valign="top">bar</td>
      <td colspan="2" align="left" valign="top"></td>
    </tr>
    <tr>
      <td rowspan="2" align="left" valign="top">zoo</td>
      <td align="left" valign="top"></td>
      <td align="left" valign="top"></td>
    </tr>
    <tr>
      <td align="left" valign="top"></td>
      <td align="left" valign="top"></td>
    </tr>
  </tbody>
</table>

The implementation should be very fast and performant.

To natively parse table.el tables and complex Org tables into perfectly aligned, spanning HTML structures without relying on org-ruby’s limited row-by-row parser, we can implement a highly optimized grid-extraction pipeline.

By running this parser within the :pre_render hook, we intercept the raw ASCII tables, calculate the true (x, y) coordinate boundaries of every cell using their border intersections, and compile them into direct HTML wrapped in #+BEGIN_HTML.

Check the commit of these lines here to see the exact lines to change in org_converter.rb file.

Tasks

How to compose alternative contents?

A section whose contents are mostly the same for different systems such as Windows, macOS, Linux, but with difference in certain parameters or segments for each system.

How do you compose such contents in Org Mode and Markdown?

Updated: