Improve style for <table> with <caption>

[cebarobot]

Context

I'm attempting to add captions to tables in Markdown by embedding <caption> elements within <table> elements, but the results don't appear as visually appealing as expected. The caption is displayed inside of the table border, and it seems that there is no stylesheet to handle this.

For example, this is an simple HTML table:

<table>
  <caption>Simple Table Caption</caption>
  <tr> <th>foo</th> <th>bar</th> </tr>
  <tr> <td>wawawa</td> <td>hahaha</td> </tr>
</table>

The outcome of Mkdocs for Material looks not good.

This is not a problem about syntax of table caption. It's about the build-in CSS.

pymdownx.blocks.caption always generates <figure> and <figurecaption> rather than <table> and <caption>, so it is unrelated with this issue.

Description

Improve the stylesheet for <table> and <caption>, to make sure caption is displayed outside of the table border.

Related links

HTML reference:

• https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption

Markdown extension for table caption:

• Python-markdown: flywire/caption
• Pandoc: https://pandoc.org/MANUAL.html#extension-table_captions
• Markdown-it: markdown-it-table-captions

Use Cases

<caption> is a standard HTML element that specifies the caption (or title) of a table. Mkdocs-material should provide the appropriate stylesheet for it.

Additionally, some Markdown extensions offer different syntaxes for adding captions to tables, all of which use <caption> in the generated HTML.

Visuals

The expected style is as follows:

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[facelessuser]

pymdownx.blocks.caption always generates <figure> and <figurecaption> rather than <table> and <caption>, so it is unrelated with this issue.

I won't get into specific issues with the referenced extension unless you bring up specific points, but you seem to be highlighting that you don't like that the table is wrapped with <figure>.

Let me address some confusion. If you put the caption directly under the table, it is inside the table, so any border on the table is going to be around the caption. This a sane and reasonable approach. If you do not like this, I would strongly advise not placing the caption inside the table. That is why <figure> and <figecaption> exist. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure. It is also why pymdownx.blocks.caption always generates

and . Figure doesn't mean image or anything specific. Anything with a caption can be a figure.

[cebarobot]

Thanks a lot for your reply.

I won't get into specific issues with the referenced extension unless you bring up specific points, but you seem to be highlighting that you don't like that the table is wrapped with <figure>.

I have to say that <figure> and <figurecaption> has no relation with this issue. <figure> and <figurecaption> are great, but I just want to talk about the style of <table> and its <caption>.

Let me address some confusion. If you put the caption directly under the table, it is inside the table, so any border on the table is going to be around the caption. This a sane and reasonable approach. If you do not like this, I would strongly advise not placing the caption inside the table. That is why <figure> and <figecaption> exist.

Actually, I think directly applying a border around the entire <table> is worth reconsidering, as it effectively prevents the use of the standard HTML <caption> element. This is the key point I'm trying to emphasize.

From my observations, using the <caption> element is a common pratice in HTML. Tools like Pandoc, Sphinx, Asciidoctor and so on follows this approach. Therefore, I would like to see Mkdocs-Material be more accommodating to this convention.

[squidfunk]

Thanks for reporting. So, this happens due to a hack we've had in place for 8 years, as we set the display property from table to inline-block, which we added in 8f48f0b and released as part of 1.1.0:

mkdocs-material/src/templates/assets/stylesheets/main/_typeset.scss

Lines 455 to 457 in 3cc0a30

	table:not([class]) {
	display: inline-block;
	max-width: 100%;

I'm not sure whether we still need this hack, because it's been such a long time ago, so issues might have been fixed, but digging into the changelog and related issues, I've found the following:

• Tables cannot be set to 100% width #175
• Fixed inconsistencies in table-styling #185

We're in feature freeze right now, and since this is not a simple to fix bug, as it's hard to know the impact, we'll address this later, once we finish the foundational work we're currently working on. In the meantime, the following additional CSS should mitigate the issue, but it will revert the hack that we've got in place to normalize table styling:

.md-typeset table:not([class]) {
    display: table;
}

[cebarobot]

In addition, I'm curious as to why Mkdocs-Material's border of <table> also includes the <caption>, while in other environment, the border only surrounds the table body.

Example:

<table style="border:1px solid;">
    <caption>Simple Table Caption</caption>
    <tr> <th>foo</th> <th>bar</th> </tr>
    <tr> <td>wawawa</td> <td>hahaha</td> </tr>
</table>

Result:

I discovered that the display: inline-block; style applied to <table> seems to be the culprit.

Example:

<table style="border:1px solid; display: inline-block;">
    <caption>Simple Table Caption</caption>
    <tr> <th>foo</th> <th>bar</th> </tr>
    <tr> <td>wawawa</td> <td>hahaha</td> </tr>
</table>

Result:

The suspicious code is here:

mkdocs-material/src/templates/assets/stylesheets/main/_typeset.scss

Lines 454 to 457 in 3cc0a30

	// Data table
	table:not([class]) {
	display: inline-block;
	max-width: 100%;

I'm not entirely sure why there is such ...

[squidfunk]

Or you know what, I wouldn't declare this a bug, actually, but rather a limitation of the current design. Thus, I'm marking this as a change request that is currently resolvable with customization.

[squidfunk]

@cebarobot our comments overlapped timewise – yes, you're right, this is the property in question, see #7889 (comment)

[cebarobot]

@squidfunk Thanks a lot for your reply. I really appreciate your help.

[facelessuser]

@cebarobot Ah, I see now you were referring to caption, not figcaption. That was my fault. I think I was thrown off by the mention of the extension.

[cebarobot]

@facelessuser No problem at all. I appreciate your help in this.