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

• Blog layout: streamline and fix styling RSS button #1193
  • [BSv5] Blog RSS button hover color is white on white #1481
• Reformat SCSS sources using Prettier #1454
• Delete duplicate mixin definitions #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
  Drop jQuery #1436
• Upgrade to Popper v2 is done automatically thanks to Scripts: get Popper from Bootstrap bundle #1268
• [BSv5] Docsy depencendies: bump _rfs.scss to bootstrap version 5.2.3 #1372
• [BSv5]: make docsy point to latest version of dependencies #1374

✅ Sass - @chalin

• Renamed color-yiq() function and related variables to color-contrast(), etc. For details, see corresponding Sass entry:
  • Update to Bootstrap v5: initial work #517
  • [BSv5] YIQ color - final changes #1363
• ⚠️ media-breakpoint-down() change argument to be next breakpoint of higher value
  [BSv5] Adjust media-breakpoint-down() argument #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.
  • [BSv5] Drop bg-gradient-variant() mixin #1369
• Removed previously deprecated mixins. N/A
• scale-color N/A
• No other change is applicable to Docsy.

Customization:

• [BSv5] Docsy variables cleanup and BS version test #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.

• [BSv5] replace lighten() by tint-color(), and var/func clean up #1384
• ⚠️ [BSv5] Fix SCSS functions import issue, and replace darken() #1388
  This change only needs to be done by Docsy, not projects using Docsy.
• [BSv5] UG's community page has color issues #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 ...
  • [BSv5] Blog RSS button is flush right #1479
  • [BSv5] Blog posts page has layout issues #1571
• Dropped several .order-* classes that often went unused (beyond 5 it seems). N/A
• Dropped the .media component. Regex: \b(^|[^@])media($|[^-])
  • [BSv5] Replace media styles with flex equivalents #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:

• [BSv5] Row/col formatting breaks Docsy components #1466

✅ Content, Reboot, etc - @chalin

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

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

• [BSv5] Table widths should be the same as all doc page content #1473
• [BSv5] Ensure tables are responsive by default #1476

⏭️ RTL - @chalin

• Drop current RTL support, since it's incompatible with BSv5: [BSv5] Drop import of rtl/main #1443
• Reintroduce RTL support using BSv5 RTLCSS #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 - Adding shortcode for accordion component (Bootstrap 5) #1391 is ready for review @chalin @deining
  • Post-migration, the following will be addressed: - [BSv5] Drop bg-gradient-variant() mixin #1369.
• Alerts - no changes necessary, but it'll be worth looking into the support for icons. @chalin
• Badges - @chalin
  • [BSv5] Drop redundant setting of BS $enable-rounded variable #1452
• Breadcrumbs
  • [BS5] Breadcrumbs: active-breadcrumb fix #1414
  • (Try new CSS custom property --bs-breadcrumb-divider for easy customization)
• Buttons - @chalin
  • Toggle buttons - N/A
  • Etc - N/A
• Card - @deining
  • [BSv5] Card groups are not rendered properly any more #1375
• Carousel - N/A @chalin
• Close button - N/A @chalin
• Collapse - N/A @chalin
• Dropdowns @deining @chalin
  • [BSv5] Dropdown for language selection fails #1381
  • Dropdowns now support .dropdown-items wrapped in <li>s -
    [BS5] Adjust HTML of dropdowns for version and lang #1415
• Jumbotron - N/A @chalin
• List group - N/A @chalin
• Navs and tabs - N/A @chalin
• Navbars @chalin
  • Navbars now require a container within - [BSv5] Navbar: add inner container + cleanup #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 (Consider using Bootstrap pagination support #1423) @chalin
• Popovers @chalin
  • Renamed .arrow to .popover-arrow - [BSv5] Offline-search adjust arrow class name #1427
  • Offline search no longer works under Bootstrap v5 #1425 - thank you to @tekezo for the fix!
  • JS code updates (to enable & configure) will be handled later: Drop jQuery #1436
• Spinners - N/A @chalin
• Toasts - N/A @chalin
• Tooltips
  • [BSv5][JS]: fix dropdowns and more #1382
  • [BSv5] Drop invalid and unnecessary tooltip attribute #1407
  • JS code updates (to enable & configure) will be handled later: Drop jQuery #1436

✅ Utilities - @chalin

• Renamed .float-left and .float-right to .float-start and .float-end - [BSv5] More utility updates #1361
• Renamed .ml-* and .mr-* to .ms-* and .me-*:
  • Update to Bootstrap v5: initial work #517 - commit 4ba35a1
  • [BSv5] More utility updates #1361
• Renamed .pl-* and .pr-* to .ps-* and .pe-* - [BSv5] More utility updates #1361
• Renamed .text-left and .text-right to .text-start and .text-end:
  • [BSv5] More utility updates #1361
  • [BSv5] Footer updates are necessary #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: Drop jQuery #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.:
  • [BSv5] Tab panes are not working properly any more #1368
  • [BSv5][JS]: fix dropdowns and more #1382

Other

• Delete bootstrap5 branch? #1383
• [BSv5] Refactor Click-to-copy #1447
  • Click-to-copy button adds extra vertical space to top of code-block #1548
• home page is showing horizontal scroller at bottom of site #1489

Post-upgrade checks / changes

• See BSv5.2 upgrade followup #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 #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 - [BSv5] Adapt cardpane shortcode #1376

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

• BSv5.2 upgrade followup #1510