[BSv5] blocks/section row-col hierarchy fix (#1472)

google · Mar 9, 2023 · e1b0f62 · e1b0f62
1 parent 01eafd3
commit e1b0f62
Show file tree

Hide file tree

Showing 13 changed files with 98 additions and 99 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,24 +14,35 @@ 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].
+- **Shortcodes**:
+  - Now using Hugo's native support for processing HTML & markdown, not file
+    extension testing. ([#906])
+  - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939])
+  - `blocks/section`: **default** and accepted values of the `type` argument
+    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
+[#906]: https://github.com/google/docsy/issues/906
+[#939]: https://github.com/google/docsy/issues/939
 [#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][]
@@ -45,9 +56,9 @@ Bootstrap version. See [the announcement][bs-announcement] for more information.
 **New**:
 
 - **Simplified use of mermaid diagrams**: when using a `mermaid` code block on
-  your page, mermaid is now automatically enabled (needs hugo version >= 0.93.0).
-  For existing sites build with hugo 0.93.0+, parameter `mermaid.enable`
-  can be removed from site config.
+  your page, mermaid is now automatically enabled (needs hugo version >=
+  0.93.0). For existing sites build with hugo 0.93.0+, parameter
+  `mermaid.enable` can be removed from site config.
 
 - **Add render hook for chem code blocks**: add auto-activation of `math` and
   `chem` blocks via KateX and mhchem. Support for formula rendering activation
@@ -69,11 +80,12 @@ notes][0.5.1]. **BREAKING CHANGES** are documented below.
 
 **Breaking changes**:
 
-- **Tabbed panes, text display**. By default, the content of a tab inside a tabbed
-  pane is shown as code. As of version 0.4 of the shortcode, you can add the
-  parameter `code=false` to your `tabpane` or `tab` shortcode  in order to render
-  tab content(s) as text (markdown or html). As of version 0.5 the name of this
-  parameter was changed, we now use `text=true` in order to mark content as text.
+- **Tabbed panes, text display**. By default, the content of a tab inside a
+  tabbed pane is shown as code. As of version 0.4 of the shortcode, you can add
+  the parameter `code=false` to your `tabpane` or `tab` shortcode in order to
+  render tab content(s) as text (markdown or html). As of version 0.5 the name
+  of this parameter was changed, we now use `text=true` in order to mark content
+  as text.
 - **Display logo by default**. Most projects show their logo in the navbar. In
   support of this majority, Docsy now displays a logo by default. For details on
   how to hide the logo (or your brand name), see [Styling your project logo and
@@ -93,7 +105,8 @@ notes][0.5.1]. **BREAKING CHANGES** are documented below.
 - By default, Docsy now uses the [gtag.js][] analytics library for all site
   tags. For details, see [Adding Analytics > Setup][].
 
-[Adding Analytics > Setup]: https://www.docsy.dev/docs/adding-content/feedback/#setup
+[adding analytics > setup]:
+  https://www.docsy.dev/docs/adding-content/feedback/#setup
 [v4.6.2 release notes]: https://github.com/twbs/bootstrap/releases/tag/v4.6.2
 [docsy as an npm package]:
   https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
@@ -125,31 +138,31 @@ Docsy now fetches Bootstrap and FontAwesome as NPM packages rather than git
 submodules. This has an impact on your project-build setup. To migrate your
 site, follow these steps (execute commands from your project's root directory):
 
-  1.  Delete obsolete Docsy Git submodules:
-      ```console
-      $ rm -Rf themes/docsy/assets/vendor
-      ```
-  2.  Get Docsy dependencies:
-      ```console
-      $ (cd themes/docsy && npm install)
-      ```
-  3.  Update your build scripts to fetch Docsy dependencies automatically. For
-      example, if your site build uses NPM scripts, consider getting Docsy
-      dependencies via a [prepare][] script as follows:
-      ```json
-      {
-        "name": "my-website",
-        "scripts": {
-          "prepare": "cd themes/docsy && npm install",
-          "...": "..."
-        },
+1.  Delete obsolete Docsy Git submodules:
+    ```console
+    $ rm -Rf themes/docsy/assets/vendor
+    ```
+2.  Get Docsy dependencies:
+    ```console
+    $ (cd themes/docsy && npm install)
+    ```
+3.  Update your build scripts to fetch Docsy dependencies automatically. For
+    example, if your site build uses NPM scripts, consider getting Docsy
+    dependencies via a [prepare][] script as follows:
+    ```json
+    {
+      "name": "my-website",
+      "scripts": {
+        "prepare": "cd themes/docsy && npm install",
         "...": "..."
-      }
-      ```
-  4.  (Optional) Build script cleanup. If your project uses Docsy as a git
-      submodule, Docsy updates no longer require the `--recursive` flag when
-      running `git submodule update`. Consider dropping the flag if you have no
-      other recursive git submodules.
+      },
+      "...": "..."
+    }
+    ```
+4.  (Optional) Build script cleanup. If your project uses Docsy as a git
+    submodule, Docsy updates no longer require the `--recursive` flag when
+    running `git submodule update`. Consider dropping the flag if you have no
+    other recursive git submodules.
 
 Proceed as usual to build or serve your site.
 

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: