What is this?
Version 2 of NodeBB using the Persona theme (and many child themes based off of Persona) used Bootstrap 3 as its front-end CSS framework.
As part of the upgrade to version 3, we are upgrading to Bootstrap 5, whose migration comes with a number of updates and changes, many of which are incompatible with previous versions of Bootstrap.
Do I need this?
If your theme or child theme updates the templates folder, you will need this guide to update your templates to use Bootstrap 5 components and classes.
If your templates are based off of an older version of Persona (that is, you copied an existing template and modified it), you simply need to copy the latest template from Persona and re-apply your changes.
The main migration docs for migrating from Bootstrap 3 to 5 can be found on the Bootstrap website:
… however, they are exhaustively complete and likely contain a lot of content that does not necessarily pertain to your theme. We have distilled some of the common migration steps below for easier consumption.
In general…
pull-leftchanged tofloat-startpull-rightchanged tofloat-endtext-rightchanged totext-endimg-responsivechanged toimg-fluid
Buttons
- Vertically stacked buttons change from .btn-block to using display/spacer classes.
<div class="d-grid gap-2"> <button class="btn btn-primary" type="button">Button</button> <button class="btn btn-primary" type="button">Button</button> </div>
btn-xsremoved usebtn-smbtn-defaultremoved usebtn-outline-secondary
Grid/Breakpoints
col-xs-<n>changed tocol-<n>
Display
inline-blockchanged tod-inline-block
Media Component
… has been removed completely, use flex display classes instead:<div class="d-flex">
<div class="flex-shrink-0">
image
</div>
<div class="flex-grow-1 ms-3">
text
</div>
</div>
Navbar
navbar-togglechanged tonavbar-toggler
Panels, Wells, and Jumbotrons
… have all been removed in favour of the “card” component.
To convert a panel into a card:
<div class=”card”> <div class=”card-header”>header</div> <div class=”card-body”>body</div> <div class=”card-footer”>footer</div> </div>
<div class="well">changed to<div class="card card-body text-bg-light">
Forms
<select class="form-control">changed to<select class="form-select">- Add
form-labelclass to labels - Add
form-check-inputto checkboxes. Sample checkbox with label:
<div class="”form-check”"> <input class="”form-check-input”" type="”checkbox”" /> <label class="”form-check-label”">a checkbox</label> </div>
form-group,.form-row, or.form-inlineare removed use spacing utilitieshelp-blockchanged toform-text
Dropdowns
data-toggle="dropdown"changed todata-bs-toggle="dropdown"- Add
dropdown-itemto dropdown list item<a class="dropdown-item">Item 1</a> dropdown-menu-rightchanged todropdown-menu-end- Divider changed to
dropdown-divider
Collapse
data-toggle="collapse"changed todata-bs-toggle="collapse"data-target=".classname"changed todata-bs-target=".classname"
Modals
data-dismiss="modal"changed todata-bs-dismiss="modal"
Responsive Breakpoints
Instead of using media queries using old Bootstrap 3 variables (e.g. @media (max-width: @screen-sm-max) { ... }), Bootstrap 5 introduces a new mixin for breakpoints.
Read more about it in Bootstrap 5’s article re: responsive breakpoints.