From a671659c00b33b41cbc355c05458501cbc6cafb2 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Mar 2023 08:37:37 -0500 Subject: [PATCH 1/3] [BSv5] Set tables to display:block and explain why --- assets/scss/_table.scss | 8 +++- .../en/docs/adding-content/lookandfeel.md | 42 +++++++++++++++++++ 2 files changed, 48 insertions(+), 2 deletions(-) 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..447e79c642 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -239,6 +239,48 @@ of the following: [wordmark]: https://en.wikipedia.org/wiki/Wordmark [your logo]: /docs/adding-content/iconsimages/#add-your-logo +## Tables + +By default, Docsy applies the following styles (through the class `.td-table`) +to all tables: + +- [Bootstrap table][] styles: + - `.table` + - `.table-striped` + - `.table-responsive` +- `display: block`, which is necessary for tables to be responsive. + +This particular styling configuration goes against the [Bootstrap recommendation +of _wrapping_ tables][wrap-tables] with `.table-responsive`, but it is more +convenient for content writers who get responsive tables using table Markdown +only, without the need for a wrapping `
`. The price to pay is that `display` +is set to `block`. + +To render a table without Docsy styles, 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 next: + +```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 +[wrap-tables]: https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables + ## Customizing templates ### Add code to head or before body end From dfc044c9829438e3ef73ea677c22bd02bb289a0e Mon Sep 17 00:00:00 2001 From: LisaFC Date: Fri, 10 Mar 2023 14:07:01 +0000 Subject: [PATCH 2/3] Update lookandfeel.md Small tweaks - broke up a couple of sentences, also put the bit about Bootstrap's recommendation into a note as it's not *absolutely* necessary to use the feature but might be interesting to some readers. --- .../en/docs/adding-content/lookandfeel.md | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index 447e79c642..bbde58cacd 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -241,8 +241,7 @@ of the following: ## Tables -By default, Docsy applies the following styles (through the class `.td-table`) -to all tables: +By default, Docsy applies the following styles to all tables, through the class `.td-table`: - [Bootstrap table][] styles: - `.table` @@ -250,16 +249,20 @@ to all tables: - `.table-responsive` - `display: block`, which is necessary for tables to be responsive. -This particular styling configuration goes against the [Bootstrap recommendation -of _wrapping_ tables][wrap-tables] with `.table-responsive`, but it is more -convenient for content writers who get responsive tables using table Markdown -only, without the need for a wrapping `
`. The price to pay is that `display` -is set to `block`. +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. -To render a table without Docsy styles, apply the `.td-initial` class to the +{{% alert title="Note" %}} +Our default 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. +{{% /alert %}} + +To render a table without default 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 next: +custom styles (rather than trying to undo default Docsy table styling), as is +illustrated in the following example: ```markdown | Shape | Number of sides | From 639a16e8ed06bacc2f6739238dbd78505d01a583 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Mar 2023 14:28:10 -0500 Subject: [PATCH 3/3] Fix link, plus a few more tweaks --- .../en/docs/adding-content/lookandfeel.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index bbde58cacd..699724b0e4 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -241,7 +241,7 @@ of the following: ## Tables -By default, Docsy applies the following styles to all tables, through the class `.td-table`: +Docsy applies the following styles to all tables, through the class `.td-table`: - [Bootstrap table][] styles: - `.table` @@ -254,14 +254,19 @@ without the need to wrap the table in a `
`. It does, however, mean that all set to `block`. If you don't want this, you can create your own custom styles for tables. {{% alert title="Note" %}} -Our default 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. + +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 default Docsy styling, apply the `.td-initial` class to the +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 default Docsy table styling), as is +custom styles (rather than trying to undo Docsy table styling), as is illustrated in the following example: ```markdown @@ -282,7 +287,6 @@ The example above uses [Markdown attribute][] syntax, and might render like this [Bootstrap table]: https://getbootstrap.com/docs/5.3/content/tables/ [Markdown attribute]: https://discourse.gohugo.io/t/markdown-attributes/41783 -[wrap-tables]: https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables ## Customizing templates