Super 3.1 – Changes & Code update guide

💡

You can preview what this update looks like on your site at beta.super.so

Technology Upgrade

In the 3.1 release Super sites are getting a significant update. This update is mostly related to the technology on which Super sites runs, and provides huge site performance enhancements. It also allows us to start implementing new features which were previously not possible. It also sets up the Super platform for a robust future.

This brings huge performance boosts by significantly reducing the amount of HTML required to render a page - we’ve cut the number of elements on a typical page by over 30%. We did this by rebuilding many of the sites components in a smarter way and reducing nested elements. This also improves SEO since search engines favor sites that load faster. One implication of this update is the simplification of some of the Super page structures which can have an impact to your sites custom code.

Check and update your Custom Code

For most sites there will be no impact from these changes. For some sites using custom code, there may be some impact. We don’t do this kind of update often because it can break custom code.

On the sites we’ve tested, most custom code works fine, and any changes that are required to be compatible with this update are very minimal.

However, some sites use custom code that relies on a specific DOM structure, so we are rolling the update out slowly to give everyone time to update their custom code if needed.

How to check your code

After the update is initially deployed, the Super dashboard preview in the Beta will show your site with the updated HTML structure, but your live site will continue to render the old HTML until you commit to the upgrade by pressing the upgrade button, or the beta/transition period elapses.

View your site in the Super Dashboard Beta - during the initial beta period use beta.super.so instead of app.super.so
You will see an upgrade button on the dashboard - this means your live site is still running the old version of Super and the Preview panel in the Dashboard is running the new version.

⚠️

Upgrading your site is a one way process and cannot be undone.

Don’t press the ‘Update now’ button until you are happy that your code is updated and working in the Preview Panel.

Backup your custom code - ensure that you make your own backups of your custom code before you make any changes - select all the code, copy it, and paste it into a Notion page somewhere in your Notion account making note of where the code came from - global/which page etc.
Check your custom code - using the guide below, check for code references that may have changed and validate that the changes you make are fixing any incompatibilities. You can use your live site as a reference during the beta and transition periods until you press the Upgrade button.

💡

In the Super code editor, pressing cmd-f or ctrl-f will open up a search box, that will allow you to search through the code.

Your live site will still be referencing the same custom code base as the new version, so any changes to the CSS will need to also support your current live site. You can manage this by maintaining the original CSS references in the code, and adding the new references to the code.

so if you had the following code:

.super-content-wrapper .super-content {
  color: red !important;
}

Then add the new reference rather than replacing it:

.super-content-wrapper .super-content, .super-content { /* 3.1 */
  color: red !important;
}

This will maintain backward compatibility for your live site while the transition happens. Using a comment on the updated line will help you manage the changes without re-work.

Upgrade your site once you are happy with the changes - if you are using more general CSS code, then chances are you won't have needed to make any changes. Pressing the upgrade button will initiate the upgrade process for your site. Upgrades will be done in batches at least once every 24 hours.

Getting help with this transition

While your custom code is your responsibility, we can support you with this change to help you identify any small fixes to help with the transition - reach out to support in the Chat bubble in the bottom right of the Dashboard, and we’ll help you work through the process.

Code changes breakdown

Here is a breakdown of the specific changes in the HTML code, including class names, and before-and-after comparisons.

Global layout changes

Change	Suggested Custom CSS checks
`div` with id of `#__next` has been completely removed	Check for uses of `#__next`
The highest level targetable element is now a `div` with the class of `.super-root` and is the direct child of the `body`	Replace any uses of uses of `#__next` with `.super-root`
The `div` element that uses the page specific id such as `#page-index` has been changed to a `main` element	Check for any references to `div#page-NAME`
`.notion-navbar/.super-navbar` and `.super-footer` are now outside of the `#page-NAME` wrapper	Check references to `.super-navbar` and `.super-footer` are not preceded by `#page-NAME.` Custom code targeting specific pages should now be done on a page-specific level.
Removed `span` wrapping images, icons, text across all components	Check for all references to `span` in your CSS
`.notion-navbar` and `.super-navbar` elements has changed from `div` to `nav`	Check for references to `div.super-navbar` or `div.notion-navbar`
`.super-footer` element has changed from `div` to `footer`	Check for references to `div.super-`footer

<body>
	<div id="__next">
		<div id="page-index" class="super-root page__index">
			<div class="super-navbar">...</div>
			<div class="super-content-wrapper">
				<div class="notion-header page">...</div>
				<div class="super-content">
					<article class="notion-root">...</div>
				</div>
			</div>
			<div class="super-footer">...</div>
		</div>
	</div>
</body>

Before

<body>
	<div class="super-root">
		<nav class="super-navbar">...</nav>
		<div class="super-content-wrapper">
			<main id="page-index" class="super-content page__index">
				<div class="notion-header page">...</div>
				<article class="notion-root">...</article>
			</main>
		</div>
		<footer class="super-footer">...</footer>
	</div>
</body>

After

Notion Page

Change	Suggested Custom CSS checks
`div` after `.notion-page` is removed	Check for `.notion-page` references that are relying on a `div` following
`span` after `.notion-page__icon` is removed	Check for `.notion-page__icon` references that are relying on a `span` following
`.notion-page__icon` changed from `div` to `span`	Check for `div.notion-page__icon` references
`.notion-root.full-width` is now `.notion-root.max-width` when page is not full width	Check for `.notion-root.full-width` references

<a id="block-5794182c5e384fc6a3f30a6d1cf9448e" class="notion-link notion-page" href="/site/d2437950-1bc9-4e81-ad37-01dc059ea9f0#5794182c5e384fc6a3f30a6d1cf9448e">
	<div>
		<div class="notion-page__icon">
			<span>
				<img alt="Getting Started" src="https://assets.super.so/d2437950-1bc9-4e81-ad37-01dc059ea9f0/images/39c8827b-b29f-4422-b2e3-a7241ec7d02e/2.svg" decoding="async" data-nimg="fixed" class="notion-icon"  srcset="https://assets.super.so/d2437950-1bc9-4e81-ad37-01dc059ea9f0/images/39c8827b-b29f-4422-b2e3-a7241ec7d02e/2.svg 1x, https://assets.super.so/d2437950-1bc9-4e81-ad37-01dc059ea9f0/images/39c8827b-b29f-4422-b2e3-a7241ec7d02e/2.svg 2x">
			</span>
		</div>
		<div class="notion-page__title">
			<span class="notion-semantic-string">
				<span>Getting Started</span>
			</span>
		</div>
	</div>
</a>

Before

<a id="block-5794182c5e384fc6a3f30a6d1cf9448e" class="notion-link notion-page" href="/5794182c5e384fc6a3f30a6d1cf9448e">
	<span class="notion-page__icon">
		<img class="notion-icon" alt="Getting Started" width="20" height="20"  src="https://assets.super.so/d2437950-1bc9-4e81-ad37-01dc059ea9f0/images/39c8827b-b29f-4422-b2e3-a7241ec7d02e/2.svg">
	</span>
	<span class="notion-page__title notion-semantic-string">Getting Started</span>
</a>

After

Heading

Change	Suggested Custom CSS checks
`.notion-heading__anchor` is above `h` tag	Check `.notion-heading__anchor` references that are looking for anchor tag within

<h1 id="block-c7b47dc318c04b40a780d10f35694526" class="notion-heading">
	<span class="notion-heading__anchor" id="c7b47dc318c04b40a780d10f35694526"></span>
		<span class="notion-semantic-string">
			<span>Hello World</span>
		</span>
</h1>

Before

<h1 id="block-c7b47dc318c04b40a780d10f35694526" class="notion-heading notion-semantic-string">
	Hello World
</h1>

After

Text

Change	Suggested Custom CSS checks
`span` after `.notion-semantic-string` is removed	Check for `.notion-semantic-string > span` or `.notion-semantic-string span`
remove `span` elements that wrap every part of a semantic string	Check for `.notion-semantic-string > span` or `.notion-semantic-string span` etc
`.notion-semantic-string` class is moved one element up. usually on a `.notion-*` class	Check for `.notion-semantic-string` references that may have dependency changes

Text block

Change	Suggested Custom CSS checks
Removal of the main parent `div` element	Check for `div.notion-text` references and update to `.notion-text`
`block id` and `.notion-text` class moved to the `p` element	Check `block` references that relate to text blocks, particularly if there are child references like `#block > p`
`span` element with class `.notion-semantic-string` removed and class moved onto the `p` element	Check for `.notion-text` references that include child `span` elements in the targeting
`span` element with no class has been removed	Check for `.notion-text` references that include child `span` elements in the targeting

<div id="block-b6997ba92b274084ae2a07fb5db63909" class="notion-text">
	<p class="notion-text__content">
		<span class="notion-semantic-string">
			<span>Hello World</span>
		</span>
	</p>
</div>

Before

<p id="block-b6997ba92b274084ae2a07fb5db63909" class="notion-text notion-text__content notion-semantic-string">
	Hello World
</p>

After

Text link

Change	Suggested Custom CSS checks
Removal of the main parent `div` element	Check for `div.notion-text` references and update to `.notion-text`
`block id` and `.notion-text` class moved to the `p` element	Check `block` references that relate to text blocks, particularly if there are child references like `#block > p`
`span` element with class `.notion-semantic-string` removed and class moved onto the `p` element	Check for `.notion-text` references that include child `span` elements in the targeting
`span` element with no class has been removed	Check for `.notion-text` references that include child `span` elements in the targeting

<div id="block-699ee84ecbe14a2c96a6b8feb2166a7c" class="notion-text">
	<p class="notion-text__content">
		<span class="notion-semantic-string">
			<span>
				<a href="https://super.so" class="notion-link link" target="_blank" rel="noopener noreferrer">
					Super
				</a>
			</span>
		</span>
	</p>
</div>

Before

<p id="block-699ee84ecbe14a2c96a6b8feb2166a7c" class="notion-text notion-text__content notion-semantic-string">
	<a class="notion-link link" href="https://super.so">
		Super
	</a>
</p>

After

Databases: Gallery cards

Change	Suggested Custom CSS checks
`notion-collection-card__property-list` and `notion-collection-card__content` are now combined and wrap both a card title and properties.	Check for `notion-collection-card__property-list` and `notion-collection-card__content` used as parent references for gallery card content or properties
Remove unnecessary `span` elements wrapping text	Check for collection-card references that include child `span` elements in the targeting

<div class="notion-collection-card">
	<a class="notion-link notion-collection-card__anchor"></a>
	<img class="notion-collection-card__cover">
	<div class="notion-collection-card__content">
		<div class="notion-property__title">
			<span class="notion-semantic-string">
				<span>Title Here</span>
			</span>
		</div>
		<div class="notion-collection-card__property-list">
			<div class="notion-collection-card__property">
				<div class="notion-property__text">
					<span>Text</span>
				</div>
			</div>
		</div>
	</div>
</div>

Before

<div class="notion-collection-card">
	<a class="notion-link notion-collection-card__anchor"></a>
	<div class="notion-collection-card__cover">
		<img>
	</div>
	<div class="notion-collection-card__content notion-collection-card__property-list">
		<div class="notion-property__title notion-semantic-string">
			Title Here
		</div>
		<div class="notion-property__text notion-collection-card__property">
			Text
		</div>
	</div>
</div>

After

Navbar

Change	Suggested Custom CSS checks
The main navbar container `div` with class `.super-navbar` has been changed to a `nav` element	Check for`div.super-navbar` references
The div wrapper around `.super-navbar__item-list` has been removed	Check for `.super-navbar*` references that include a child div
`.super-navbar__list-viewport` is gone	Check for `.super-navbar__list-viewport` references
Changed from Radix to custom. Some radix wrapper elements are gone in favor of a lighter component

<div class="super-navbar simple">
    <nav class="super-navbar__content">
        <a class="notion-link super-navbar__logo" href="/">
            <span class="super-navbar__logo-text">Logo text</span>
        </a>
        <div style="position:relative">
            <ul class="super-navbar__item-list"></ul>
        </div>
        <div class="super-navbar__actions "></div>
    </nav>
</div>

Before

<nav class="super-navbar simple">
  <div class="super-navbar__content">
    <a class="notion-link super-navbar__logo" href="/">
      <span class="super-navbar__logo-text">Logo text</span>
    </a>
    <ul class="super-navbar__item-list"></ul>
    <div class="super-navbar__actions "></div>
  <div/>
</nav>

After

Footer

Change	Suggested Custom CSS checks
The main footer container `div` with class `.super-footer` has been changed to a `footer` element	Check for `div.super-footer` references

Error Page

Change	Suggested Custom CSS checks
`.error-wrapper` is now `.super-error`	Check for `.error*` references
`.error-not-found` is now `.super-error__not-found`	Check for `.error*` references
`.error-text` is now `.super-error__text`	Check for `.error*` references

General

Change	Suggested Custom CSS checks
Removed unnecessary `span` elements that wrap other elements throughout	Check for any `span` references
`border-bottom` on links and pages have been changed to `text-decoration`	Check for any `border-bottom` settings for links and page links