Why Sponsor Oils? | source | all docs for version 0.24.0 | all versions | oilshell.org

ul-table: Markdown Tables Without New Syntax

Our ul-table plugin allows you to write HTML tables as bulleted lists.

Why?

• Because writing and maintaining <tr> and <td> and </td> and </tr> is tedious.
• Because Markdown can express bulleted lists, so your file remains valid Markdown.
  • Your documentation still be readable when viewed with sourcehut or Github.

That is, this way of writing tables involves no new syntax. It's not a Markdown language extension.

Simple Example

Suppose you want to make this table:

With ul-table, you type a two-level Markdown list, inside <table> tags:

<table>

- thead
  - Shell
  - Version
- tr
  - [bash]($xref)
  - 5.2
- tr
  - [OSH]($xref)
  - 0.25.0

</table>

(This format looks similar to tables in reStructuredText).

The conversion takes two steps:

1. Any Markdown translator will produce a <table> <ul> <li> ... </li> </ul> </table> structure.
2. Our ul-table plugin transforms that into a <table> <tr> <td> </td> </tr> </table> structure, which is a normal HTML table.

Pure Markdown Requires Tedious HTML

The bulleted lists are easier to read and write! Here's the equivalent in CommonMark:

<table>
  <thead>
    <tr>
      <td>Shell</td>
      <td>Version</td>
    </tr>
  </thead>
  <tr>
    <td>

    [bash]($xref)

    </td>
    <td>5.2</td>
  </tr>
  <tr>
    <td>

    [OSH]($xref)

    </td>
    <td>0.25.0</td>
  </tr>

</table>

It uses the rule where you can embed HTML inside markdown, and then markdown inside HTML.

With ul-table, we remove this kind of mutual nesting (at least, one level of it.)

Note that HTML inside CommonMark results in an extra <p> element:

<td>
  <p>OSH</p>
</td>

In contrast, ul-table can produce:

<td>
  OSH
</td>

Stylesheet

To make the table look nice, I use <style> tags inside Markdown:

<style>
table {
  margin: 0 auto;
}
thead {
  font-weight: bold;
}
td {
  padding: 5px;
}
</style>

The Untranslated Markdown

By the way, if you omit the <table> tags, then the bulleted list looks like this:

• thead
  • Shell
  • Version
• tr
  • bash
  • 5.2
• tr
  • OSH
  • 0.25.0

This is how your tables will appear on sourcehut or Github — the contents are still readable. Remember, ul-table is not an extension to Markdown syntax.

More Complex Example

View the source code of this table: doc/ul-table.md

echo sh=$bash
ls /tmp | wc -l
echo

Real Examples in Oils

TODO

• docs
  • convert proc-func table
  • interior/exterior?
• blog
  • What Oils Looks Like in 2024
  • Line Counts
  • Narrow waist? diagrams

ul-table Features

• Any markdown can be in a cell
  • paragraphs, code blocks with backticks, nested lists
  • Markdown supports arbitrary HTML, so arbitrary HTML can be in a cell
    • no new rules to learn!
• TODO: Attributes for columns, rows, and cells
  • <ul-col class=foo />
    • Note: I ran into problems with <colgroup>
    • Example: Justify columns left and right
  • <ul-row class=foo />
  • <ul-td colspan=2 />

Note: should have a custom rule of aligning numbers to right, and text to left? I think web/table/ has that rule.

Quirks

(1) CommonMark doesn't seem to allow empty list items:

- thead
  -
  - above is not rendered as a list item

A workaround is to use a comment:

- tr
  - <!-- empty -->
  - above is OK

• Related CommonMark thread

(2) Likewise, a cell containing a hyphen may need a comment in front of it:

- tr
  - <!-- hyphen --> -
  - <!-- hyphen --> -

(3) I ran into an issue where line breaks affect backtick expansion to <code>:

- tr
  - <ul-td /> <!-- we need something on this line -->
    ... More `proc` features ...

This is probably the same as case (1), because the <ul-td /> is considered empty.

Appendix

Related Docs

• How We Build Oils Documentation
• Examples of HTML Plugins

Our Style is Nicer Than Github's

Github-flavored Markdown has an non-standard extension for tables:

• Github: Organizing Information With Tables

This style is hard to read and write, especially with large tables:

| Command | Description |
| --- | --- |
| git status | List all new or modified files |
| git diff | Show file differences that haven't been staged |

Our style is less noisy and more easily editable:

- thead
  - Command
  - Description
- tr
  - git status
  - List all new or modified files
- tr
  - git diff
  - Show file differences that haven't been staged

CommonMark

• 2014 discussion: Tables in pure Markdown
• 2022 discussion: Obvious Markdown syntax for Tables

Implemention

• doctools/ul_table.py - less than 400 lines
• lazylex/html.py - about 400 lines

TODO:

• Make it run under Python 3, including unit tests
• De-couple it from cmark.so
  • Use Unix pipes, with a demo in doctools/ul-table.sh