Upgrade to Bootstrap 5.2

[LisaFC]

Bootstrap 5 has some changes that seem to break Docsy site builds #304 #464.

---

(Edit: @chalin)

Info: the last BSv4 build

A link to the last edition of the User Guide that was build with BSv4: https://deploy-preview-1356--docsydocs.netlify.app. This link was taken from the last PR/commit of v0.6.x.

Prep

• [x] #1193
  • [x] #1481
• [x] #1454
• [x] #1458

Tasks

All of the section headings below that are hyperlinks, link to a section of the Bootstrap 5.2 migration guide of the corresponding name. A GitHub user name on a section or subsection heading declares that person as taking responsibility for making the corresponding changes to Docsy.

✅ Dependencies - @chalin

• BS dropped jQuery, but it is still used if present. We'll handle this later via

  1436

• [x] Upgrade to Popper v2 is done automatically thanks to https://github.com/google/docsy/pull/1268
• [x] #1372
• [x] #1374

✅ Sass - @chalin

• [x] Renamed color-yiq() function and related variables to color-contrast(), etc. For details, see corresponding Sass entry:
  • [x] #517
  • [x] #1363
• [x] ⚠️ media-breakpoint-down() change argument to be next breakpoint of higher value

  1367

  Projects will have to make a similar change to their styles.

• $enable-print-styles N/A
• color() etc. N/A
• color-level etc. N/A
• reduced-motion etc. N/A
• Gradient related changes: bg-gradient-variant() is gone, etc.
  • [x] #1369
• Removed previously deprecated mixins. N/A
• scale-color N/A
• No other change is applicable to Docsy.

Customization:

• [x] #1462

✅ Color system - @chalin

While I used to think that Color system changes were optional, I've since changed my mind. IMHO, without #1388 we would have gotten weird behavior. For details see the issue's opening comment.

• [x] #1384
• [x] ⚠️ #1388 This change only needs to be done by Docsy, not projects using Docsy.
• [x] #1406
• (👀 Might be worth it later to look at the new tints & shades, and the improvements in color contrast.)

✅ Grid updates - @chalin

• Renamed .no-gutters N/A
• Columns no longer have position: relative applied ...
  • [x] #1479
  • [x] #1571
• Dropped several .order-* classes that often went unused (beyond 5 it seems). N/A
• Dropped the .media component. Regex: \b(^|[^@])media($|[^-])
  • [x] #1560
• No other change from this section of the migration guide is applicable to Docsy.

⚠️ The following isn't mentioned in the migration guide. Formatting of rows and columns has changed! For details, and related fixes, see:

• [x] #1466

✅ Content, Reboot, etc - @chalin

• [x] display-* typography has changed (this is why the "Welcome to Docsy" on the homepage looks so different). $display* variables have been replaced.
  • [x] #1459
• No other changes necessary AFAICT.

Table styles have changed. For details, see #1473.

• [x] #1473
• [x] #1476

⏭️ RTL - @chalin

• [x] Drop current RTL support, since it's incompatible with BSv5: #1443

• 1442

✅ Forms

Docsy's only use of form elements is for search, and it's a very minimal. Docsy doesn't use any of the form-specific classes that were deprecated.

✅ Components

• Accordion: future versions of docsy will support accordions - #1391 is ready for review @chalin @deining
  • Post-migration, the following will be addressed: - #1369.
• Alerts - no changes necessary, but it'll be worth looking into the support for icons. @chalin
• Badges - @chalin
  • [x] #1452
• Breadcrumbs
  • [x] #1414
  • (Try new CSS custom property --bs-breadcrumb-divider for easy customization)
• Buttons - @chalin
  • Toggle buttons - N/A
  • Etc - N/A
• Card - @deining
  • [x] #1375
• Carousel - N/A @chalin
• Close button - N/A @chalin
• Collapse - N/A @chalin
• Dropdowns @deining @chalin
  • [x] #1381
  • [x] Dropdowns now support .dropdown-items wrapped in <li>s -

    1415

• Jumbotron - N/A @chalin
• List group - N/A @chalin
• Navs and tabs - N/A @chalin
• Navbars @chalin
  • [x] Navbars now require a container within - #1422
  • The .active class can no longer be applied to .nav-item - N/A
• Offcanvas - N/A @chalin
• Pagination - N/A since Docsy doesn't currently use BS pagination, but maybe it should (#1423) @chalin
• Popovers @chalin
  • [x] Renamed .arrow to .popover-arrow - #1427
  • [x] #1425 - thank you to @tekezo for the fix!
  • JS code updates (to enable & configure) will be handled later: #1436
• Spinners - N/A @chalin
• Toasts - N/A @chalin
• [x] Tooltips
  • [x] #1382
  • [x] #1407
  • JS code updates (to enable & configure) will be handled later: #1436

✅ Utilities - @chalin

• [x] Renamed .float-left and .float-right to .float-start and .float-end - #1361
• [x] Renamed .ml- and .mr- to .ms- and .me-:
  • [x] #517 - commit 4ba35a1fa5ccd1e4a381d8f6cd1221d803d97491
  • [x] #1361
• [x] Renamed .pl- and .pr- to .ps- and .pe- - #1361
• [x] Renamed .text-left and .text-right to .text-start and .text-end:
  • [x] #1361
  • [x] #1364
• No other change is applicable to Docsy.

Regex:

• Margin and padding: \b([mp])[lr](-([0-5]|auto))\b
• Left/right classes: \b((float|border|rounded|text)-)(left|right)\b

✅ Helpers - @chalin

• No changes necessary AFAICT.

✅ JavaScript

• BS dropped jQuery, but since this isn't essential for completing the migration to BSv5, we'll handle it after: #1436
  • Initialization / configuration and use of components will be impacted.
• Data attributes for all JavaScript plugins are now namespaced. This was addresses along with other changes, e.g.:
  • [x] #1368
  • [x] #1382

Other

• [x] #1383
• [x] #1447
  • [x] #1548
• [x] #1489

Post-upgrade checks / changes

• See #1510

[bwklein]

Suggestion: Use Tailwind CSS instead. 😄

[kinti]

Is not Docsy only, its all themes..., is all..., in netlify

[LisaFC]

Hmm, didn't realize how many things it wasn't compatible with. :( I'll see if I can find any more general Hugo/Netlify bootstrap 5 issues.

[glasnt]

I took a look, and after bumping bootstrap from v4-dev to main, I was able to replicate the issues others had found with errors, and found it was related to color-yiq being renamed... which was already found in https://github.com/google/docsy/pull/517 :)

As they found, there are other small UX differences that are visible just in the user guide. See a dynamic view of the 517 Netlify preview for comparison

The Bootstrap migration guide should help with a lot of these https://getbootstrap.com/docs/5.0/migration/.

I'm not 100% across this project, testing wise, how you enumerate all the customisations your theme has, etc.

[chalin]

Extra incentive to schedule migration to v5 before year's end:

• v4 critical support ends: 2022/11
• v4 EOL: 2023/01

Sources:

• https://blog.getbootstrap.com/2022/07/19/bootstrap-4-6-2/
• https://endoflife.date/bootstrap

/cc @geriom @emckean

[LisaFC]

Name changed so we can use this to track actually making the necessary update.

[chalin]

Thanks @LisaFC. FYI, I've set the milestone to Q3 :).

[chalin]

Moved to 22Q4. Given the deadlines we're facing re. BS v4 EOL, we really should schedule this work to happen soon:

Extra incentive to schedule migration to v5 before year's end:

• v4 critical support ends: 2022/11
• v4 EOL: 2023/01

[chalin]

I've updated the title to reflect that this is an upgrade to v5 that stops at 5.2. I was hoping to pickup 5.3, but it is still in alpha, and I don't want to delay a release of Docsy any longer.

Other updates make to this issue:

• Forms-migration requirements checks have been completed
• Card-pane update rebased, conflict-resolved and merged - #1376

I've created a followup meta issue to track the key changes we'll want to make after this issue is closed:

• 1510