Migrate from v4 to v5

Django Baton v5 – Upgrade Guide

Django Baton v5 is almost here — it's a major update and includes breaking changes.

Django Baton v5 is optimized for Django >= 5.x. It should also work with older versions of Django, but some styles may appear inconsistent or not be applied correctly.

Let’s put it this way: during the complete restyling and refactoring, we only tested it with Django >= 5.0.

The JavaScript part remains mostly unchanged, so we don’t expect issues there. However, the styling may present problems, as recent Django versions have introduced changes to the HTML.

---

🔧 Migration Instructions

To migrate your existing Baton installation, follow these steps:

1. Update admin/base_site.html

If you have overridden the admin/base_site.html template, you need to add the code that loads Google Material Symbols:

Click to expand the full template

{% extends "admin/base.html" %}
{% load static baton_tags %}
{% load i18n %}

{% block title %}
    {% if subtitle %}{{ subtitle }} |{% endif %}
    {{ title }} | {{ site_title|default:_("Django site admin") }}
{% endblock title %}

{% block extrahead %}
    {{ block.super }}
    {% baton_config as conf %}
    {{ conf | json_script:"baton-config" }}
    <script charset="utf-8">
        (function () {
            // Immediately set the theme mode to avoid flashes
            var systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
            var theme = JSON.parse(document.getElementById('baton-config').textContent).forceTheme 
                || localStorage.getItem('baton-theme') 
                || (systemTheme.matches ? 'dark' : 'light');
            document.getElementsByTagName('html')[0].setAttribute('data-bs-theme', theme);
        })()
    </script>
    <meta content="width=device-width, initial-scale=1.0" name="viewport" />
    <link rel="preload" href="https://fonts.gstatic.com/s/materialsymbolsoutlined/v247/kJEhBvYX7BgnkSrUwT8OhrdQw4oELdPIeeII9v6oFsI.woff2" as="font" type="font/woff2" crossorigin>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
    <style>
    .material-symbols-outlined {
        font-size: 22px;
        line-height: 0;
        vertical-align: middle;
        font-variation-settings:
        'FILL' 0,
        'wght' 400,
        'GRAD' 0,
        'opsz' 24;
    }
    .material-symbols-outlined:hover {
        text-decoration: none;
    }
    </style>
    <script src="{% static 'baton/app/dist/baton.min.js' %}"></script>
    <!-- <script src="http://localhost:8080/static/baton/app/dist/baton.min.js"></script> -->
    <script src="{% static 'baton/js_snippets/init_baton.js' %}"></script>
    {% baton_theme %}
    {% if LANGUAGE_BIDI %}
        <link rel="stylesheet" type="text/css" href="{% static 'admin/css/rtl.css' %}">
        <script src="{% static 'baton/js_snippets/rtl.js' %}"></script>
    {% endif %}
{% endblock extrahead %}

{% block branding %}
    <div class="baton-startup-overlay"></div>
    <h1 id="site-name">
        <a href="{% url 'admin:index' %}">{{ site_header|default:_("Django administration") }}</a>
    </h1>
{% endblock branding %}

{% block nav-global %}{% endblock nav-global %}
{% block footer %}{% footer %}{% endblock footer %}

---

2. Replace FontAwesome Icons with Material Symbols

Support for FontAwesome has been dropped in favor of Material Symbols.

Update your icon definitions in the BATON settings. For example:

...
"MENU": (
    {
        "type": "title",
        "label": "System",
        "apps": ("auth",),
        "icon": "lock",  # Previously "fa fa-lock"
    },
...

🔗 Browse available icons

---

3. Update Custom Themes

If you’ve used custom themes, note that the available CSS variables have changed.
You'll need to update your styles accordingly.

🔗 View updated variables

---

✅ Recommendation

Due to the changes in menu styling, we recommend using:

• title menu items with icons
• Their children property to add subitems without icons

This approach results in a cleaner, more consistent layout.

---

Let us know if you encounter any issues — and happy upgrading!