[BSv5] blocks/section row-col hierarchy fix

google · Mar 9, 2023 · 5593385 · 5593385
1 parent 33e1a49
commit 5593385
Show file tree

Hide file tree

Showing 13 changed files with 56 additions and 66 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,24 +14,28 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone.
 
 **Breaking changes**:
 
-- **[Upgraded Bootstrap ([#470][])** to v5. For a list of Bootstrap breaking
-  changes, see the [Bootstrap migration guide][bsv5mig]. Other, Docsy-specific
+- **Upgraded Bootstrap ([#470][])** to v5.2. For a list of Bootstrap's breaking
+  changes, see the [Bootstrap migration guide][bsv5mig]. Other Docsy-specific
   changes are listed below:
-  - Clean up of unused, or rarely used, variables and functions:
-    - Dropped `$primary-light`.
-    - Dropped `color-diff()`.
-  - BSv4 RTL support, being incompatible with BSv5, has been removed. For
-    progress in RTL support, see [#1442][].
-  - Dropped the `bg-gradient-variant()` mixin. [#1369][].
+  - Clean up of unused, or rarely used, variables, functions, and mixins:
+    - Dropped `$primary-light`
+    - Dropped `color-diff()`
+    - Dropped `bg-gradient-variant()` mixin ([#1369][])
+  - Docsy's RTL support has been removed because it is incompatible with BSv5.
+    For progress on the reintroduction of RTL support, see [#1442][].
+- `blocks/section` shortcode `type` argument: the **default** and accepted
+  values have changed! For details see [blocks/section][] ([#1472][]).
 
 **Other changes**:
 
 - Non-breaking changes that result from the Bootstrap v5 upgrade:
-  - Draw.io diagram edit button: replace custom colors by BS's outline primary.
+  - Draw.io diagram edit button: replaced custom colors by BS's outline primary.
 
 [#470]: https://github.com/google/docsy/issues/470
 [#1369]: https://github.com/google/docsy/issues/1369
 [#1442]: https://github.com/google/docsy/issues/1442
+[#1472]: https://github.com/google/docsy/issues/1472
+[blocks/section]: https://www.docsy.dev/docs/adding-content/shortcodes/#blockssection
 [bsv5mig]: https://getbootstrap.com/docs/5.2/migration/
 
 ## [0.6.0][]

diff --git a/assets/scss/_boxes.scss b/assets/scss/_boxes.scss
@@ -77,26 +77,17 @@
 
 // Styling for section boxes
 .td-box {
-  .row.section {
-    padding-left: 5vw;
-    padding-right: 5vw;
-    flex-direction: column;
-
-    > table {
-      @extend .table-striped;
-
-      @extend .table-responsive;
-
-      @extend .table;
-    }
-  }
-
   .row {
     padding-left: 5vw;
     padding-right: 5vw;
-    flex-direction: row;
+  }
+  table {
+    @extend .table;
+    @extend .table-striped;
+    @extend .table-responsive;
   }
 }
+
 // Styling for community page link boxes
 
 .td-box.linkbox {

diff --git a/layouts/_default/content.html b/layouts/_default/content.html
@@ -6,7 +6,7 @@ <h1>{{ .Title }}</h1>
 		{{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) }}
 			{{ partial "reading-time.html" . }}
 		{{ end }}
-	</header>    
+	</header>
 	{{ .Content }}
 	{{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable) (.Site.GoogleAnalytics)) }}
 		{{ partial "feedback.html" .Site.Params.ui.feedback }}
@@ -18,3 +18,4 @@ <h1>{{ .Title }}</h1>
 	{{ end }}
 	{{ partial "page-meta-lastmod.html" . }}
 </div>
+{{/**/ -}}
diff --git a/layouts/_default/list.html b/layouts/_default/list.html
@@ -1,5 +1,3 @@
-{{ define "main" }}
-{{ with .Content }}
-{{ . }}
+{{ define "main" -}}
+{{ .Content -}}
 {{ end }}
-{{ end }}
diff --git a/layouts/_default/search.html b/layouts/_default/search.html
@@ -1,8 +1,8 @@
-{{ define "main" }}
+{{ define "main" -}}
 <section class="row td-search-result">
 <div class="col-12 col-md-8 offset-md-2">
 <h2 class="ms-4">{{ .Title }}</h2>
-{{ with .Site.Params.gcs_engine_id }}
+{{ with .Site.Params.gcs_engine_id -}}
 <script>
 (function() {
 var cx = '{{ . }}';
@@ -14,9 +14,8 @@ <h2 class="ms-4">{{ .Title }}</h2>
 s.parentNode.insertBefore(gcse, s);
 })();
 </script>
-			<gcse:searchresults-only></gcse:searchresults-only>
-{{ end }}
+<gcse:searchresults-only></gcse:searchresults-only>
+{{ end -}}
 </div>
 </section>
-
-{{ end }}
+{{ end }}
diff --git a/layouts/_default/single.html b/layouts/_default/single.html
@@ -1,5 +1,3 @@
-{{ define "main" }}
-{{ with .Content }}
-{{ . }}
+{{ define "main" -}}
+{{ .Content -}}
 {{ end }}
-{{ end }}
diff --git a/layouts/community/list.html b/layouts/community/list.html
@@ -1,6 +1,6 @@
 {{ define "main" -}}
 
-<a class="td-offset-anchor"></a>
+<div><a class="td-offset-anchor"></a></div>
 <section
   class="row td-box td-box--primary position-relative td-box--height-auto"
 >

diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html
@@ -5,12 +5,13 @@
     {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
   {{ end -}}
 {{ end -}}
+
 <div><a id="td-block-{{ .Ordinal }}" class="td-offset-anchor"></a></div>
 <section class="row td-box td-box--{{ $col_id }} position-relative td-box--height-{{ $height }}">
 <div class="col-12 px-0">
 <div class="container text-center td-arrow-down">
 <div class="h4 mb-0">
-{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
 {{ .Inner }}
 </div>
 </div>

diff --git a/layouts/shortcodes/blocks/section.html b/layouts/shortcodes/blocks/section.html
@@ -1,16 +1,14 @@
-{{ $_hugo_config := `{ "version": 1 }` -}}
 {{ $col_id := .Get "color" | default .Ordinal -}}
 {{ $height := .Get "height" | default "auto"  -}}
-{{ $type   := .Get "type" | default "" -}}
-<a id="td-block-{{ .Ordinal }}" class="td-offset-anchor"></a>
+{{ $type   := .Get "type" | default "container" -}}
+
+<div><a id="td-block-{{ .Ordinal }}" class="td-offset-anchor"></a></div>
 <section class="row td-box td-box--{{ $col_id }} td-box--height-{{ $height }}">
-	<div class="col">
-		<div class="row {{ $type }}">
-			{{ if eq .Page.File.Ext "md" -}}
-				{{ .Inner | markdownify -}}
-			{{ else -}}
-				{{ .Inner | htmlUnescape | safeHTML -}}
-			{{ end -}}
-		</div>
-	</div>
+<div class="col px-0">
+<div class="{{ $type }}">
+{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ .Inner -}}
+</div>
+</div>
 </section>
+{{/**/ -}}
diff --git a/userguide/content/en/_index.md b/userguide/content/en/_index.md
@@ -27,7 +27,8 @@ on creating great content for your users.
 </a>
 {{% /blocks/lead %}}
 
-{{% blocks/section color="dark" type="features"%}}
+{{% blocks/section color="dark" type="row" %}}
+
 {{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}}
 As well as our example site, there's a growing number of projects using Docsy for their doc sites.
 {{% /blocks/feature %}}

diff --git a/userguide/content/en/about/_index.md → userguide/content/en/about/index.md b/userguide/content/en/about/_index.md → userguide/content/en/about/index.md
@@ -2,7 +2,6 @@
 title: About Docsy
 linkTitle: About
 menu: {main: {weight: 10}}
-layout: docs
 ---
 
 {{% blocks/cover title="About Docsy" height="auto" %}}
@@ -12,7 +11,7 @@ Docsy is a pre-configured Hugo theme that provides the core features and behavio
 Read on to find out more, or visit our [documentation](/docs/) to get started!
 {{% /blocks/cover %}}
 
-{{% blocks/section type="section" color="primary" %}}
+{{% blocks/section color="primary" %}}
 ## So what’s a technical documentation site?
 
 A technical documentation site is a website that your users can visit to find the documentation for your technical project.  Your documentation set contains all the information you think your users might need to engage with your project, from overviews that help them understand what the project is for, to instructions for specific tasks. Depending on the size of the project, a documentation set can be a page or two or an entire “book” with different types of information.
@@ -28,7 +27,7 @@ If you have users around the world, you might also want to provide your content
 Once you have your content, you use a technical documentation site to publish your technical documentation set online for your users. In addition to your documentation, your site might also contain material like contact information, a blog, or information about how to contribute to the project.
 {{% /blocks/section %}}
 
-{{% blocks/section type="section" color="white" %}}
+{{% blocks/section color="white" %}}
 ## How does Docsy help?
 
 Particularly when working with open source projects, it can be difficult to figure out how to turn all your product knowledge into a website that helps and engages your users. **Enter Docsy!**
@@ -122,16 +121,13 @@ template, or even add new behaviors. [Learn more...](/docs/updating/)
 
 Because Docsy helps you create and serve a well-organized, navigable technical documentation set, it frees you up to create and maintain great reliable, comprehensive content that your users can enjoy and trust.
 {{% /blocks/section %}}
-{{% blocks/section type="section" color="primary" %}}
+{{% blocks/section color="primary" %}}
 ## What's next for Docsy?
 
 Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better. We hope to continue to make improvements to the theme along with the Docsy community.
 
 Visit our [Issues](https://github.com/google/docsy/issues) to see what we're currently working on. If there's something you'd like to see in Docsy, please create an issue yourself - or assign yourself an issue if you'd like to fix or add something! See our [contribution guidelines](/docs/contribution-guidelines/) for more information.
 
 You can find out how to update your site to the latest version of Docsy in [Keeping the theme up to date](/docs/updating/).
+<!-- There must not be a blank line at the end of this file otherwise it creates an empty paragraph in the rendered page -->
 {{% /blocks/section %}}
-
-
-
-
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
@@ -97,7 +97,7 @@ The example below shows a section wrapping 3 feature sections.
 
 
 ```go-html-template
-{{</* blocks/section color="dark" */>}}
+{{</* blocks/section color="dark" type="row" */>}}
 {{%/* blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" */%}}
 The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
 Please follow this space for updates!
@@ -113,9 +113,9 @@ For announcement of latest features etc.
 
 | Parameter        | Default    | Description  |
 | ---------------- |------------| ------------|
-| height | | See above.
-| color | | See above.
-| type  | | Specify "section" if you want a general container,  omit this parameter if you want this section to contain a horizontal row of features.
+| `height` | | See above.
+| `color` | | See above.
+| `type`  | | Specify "container" (the default) if you want a general container, or "row" if the section will contain columns -- which must be immediate children.
 
 ### blocks/feature
 

diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml
@@ -40,6 +40,9 @@ languages:
 
 markup:
   goldmark:
+    parser:
+      attribute:
+        block: true
     renderer:
       unsafe: true
   highlight: