Multiline Table extension for Python Markdown¶
This project extends the Python markdown implementation with multiline table support. It can be easily used with Python-Markdown and MkDocs as well as Material for MkDocs.
Install¶
The main installation is as easy as any other pip package.
To finally be ready just make sure that your desired target uses the extension.
markdown package¶
from markdown import markdown
from md_multiline_table import MultilineTableExtension
html = markdown(text, extensions=[MultilineTableExtension()])
mkdocs¶
Just add md-multiline-table inside the markdown_extensions of your mkdocs.yml file.
Usage¶
We all know the issue with tables which include a description or any other free text column. The result is always the same. The table will be large and not as pretty and overseeable as small markdown tables.
| Module ID | Class | Description |
|----------:|:-----:|--------------------------------------------------------------------|
| 321 | 1 | Long description text |
| 1234 | 3 | An even longer description text which would be better in two lines |
| 42 | 1 | Short description |
This markdown extension tries to solve this issue with two fairly simple approaches:
- plus sign ending
- colons
Plus sign ending approach (|+)¶
Each row which ends with a plus sing + will be added to the previous row. This approach has the big advantage that the table is even displayed as a correct table even if the extension is not used.
Colon approach (:)¶
Each row which uses colons : instead of pipes | as table borders will be added to the previous row. This approach looks nearly identical to normal markdown tables.
Examples¶
All of the following examples will generate the same result as the example table above.
Example 1
Easiest way to use multiline tables.
| Module ID | Class | Description |
|----------:|:-----:|------------------------------------|
| 321 | 1 | Long description text |
| 1234 | 3 | An even longer description text |
| | | which would be better in two lines |+
| 42 | 1 | Short description |
Example 2
It is not important where the conext or empty cells are inside a multiline table.
| Module | | |
| ID | Class | Description |+
|-------:|:-----:|------------------------------------|
| 321 | 1 | Long description text |
| | 3 | An even longer description text |
| 1234 | | which would be better in two lines |+
| 42 | 1 | Short description |
Example 3
My currently preferred method for making each "complete" line easily identifiable is to use blank lines so that the naked eye can immediately tell where a line begins and ends.
Example 1
Easiest way to use multiline tables.
| Module ID | Class | Description |
|----------:|:-----:|------------------------------------|
| 321 | 1 | Long description text |
| 1234 | 3 | An even longer description text |
: : : which would be better in two lines :
| 42 | 1 | Short description |
Example 2
It is not important where the conext or empty cells are inside a multiline table.
| Module | | |
: ID : Class : Description :
|-------:|:-----:|------------------------------------|
| 321 | 1 | Long description text |
| | 3 | An even longer description text |
: 1234 : : which would be better in two lines :
| 42 | 1 | Short description |
Example 3
A great method for making each "complete" line easily identifiable is to use blank lines so that the naked eye can immediately tell where a line begins and ends.