Mkdocs-material: Wide tables differences in Chrome vs Firefox

[sspkmnd]

Description

Initially I asked that question on stackoverflow, however hope to get help here as well.

I am not really a html/css/js guy, but I am doing documentation for one project in MkDocs with Material theme. The problem here is that I have very wide tables and they are displayed differently in Chrome and Firefox, more concrete – they are completely unacceptable in Firefox.

Expected behavior

By default Chrome displays tables very nicely, it chooses column widths that look very nice and reasonable:

https://monosnap.com/file/LvtSxXhE5muFpz8aKhTPvbuoNkMOMN

Actual behavior

Unfortunately, in Firefox the table overflows the container which I suppose should not happen:

https://monosnap.com/file/u9bAq7pGarmGE5hhgawF84ah451HZz

I tried different solutions to fix this, but in the end was not able to find the way to make it look in Firefox as in Chrome. It seems that Chrome uses some logic to display table in a nice looking way.

The closest I can get to a Chrome version was to use the following css:

table {
  table-layout: fixed;
  max-width: 100%;
}

td {
  word-wrap: break-word;
}

It will force the table to stay inside the container and do not overflow, but how the table chooses widths for columns is not good:

https://monosnap.com/file/SJ6T20vIHpRTW5sy3RAa8RfY1Uchiq

Steps to reproduce the bug

I created a demo hosted on Github Pages, the repo itself. Hope this will help to see the difference. Also, there is a button that changes the style for the table, so you can see the difference between table-layout: fixed; and table-layout: auto; – it is just above the table.

Questions

1. Is there a way to make it look in Firefox like in Chrome?
2. Why it overflows the container in Firefox by default? I suppose this should not happen.

PS: I suppose there is a way to set the width explicitly for columns in percent. I tried to achieve so, but I didn't find a way to assign a class to a table <th> via Markdown (which is the source).

Any ideas would be very much appreciated!

Package versions

• Python: 2.7.10
• MkDocs: 1.0.4
• Material: 3.1.0

Project configuration

• GitHub repo with a problem -- https://github.com/sspkmnd/mkdocs-table-layout-problem
• Docs itself hosted on GitHub Pages -- https://sspkmnd.github.io/mkdocs-table-layout-problem/
• problematic Markdown file
• mkdocs.yml

System information

• OS: Mac OS X 10.14.1
• Browser: Chrome 70.0.3538.110, Firefox Developer Edition 65.0b1

[waylan]

It appears that the word-break: break-word; CSS rule on the inline code property is the problem. Notice that Firefox considers it an "invalid property value":

Of course, this then forces the column widths to expand beyond the containing box.

However, Chrome considers it a valid value and wraps the code spans, avoiding the need for wide columns.

According to CSS-Tricks, break-word is a "non standard" value only supported by Webkit. However, changing the value to break-all doesn't seem to make a difference to Firefox in my limited tests. On the other hand, overflow-wrap: break-word; seems to do the trick.

Note that Firefox still needs table-layout: fixed;. Otherwise it doesn't force the code spans to wrap.

[squidfunk]

Thanks for this excellent description and the reproducible case. That makes things much easier for me.

Unfortunately, overflow wrapping in tables is a little inconsistent across browsers. The main problem here are the long titles in the first column. Chrome breaks them due to word-break: break-word but Firefox seems to ignore it.

However, the table is now scrollable so I would not say it is completely unacceptable but could be improved for sure. Defining the layout in a way that it suites all possible use cases is very hard (and probably impossible), so sometimes tweaks are necessary.

I can confirm this bug and will dig into this when I find the time. If somebody finds a fix, feel free to share or PR.

[squidfunk]

Indeed, Firefox doesn't support break-word:
https://developer.mozilla.org/en-US/docs/Web/CSS/word-break#Browser_compatibility

[squidfunk]

@waylan When I typed my comment your answer didn't come up. Thanks for researching into this.

However, table-layout: fixed is an entirely different table layout algorithm, so it might introduce problems with mobile table layout. There are a lot of CSS hacks in place to make them work.

[waylan]

@squidfunk I understand. I was just reporting my findings while playing around in the inspector. I noted that my changes only seem to make any difference when @sspkmnd's table-layout: fixed hack was enabled. My testing was by no means exhaustive and I would not be surprised if a different solution was settled on. At least the cause of the bug is known.

[sspkmnd]

Thank you both for digging into the problem, really appreciate this. I tried what @waylan suggests, but this won't solve the issues though, and forces to use table-layout: fixed anyways.

Also, for me, it is not clear why the table overflows over the container in Firefox, is this the expected behaviour? Chrome definitely uses some smart algorithm to fit the table well.

Manual assignment of widths for each column is ok for me in this case, so I started to search for anything about it and found this discussion about Python-Markdown/markdown#312. So there is no easy way to assign styles in a <th>.

In the end, I wrapped a table into a div to explicitly specify widths only for this table:

<div markdown="1" class="explicit-col-width">

| Parameter          ...
|:------------------ ...
| `abc`              ...
| `longer_param_name ...
| `some_another_para ...

</div>

and used following styles to set the widths:

_::-moz-range-track, body:last-child table {
  table-layout: fixed;
}

.md-typeset td {
  overflow-wrap: break-word;
}

.explicit-col-width th:nth-child(1) { width: 20%; }
.explicit-col-width th:nth-child(2) { width: 10%; }
.explicit-col-width th:nth-child(3) { width: 20%; }
.explicit-col-width th:nth-child(4) { width: 50%; }

Also, it should use table-layout: fixed for Firefox only, so it should break at least less things.

Full diff of changes I did – sspkmnd/mkdocs-table-layout-problem@11322aeceadf05e2867902a0ae3205e4aab7f280

[squidfunk]

Thanks for sharing your findings. Sadly it's nothing that can be generalized because table-layout: fixed is a hack and not a solution in this case, as cell widths have to be set explicitly, so I'll close this as not fixable for now. If somebody comes up with a better solution, I'm happy to merge.

[vijaypolimeru]

Thank you both for digging into the problem, really appreciate this. I tried what @waylan suggests, but this won't solve the issues though, and forces to use table-layout: fixed anyways.

Also, for me, it is not clear why the table overflows over _the container_ in Firefox, is this the expected behaviour? Chrome definitely uses some smart algorithm to fit the table well.

Manual assignment of widths for each column is ok for me in this case, so I started to search for anything about it and found this discussion about Python-Markdown/markdown#312. So there is no easy way to assign styles in a <th>.

In the end, I wrapped a table into a div to explicitly specify widths only for this table:

<div markdown="1" class="explicit-col-width">

| Parameter          ...
|:------------------ ...
| `abc`              ...
| `longer_param_name ...
| `some_another_para ...

</div>

and used following styles to set the widths:

_::-moz-range-track, body:last-child table {
  table-layout: fixed;
}

.md-typeset td {
  overflow-wrap: break-word;
}

.explicit-col-width th:nth-child(1) { width: 20%; }
.explicit-col-width th:nth-child(2) { width: 10%; }
.explicit-col-width th:nth-child(3) { width: 20%; }
.explicit-col-width th:nth-child(4) { width: 50%; }

Also, it _should_ use table-layout: fixed for Firefox only, so it should break at least less things.

Full diff of changes I did – sspkmnd/mkdocs-table-layout-problem@11322ae

Where can I find more details about the Markdown CSS prefixes such as .md-main h1 or .md-typeset. In regular CSS they are not necessary and these commands are making a lot of differece in mkdocs.

Could any provide more information about these kinds of Markdown-CSS prefixes and other options used in Markdown-CSS

[squidfunk]

Where can I find more details about the Markdown CSS prefixes such as .md-main h1 or .md-typeset. In regular CSS they are not necessary and these commands are making a lot of differece in mkdocs.

md- is used by this theme to scope all styles in order to prevent interference with other (custom) styles. It has nothing to do with Markdown CSS (what is this anyway?)

[vijaypolimeru]

Sorry for the ambiguity, i thought .md means Markdown and .md-main , .md-typeset etc are some special CSS class selectors written in mkdocs. (Markdown CSS means CSS with special class selectors for markdown)

Without these class selectors the styles that I am defining for h1 , h2 etc are not applied in mkdocs material theme. However these special class selectors are not necessary in simple html webpage.

Where can I find more info about these class selectors.

[waylan]

@vijaypolimeru the md-main class is defined at material/base.html#L137. It is simply a class assigned to the main tag:

<main class="md-main" role="main">

Therefore any CSS rule which contains that class will only be applied to content within that tag, but not to content outside of that tag. If you look through that file, you will find various other classes as well. It appears that the theme creators simply chose to prepend each class with md as a stylistic choice. It provides no special meaning other than indicating that the related tag is a tag which wraps the Markdown content at some level.

If you find reading through template files confusing (due the mix of HTML and template code), then I recommend looking through the HTML source of a generated page of your project. Or even better, use your browser's "inspect" tool to familiarize yourself with the structure of the HTML. The browser's "inspect" tool also works great for working out which CSS rules are applied to an element and which are overridden due to precedence rules. However, these are general things which apply to any HTML/CSS and are not specific to the Material Theme or even MkDocs. Therefore, this isn't the place to get help with them.

[vijaypolimeru]

Thank you @waylan