New blog post: Upgrading to Docsy 0.7 & Bootstrap 5

userguide/.htmltest.yml

@@ -5,4 +5,6 @@ IgnoreDirectoryMissingTrailingSlash: true # FIXME
 IgnoreDirs: [_print] # FIXME
 IgnoreEmptyHref: true # FIXME
 IgnoreInternalEmptyHash: true # FIXME
-IgnoreInternalURLs:
+IgnoreInternalURLs: # list of paths
+IgnoreURLs: # list of regexs of paths or URLs to be ignored
+  - ^https://twitter.com/docsydocs$

userguide/content/en/blog/2023/bootstrap-5-migration.md

@@ -9,7 +9,7 @@ author: >
   Docsy Steering Committee
 date: 2023-06-05
 canonical_url: https://www.cncf.io/blog/2023/06/05/migrating-docsy-to-bootstrap-5/
-spelling: cSpell:ignore CNCF Chalin opentelemetry techdocs
+cSpell:ignore: CNCF Chalin opentelemetry techdocs
 ---
 
 [Docsy](https://docsy.dev), and Docsy-based project websites ([including those
@@ -85,8 +85,8 @@ This assumption wasn't apparent nor was it enforced in Bootstrap 4,
 consequently, some of Docsy's layouts failed to respect it. In
 [most cases](https://github.com/google/docsy/issues/1466), fixing violations
 consisted of simply wrapping a `.row`'s child element in a `.col`, but the
-[Docsy footer](https://github.com/google/docsy/blob/v0.7.0/layouts/partials/footer.html) required a couple of
-iterations to get right.
+[Docsy footer](https://github.com/google/docsy/blob/v0.7.0/layouts/partials/footer.html)
+required a couple of iterations to get right.
 
 My first footer adjustment reset
 [`flex-shrink`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink) to
@@ -251,8 +251,8 @@ migration that didn't apply to Docsy since Docsy uses only the most trivial of
 forms.
 
 We'll have more to share about the OTel migration effort as well as general
-project-specific migration advice in a followup blog post. In the meantime, I
-hope that you have found parts of this technical article helpful for your own
+project-specific migration advice in a [followup blog post][]. In the meantime,
+I hope that you have found parts of this technical article helpful for your own
 migration efforts.
 
 [CNCF project](https://www.cncf.io/projects/) websites eager to migrate can send
@@ -277,5 +277,6 @@ _A version of this article originally appeared as the [CNCF blog][] post
 [cncf blog]: https://www.cncf.io/blog/
 [cncf-docsy]:
   https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/
+[followup blog post]: /blog/2023/docsy-0.7/
 
 [original post]: {{% param canonical_url %}}

userguide/content/en/blog/2023/docsy-0.7.md

@@ -0,0 +1,180 @@
+---
+title: Upgrading to Docsy 0.7 & Bootstrap 5
+linkTitle: Upgrading to Docsy 0.7
+description: A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples
+author: >
+  [Patrice Chalin](https://github.com/chalin), [CNCF](https://www.cncf.io/) &
+  Docsy Steering Committee
+date: 2023-08-03
+cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy
+---
+
+Last June, Docsy celebrated a significant milestone with the release of version
+[0.7.0](https://github.com/google/docsy/releases/tag/v0.7.0). This major upgrade
+was the result of
+[six months of meticulous work (#470)](https://github.com/google/docsy/issues/470)
+focused on the migration to Bootstrap 5.2. For highlights and the rationale
+behind that journey, see
+[Migrating to Bootstrap 5.2](/blog/2023/bootstrap-5-migration/).
+
+This blog post is intended to help those who are upgrading to Docsy 0.7 and
+Bootstrap 5, based on my Docsy 0.7 upgrade experiences, specifically related to
+Bootstrap. The post starts with general guidance for Docsy-based projects
+wishing to upgrade. Every project's migration experience will be unique, but
+hopefully this post, and the two included case studies, will make your upgrade
+process easier and faster.
+
+If you're here, you probably want to upgrade your Docsy-based project---so,
+let's jump in!
+
+## Upgrading your project
+
+As was mentioned in the
+[first post](/blog/2023/bootstrap-5-migration/#migrating-docsy-based-projects),
+each project uses its own specific set of Bootstrap and Docsy features, so in
+all likelihood, **your upgrade journey will be unique**. This section offers
+some general guidance.
+
+### Upgrade Docsy
+
+If you haven't already, upgrade your project all the way up to Docsy 0.6 first.
+Each release of Docsy can bring its own set of upgrade challenges that will vary
+in size and effort depending on your project and the features it uses, as well
+as how long it's been since your version of Docsy has been upgraded. You'll want
+to get all pre-0.7 upgrade issues out of the way so that you can focus on
+Bootstrap 5 issues. Once you are done, upgrade to the latest Docsy 0.7.x
+release.
+
+### Address Bootstrap changes
+
+I recommend that you first walk through the Bootstrap 5.2
+[migration page](https://getbootstrap.com/docs/5.2/migration/) to get an
+appreciation of the scope of the changes made to Bootstrap 5 relative to 4.
+Identify the breaking changes to those Bootstrap features used by your project,
+and address each individually. I mention a few breaking changes next and close
+the section with a comment about what to do about the rest.
+
+Some Bootstrap changes will break your website's layout or functionality in
+obvious ways. This is the case for the
+[rename](https://getbootstrap.com/docs/5.2/migration/#utilities)[ of utility classes](https://getbootstrap.com/docs/5.2/migration/#utilities),
+like `ml-1` and `pr-2`. Using regular-expression based search-and-replace over
+your project's custom layouts or doc-page inline HTML is a good way to tackle
+this. I've used regex like these:
+
+- Margin and padding: `\b([mp])[lr](-([0-5]|auto))\b`
+- Left/right classes: `\b((float|border|rounded|text)-)(left|right)\b`
+
+If your project uses Bootstrap
+[JavaScript plugins](https://getbootstrap.com/docs/5.2/migration/#javascript)
+such as dropdowns, popovers, and tooltips, these will stop working until you
+adjust data attribute names, which are now "namespaced" using the `data-bs`
+prefix. For example, use `data-bs-toggle` instead of `data-toggle`.
+
+Other Bootstrap breaking changes will require more work to address, such as the
+following that were mentioned in the
+[TL;DR](/blog/2023/bootstrap-5-migration/#tldr) of the first post:
+
+- [Mixin `media-breakpoint-down()` argument shift](/blog/2023/bootstrap-5-migration/#mixin-media-breakpoint-down-argument-shift)
+- [Grid `.row` and `.col` style changes](/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking)
+- [Import ordering of Bootstrap Sass files: functions first](/blog/2023/bootstrap-5-migration/#import-ordering-of-bootstrap-sass-files-functions-first)
+
+The Docsy blog layout used the `.media` class, which was
+[dropped from Bootstrap 5](https://getbootstrap.com/docs/5.2/migration/#grid-updates).
+This, and the
+[`.row` and `.col` style changes](/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking),
+required a couple of iterated changes to the blog layouts, such as
+[PR #1566](https://github.com/google/docsy/pull/1566). If your project
+customizes blog layouts, then you'll want to walk through the updates carefully.
+Otherwise, your project will get these updates automatically, without any
+further required changes.
+
+Should you encounter a Bootstrap-5 breaking change affecting your project that
+hasn't been mentioned above, you might find the opening comment of Docsy
+[issue #470 · Upgrade to Bootstrap 5.2](https://github.com/google/docsy/issues/470)
+useful: it lists 50 tasks, each addressing a distinct migration problem,
+accompanied by notes or cross-referenced PRs that illustrate how each problem
+was resolved.
+
+### Address Docsy-specific changes
+
+It is worth mentioning in passing some of the main Docsy 0.7 changes that aren't
+related to Bootstrap, such as:
+
+- Default and accepted values of the `blocks/section`'s `type` argument have
+  changed ([#1472](https://github.com/google/docsy/issues/1472))
+- Pre-Hugo-0.54.x behavior of `{{%/* */%}}` is no longer supported
+  ([#939](https://github.com/google/docsy/issues/939))
+- [Hugo release](https://github.com/gohugoio/hugo/releases) 0.110.0 or later is
+  required
+
+For the complete list of changes, see the
+[CHANGELOG at 0.7.0](https://github.com/google/docsy/blob/main/CHANGELOG.md#070).
+
+## Case studies
+
+Our two case study projects to illustrate the Docsy upgrade process are the
+OpenTelemetry project and the Docsy example template repository.
+
+### opentelemetry.io
+
+[Several CNCF projects](https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/)
+use the Docsy theme, including [opentelemetry.io](https://opentelemetry.io/),
+which I used as a Docsy pre-release test site. As suggested earlier, I first
+upgraded Docsy from 0.4 to 0.6
+([opentelemetry.io issue #2419](https://github.com/open-telemetry/opentelemetry.io/issues/2419)).
+
+The upgrade to Docsy 0.7 went
+[fairly smoothly](https://github.com/open-telemetry/opentelemetry.io/issues?q=label%3Adocsy+is%3Aclosed+closed%3A%3E2023-03-03).
+In addition to addressing the "obvious changes" related to utility class renames
+and data-attribute namespacing, the OTel website required these project-specific
+changes:
+
+- [Breaking changes to](https://getbootstrap.com/docs/5.2/migration/#forms)
+  [forms](https://getbootstrap.com/docs/5.2/migration/#forms) required a
+  significant rework of the
+  [Registry](https://opentelemetry.io/ecosystem/registry/) form
+- While the OTel website has no blog layout overrides, it made use of the
+  `.media` class (which was dropped) for registry entries. Flex styles were used
+  instead.
+
+That's it! To see how both of the above were resolved, see OTel
+[PR #2490](https://github.com/open-telemetry/opentelemetry.io/pull/2490).
+
+### Docsy-example
+
+The [docsy-example](https://github.com/google/docsy-example) repository is a
+[GitHub template](https://gitprotect.io/blog/how-to-use-github-repository-templates/)
+that we suggest as a possible starting point for users looking to adopt
+[Docsy for a new website](/docs/get-started/docsy-as-module/example-site-as-template/).
+The example site features [multi-language support](/docs/language/), which had
+an impact on the required upgrades.
+
+The example-site upgrade was even simpler than for the OTel website. The key
+changes ([PR #221](https://github.com/google/docsy-example/pull/221)) were
+mainly confined to the landing page of each natural language:
+
+- Utility-class renames, such as `.ml-*` and `.mr-*` to `.ms-*` and `.me-*`
+- [blocks/section](/docs/adding-content/shortcodes/#blockssection) changes
+  ([PR #1472](https://github.com/google/docsy/pull/1472)):
+  - Language landing pages had to be renamed from `.html` to `.md` in support of
+    using blocks shortcodes to render markdown content
+  - Switched to `type="row"` for `blocks/section` elements that are rows (also
+    from [PR #220](https://github.com/google/docsy-example/pull/220))
+
+That was it.
+
+## What next?
+
+If your project doesn't override any Docsy layouts, then your upgrade experience
+should be relatively straightforward. Reviewing layout file changes, on the
+other hand, always warrants special attention.
+
+With the tips shared here, I hope that your journey to Docsy 0.7 will be more
+streamlined. Consider sharing your experiences by adding a comment to the
+[discussion of 0.7.0](https://github.com/google/docsy/discussions/1555) or any
+[later 0.7.x release](https://github.com/google/docsy/discussions/categories/announcement?discussions_q%3Dis%253Aopen%2Bcategory%253AAnnouncement).
+Wishing you a successful upgrade journey!
+
+A special thanks to [Erin McKean](https://github.com/emckean) for detailed and
+valuable feedback on this post, and to all who contributed to the 0.7.x releases
+of Docsy and the Docsy example!