Skip to content

Migration guide: V3 V4

Jump to bottom
Jean-François Garreau - Binomed edited this page Aug 12, 2025 · 7 revisions

This guide will help you to migrate your theme V3 to V4.

Breaking Changes

V4 Introduce lot of breaking changes!

Path change

Due to a new build, you have to now import sfeir-school-theme from dist directory and not directly from sfeir-school-theme directory

Index.html

<!doctype html>
<html lang="en">
    <head>
    ...
        <link
            rel="stylesheet"
            type="text/css"
            href="./web_modules/sfeir-school-theme/sfeir-school-theme.css"
            id="theme" />
    </head>
...

to replace by

<!doctype html>
<html lang="en">
    <head>
    ...
        <link
            rel="stylesheet"
            type="text/css"
            href="./web_modules/sfeir-school-theme/dist/sfeir-school-theme.css"
            id="theme" />
    </head>
...

slides.js

import { SfeirThemeInitializer } from '../web_modules/sfeir-school-theme/sfeir-school-theme.mjs';

to replace by

import { SfeirThemeInitializer } from '../web_modules/sfeir-school-theme/dist/sfeir-school-theme.mjs';

Class for images!

Due to support for accessibilty, the previous syntax that let you specify classes in the alt field of image is now forbidden. You will have to use what is define in Markdown.

![h-400 w-200](./assets/images/GDG.png)

Have to be replace by:

![](./assets/images/GDG.png 'h400 w-200')

End of two-column and two-column-layout

Previously, the two-column layout was done by playing verticals slides syntax. Now a new syntax is introduce and let you have "multiples columns". To do the migration pay attention to thoses elements:

  1. Wrap each column in the new syntax
  2. If you use data-state on a sub column, you have to migrate it on the main slide
  3. No "main title" is available (as it was for two-column)
  4. If you use speakers notes on each column, you have to migrate all of them at the end of the slide
  5. If you use data-background on the column, you have to integrate them in the new syntax.
  6. The text color of the column is by default the same as normal slides, and if you have to deal with a negative slide, you should use the class contrast-opposite. This mean that the class "text-dark" is now useless
  7. Change two-column or two-column-layout by `tc-multiplie-columns'

The new syntax is something like that :

##++##
The content of a column
##++##

Old slide (two-column-layout)

<!-- .slide: class="two-column-layout"-->

# A title (deprecated)

##--##

content left

##--##

content right

Replace it by

<!-- .slide: class="tc-multiple-columns"-->

##++##
# A title (deprecated)

content left
##++##
##++##
content right
##++##

Old slides (two-column)

<!-- .slide: class="two-column" data-state="test" -->

## Slide 1 with notes

A paragraph with some text and a [link](http://hakim.se).

Press 'S'

Notes:
Notes for slide left

##--##

<!-- .slide: data-state="test2"  -->

## Slide 2 with notes

-   Item 2
-   Item 3
<!-- .element: class="list-fragment" -->

Notes:
Notes for slide right

##==##

<!-- .slide: class="two-column" data-background="./assets/images/dark_background.jpeg" -->

# Some text

##--##

## Slide 2

-   Item 2
-   Item 3
<!-- .element: class="list-fragment" -->

Replace it by:

<!-- .slide: class="tc-multiple-columns" data-state="test test2" -->

##++##
## Slide 1 with notes

A paragraph with some text and a [link](http://hakim.se).

Press 'S'
##++##

##++##

## Slide 2 with notes

-   Item 2
-   Item 3
<!-- .element: class="list-fragment" -->

##++##

Notes:
Notes for slide left
Notes for slide right


##==##

<!-- .slide: class="tc-multiple-columns" -->

##++## data-background="./assets/images/dark_background.jpeg" class="contrast-opposite"

# Some Text
##++##

##++##

## Slide 2

-   Item 2
-   Item 3
<!-- .element: class="list-fragment" -->
##++##

Rework for speaker slides

  1. You should have to wrap the actual content of a speaker slide in a div with the class .speaker-slide
  2. You don't need anymore 'icon-rule', 'icon-*' classes
  3. Badge like first-badge... are not necessary now, simply indicate badge 
<!-- .slide: class="speaker-slide" -->

# Votre hôte pour la journée

![speaker](./assets/images/jf.jpg)
![company](./assets/images/logo-sfeir-blanc.png)
![badge first-badge](./assets/images/gde.png)
![badge second-badge](./assets/images/GDG-Logo-carre.png)
![badge third-badge mt-50](./assets/images/mts.png)

<h2>Jean-François<span> Garreau</span></h2>

### CTO front

<!-- .element: class="icon-rule icon-first" -->

### @jefbinomed

<!-- .element: class="icon-twitter icon-second" -->

### [email protected]

<!-- .element: class="icon-mail icon-third" -->

To replace by:

<!-- .slide: class="speaker-slide" -->
<div class="speaker-slide">

# Hello ! @SFEIR

## Jean-François <b>Garreau</b>

### CTO Front

### [email protected]

### @jefbinomed

![](./assets/images/jf.jpg 'speaker')

![](./assets/images/logo-sfeir-blanc.png 'company')

![](./assets/images/gde.png 'badge')

![](./assets/images/GDG-Logo-carre.png 'badge')

![](./assets/images/mts.png 'badge')
</div>

Icon syntax change

To support more libraries (now support, feather, font-awesome, material-symbols), you have to change the way you declare and icon. This guide will show you how to migrate feather icons due to the fact it was the only support icons library in V3

![sfeir-icons](github) basic icon

![sfeir-icons small](github) small icon

![sfeir-icons big](github) big icon

![sfeir-icons](github)<!-- .element: style="--icon-size:96px; --icon-color:orange;" --> custom icon and custom color

To replace by:

![](github 'tc-icons feather') basic icon

![](github 'tc-icons feather tc-small') small icon

![](github 'tc-icons feather tc-big') big icon

![](github 'tc-icons feather')<!-- .element: style="--tc-icon-size:96px; --tc-icon-color:orange;" --> custom icon and custom color

Change in data-theme, ... attributes

  • data-theme-slide in html become data-theme and theme in url become data-theme
  • data-type-show in html become data-type abd type in url become data-type
  • lang in url become data-lang

Change Node env for your school

  1. Update .nvmrc to version 20
  2. Update docker-compose.yaml to node version 20.2

Modifications in package.json

Just update sfeir-school-theme to 4.X.X version

Migration Script

To helps you with this, a migration tools exists in the last release to do the main expected tasks here. This script is not perfect so please be careful when you run it, take times to review all the problems and fix thems manually. To launch the migration script

  1. Install the last version of the theme (4.X.X)
  2. run npx sfeir-school-theme-migrate -> This will modify all the elements specified above
  3. run (optionnal) npx sfeir-school-theme-cleanup -> This will clean a litle bit you markdown with removing previous classes unused

Install node module

As the new version of node supported is 20, you will have to update your node_modules with npm i.

Clone this wiki locally