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