[BSv5] Set tables to display:block and explain why (#1477)

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;
 }

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 `<div>`. 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` &mdash; 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 `<table>` 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