diff --git a/assets/scss/_table.scss b/assets/scss/_table.scss index 1f6167d888..eadba6ab65 100644 --- a/assets/scss/_table.scss +++ b/assets/scss/_table.scss @@ -1,5 +1,9 @@ -.td-table { +.td-table:not(.td-initial) { @extend .table; - @extend .table-responsive; @extend .table-striped; + @extend .table-responsive; + + // The following is needed for tables to be responsive. + // For details, see the https://docsy.dev/docs/adding-content/lookandfeel/#tables + display: block; } diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index fec0cd4e03..699724b0e4 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -239,6 +239,55 @@ of the following: [wordmark]: https://en.wikipedia.org/wiki/Wordmark [your logo]: /docs/adding-content/iconsimages/#add-your-logo +## Tables + +Docsy applies the following styles to all tables, through the class `.td-table`: + +- [Bootstrap table][] styles: + - `.table` + - `.table-striped` + - `.table-responsive` +- `display: block`, which is necessary for tables to be responsive. + +This styling configuration gives you responsive tables using Markdown only, +without the need to wrap the table in a `
`. It does, however, mean that all your tables have `display` +set to `block`. If you don't want this, you can create your own custom styles for tables. + +{{% alert title="Note" %}} + +Our table styling goes against the [Bootstrap recommendation to _wrap_ +tables][wrap-tables] with `.table-responsive` — however, we think letting +users create responsive tables with just Markdown table syntax is more +convenient. + +[wrap-tables]: https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables + +{{% /alert %}} + +To render a table without Docsy styling, apply the `.td-initial` class to the +table. From the resulting `` style base, it is easier to apply your own +custom styles (rather than trying to undo Docsy table styling), as is +illustrated in the following example: + +```markdown +| Shape | Number of sides | +| -------- | --------------- | +| Triangle | 3 | +| Square | 4 | +{.td-initial .my-dark-table-style} +``` + +The example above uses [Markdown attribute][] syntax, and might render like this: + +| Shape | Number of sides | +| -------- | --------------- | +| Triangle | 3 | +| Square | 4 | +{.td-initial .table .table-dark} + +[Bootstrap table]: https://getbootstrap.com/docs/5.3/content/tables/ +[Markdown attribute]: https://discourse.gohugo.io/t/markdown-attributes/41783 + ## Customizing templates ### Add code to head or before body end