oetterer · malberts · Jul 17, 2026 · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git a/README.md b/README.md
@@ -29,8 +29,9 @@ configuration it can add a new [gallery][Gallery] mode, and replace normal
 
 Please also see the [known issues][known-issues] section.
 
-There is also a [migration guide](docs/migration-guide.md) for users switching
-from bootstrap3 (BootstrapComponents ~1.2) to bootstrap4 (BootstrapComponents ~4.0).
+There are also migration guides for users switching
+to [Bootstrap 5](docs/migration-guide-bs5.md) (Bootstrap Components ~6.0) and
+to [Bootstrap 4](docs/migration-guide-bs4.md) (Bootstrap Components ~4.0 and ~5.0).
 
 ## Contact
 For bug reports and feature requests, please see if it is already reported on

diff --git a/docs/migration-guide-bs4.md b/docs/migration-guide-bs4.md
@@ -0,0 +1,65 @@
+## Migration Guide: Bootstrap 3 to 4
+
+There have been some changes between versions ~1.0 and ~4.0. Foremost is that
+the new BootstrapComponents utilizes Twitter Bootstrap4. Therefore, it mirrors
+changes made by Bootstrap.
+
+Also, extension loading must now be done manually in your LocalSettings, no
+matter whether you installed it via composer or manually.
+
+### Changes in extension loading
+BootstrapComponents now has to loaded manually, whether you installed it
+via composer or by cloning it from github. Just add the following to
+your `LocalSettings.php` file:
+
+```
+wfLoadExtension( 'BootstrapComponents' );
+```
+
+### Changes in Components
+There have been some changes in the components provided by Bootstrap4 and
+the ExtensionBootstrap. Some of them unfortunately need your attention.
+
+#### Icon
+This is the change with the severest impact: the glyphicon font has been
+removed. BootstrapComponents unfortunately cannot provide a suitable
+replacement. If you need fancy items, please have a look at
+[Extension:FontAwesome][FontAwesome].
+
+#### Label
+The Label component has been removed, its functionality is now provided
+by the Badge Component. **BootstrapComponents takes care of that** by
+having the label component inside your wiki text rendered with
+bootstrap4's badge attributes and classes.
+
+In other words, you can use these two elements in your wiki and
+they both produce the same output:
+```html
+{{#bootstrap_label: text | .. }}
+{{#bootstrap_badge: text | .. }}
+```
+
+However, it is recommended that on new pages or new edits you now only
+use the badge component.
+
+#### Panel and Well
+Bootstrap4 removes the Panel and the Well and introduces the new
+component Card. Since "Bootstrap’s cards provide a flexible
+and extensible content container with multiple variants and options."
+it can be used to render things to look like Panels and Wells.
+Again, **BootstrapComponents takes care of that** by rendering
+a Well and a Panel like a Bootstrap4 Card.
+
+Subsequently, these calls all produce the same output:
+```html
+<bootstrap_card [..]>Content text for the box</bootstrap_card>
+<bootstrap_panel [..]>Content text for the box</bootstrap_panel>
+<bootstrap_well [..]>Content text for the box</bootstrap_well>
+```
+
+This includes panels inside accordions, as well.
+
+Again, it is recommended that on new pages or new edits you now only
+use the card component.
+
+[FontAwesome]: https://www.mediawiki.org/wiki/Extension:FontAwesome
diff --git a/docs/migration-guide-bs5.md b/docs/migration-guide-bs5.md
@@ -0,0 +1,78 @@
+## Migration Guide: Bootstrap 4 to 5
+
+Bootstrap Components 6.0 moves the underlying framework from Bootstrap 4
+to Bootstrap 5.3. All components keep their wikitext syntax: no parser
+function or tag was removed or renamed, and existing pages keep parsing
+as before. What needs attention is everything a wiki builds around the
+emitted markup.
+
+### New requirements
+
+* MediaWiki 1.43 or later
+* PHP 8.1 or later
+* Bootstrap extension 6.x, which bundles the Bootstrap 5.3 library
+
+Upgrade the Bootstrap extension together with Bootstrap Components; the
+two versions belong together.
+
+### Jumbotron
+
+Bootstrap 5 removed the `.jumbotron` component.
+**Bootstrap Components takes care of that** by rebuilding the component
+from [utility classes][BS5-jumbotron] (`p-5 mb-4 bg-body-tertiary
+rounded-3`), so existing jumbotrons keep working. Expect slight visual
+differences, and note that custom CSS targeting `.jumbotron` no longer
+matches anything.
+
+### Custom CSS targeting emitted markup
+
+Bootstrap 5 renamed classes and restructured some components, and the
+markup this extension emits changed accordingly. Rules in
+`MediaWiki:Common.css` (or skin CSS) written against the old output
+need review. The changes most likely to matter:
+
+| Emitted before | Emitted now |
+| -------------- | ----------- |
+| `close` (alert and modal close button) | `btn-close` |
+| `badge-{color}` | `text-bg-{color}` |
+| `badge-pill` | `rounded-pill` |
+| `jumbotron` | `p-5 mb-4 bg-body-tertiary rounded-3` |
+| carousel indicators as `<ol>`/`<li>` | `<button>` elements |
+
+### Hand-written Bootstrap HTML in templates
+
+Bootstrap 5 only reacts to `data-bs-*` attributes. This extension
+renamed the attributes it emits, but raw Bootstrap 4 snippets pasted
+into templates or pages are the wiki's responsibility and need the same
+rename: `data-toggle` becomes `data-bs-toggle`, and likewise for
+`data-target`, `data-dismiss`, `data-ride`, `data-slide`,
+`data-slide-to`, `data-parent`, `data-placement`, `data-content`, and
+`data-trigger`.
+
+### Gadgets and site JavaScript
+
+The extension now initializes its components through the native
+Bootstrap 5 API instead of jQuery plugins. Bootstrap 5 still registers
+its jQuery plugin interface when jQuery is present (which is always the
+case in MediaWiki), so existing gadget code along the lines of
+`$( '#myModal' ).modal( 'show' )` generally keeps working. New code
+should use the native API, e.g.
+`bootstrap.Modal.getOrCreateInstance( element ).show()`.
+
+### Customized SCSS variables
+
+If your wiki customizes Bootstrap through SCSS variable overrides via
+the Bootstrap extension, review the variable names: Bootstrap 5 renamed
+and removed a number of them. See the [Bootstrap 5 migration
+notes][BS5-migration] for the authoritative list.
+
+### After the upgrade
+
+Pages rendered before the upgrade still carry Bootstrap 4 markup in the
+parser cache while the wiki already serves Bootstrap 5 CSS and
+JavaScript, so components on cached pages can look broken. This
+resolves as pages re-render; to force it, purge the affected pages or
+run the `purgeParserCache` maintenance script.
+
+[BS5-jumbotron]: https://getbootstrap.com/docs/5.3/examples/jumbotron/
+[BS5-migration]: https://getbootstrap.com/docs/5.3/migration/
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
@@ -1,63 +1,6 @@
 ## Migration Guide
 
-There have been some changes between versions ~1.0 and ~4.0. Foremost is that
-the new BootstrapComponents utilizes Twitter Bootstrap4. Therefore, it mirrors
-changes made by Bootstrap.
+The migration guide is split into one document per upgrade:
 
-Also, extension loading must now be done manually in your LocalSettings, no
-matter whether you installed it via composer or manually.
-
-### Changes in extension loading
-BootstrapComponents now has to loaded manually, whether you installed it
-via composer or by cloning it from github. Just add the following to
-your `LocalSettings.php` file:
-
-```
-wfLoadExtension( 'BootstrapComponents' );
-```
-
-### Changes in Components
-There have been some changes in the components provided by Bootstrap4 and
-the ExtensionBootstrap. Some of them unfortunately need your attention.
-
-#### Icon
-This is the change with the severest impact: the glyphicon font has been
-removed. BootstrapComponents unfortunately cannot provide a suitable
-replacement. If you need fancy items, please have a look at
-[Extension:FontAwesome][FontAwesome].
-
-#### Label
-The Label component has been removed, its functionality is now provided
-by the Badge Component. **BootstrapComponents takes care of that** by
-having the label component inside your wiki text rendered with
-bootstrap4's badge attributes and classes.
-
-In other words, you can use these two elements in your wiki and
-they both produce the same output:
-```html
-{{#bootstrap_label: text | .. }}
-{{#bootstrap_badge: text | .. }}
-```
-
-However, it is recommended that on new pages or new edits you now only
-use the badge component.
-
-#### Panel and Well
-Bootstrap4 removes the Panel and the Well and introduces the new
-component Card. Since "Bootstrap’s cards provide a flexible
-and extensible content container with multiple variants and options."
-it can be used to render things to look like Panels and Wells.
-Again, **BootstrapComponents takes care of that** by rendering
-a Well and a Panel like a Bootstrap4 Card.
-
-Subsequently, these calls all produce the same output:
-```html
-<bootstrap_card [..]>Content text for the box</bootstrap_card>
-<bootstrap_panel [..]>Content text for the box</bootstrap_panel>
-<bootstrap_well [..]>Content text for the box</bootstrap_well>
-```
-
-This includes panels inside accordions, as well.
-
-Again, it is recommended that on new pages or new edits you now only
-use the card component.
+* [Bootstrap 4 to 5](migration-guide-bs5.md) — upgrading to Bootstrap Components ~6.0
+* [Bootstrap 3 to 4](migration-guide-bs4.md) — upgrading to Bootstrap Components ~4.0 and ~5.0
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -1,5 +1,13 @@
 ## Release Notes
 
+### BootstrapComponents 6.0.1
+
+Released on TBD
+
+Changes:
+* add a migration guide for the Bootstrap 4 to 5 upgrade
+* split the migration guide into one document per upgrade and link both guides from the README
+
 ### BootstrapComponents 6.0.0
 
 Released on 16-July-2026
@@ -14,6 +22,8 @@ Changes:
 * rewrite component JavaScript from jQuery to the native Bootstrap 5 API
 * reimplement the jumbotron using Bootstrap 5 utility classes, since Bootstrap 5 removed the .jumbotron component
 
+See the [migration guide](migration-guide-bs5.md) when upgrading from 5.x.
+
 ### BootstrapComponents 5.2.4
 
 Released on 22-May-2026
@@ -168,7 +178,7 @@ Fixes:
 * fixed some typos
 * fix component popover header handling
 
-Also see the [migration guide](migration-guide.md) when switching to ~4.0.
+Also see the [migration guide](migration-guide-bs4.md) when switching to ~4.0.
 
 ### BootstrapComponents 1.2.4