Fixing image positioning in SharePoint

How to cope with the new way SharePoint handles images that are placed next to each other.

Summary of what happened images in SharePoint

Up until about mid-2023 SharePoint text web parts were able to display inline images next to each other. Then Microsoft started upgrading the editor component that powers the text web part, while at the same time introducing changes to the overall page style. This broke adjacent image positioning.

Specifially, when editing a SharePoint page, its text web parts are auto-upgraded to the new editor version which positions once-adjacent images now vertically, not horizontally:

So what are our options to fix this?

How to fix image positioning? And who?

The SharePoint text web part, at the time of this writing, does not support putting multiple images next to each other. Neither in the browser editor, nor via programmatic means.

Here’s a list of parties that could influence image positioning in text web parts, in principle:

  1. Microsoft - but they say the current behavior is by design, so they won’t help
  2. WikiTraccs
  3. You

Number one is out, let’s look at the other two options.

What can WikiTraccs do?

Short version:

At the moment, nothing.

Longer version:

When migrating Confluence pages to SharePoint, WikiTraccs creates pages that still show adjacent images. That’s because it’s generating pages in a version that still supports this. SharePoint supports displaying pages that use the (now) older version.

As soon as you edit such a page it is upgraded to a newer version that doesn’t support adjacent images anymore.

The only thing that WikiTraccs could do is starting to generate pages in such a way that images won’t be adjacent anymore, to begin with. You’d then see the non-adjacent version right away, without having to edit the page.

I’ll look into such options as soon as the new way to display pages is confirmed as generally available by Microsoft. I don’t have such a confirmation, yet.

That means that WikiTraccs cannot do anything at the moment.

What can you do?

You have two options:

  1. Re-arrange images and content when you edit a page.
  2. Roll back the layout change that Microsoft did to screw up image positioning.

Option 1 is straightforward: you edit a page, adjacent images are not next to each other anymore, you have to clean up.

Option 2 involves rolling back a single layout change that Microsoft introduces when upgrading the text web part.

The Wiki Transformation Project provides a tool to achieve option 2: the WikiTraccs Page Companion.

Introducing the WikiTraccs Page Companion

For option 2 to work, we need to change pages as they are displayed in the browser. It’s like duct taping a small piece of paper over a bad part of the page, using duct tape that can be removed without traces.

Fortunately Microsoft provides a supported means of integrating with SharePoint pages: SharePoint Framework (SPFx) Application Customizer. Using such a customizer, we can hook into each page as it is being displayed in the browser.

Regrettable, the change we need to make to how pages are being displayed is not officially supported by Microsoft. We need to accept that if we want to proceed with this duct tape option.

Here’s a demo video of the WikiTraccs Page Companion in action. About 11 seconds into the video, note the little box reading Legacy image positioning (by WikiTraccs) in the lower right corner, that’s the extension:

(Note, because I get asked: the page tree you see in the video is WikiPakk, the SharePoint page tree experience.)

The toggle button can be used to toggle the image positioning fix on and off on a per-page basis. On means, the duct tape is applied. Off means, the duct tape is being removed, again. It is opt-in, so not enabled by default.

As an author, you would check the page you are editing, and toggle the button as needed. The fix affects the page both when being edited and being viewed.

The WikiTraccs Page Companion is available as pre-compiled download (to be deployed to a SharePoint app catalog), and also as source code for you to build yourself. It’s all on GitHub: WikiTraccs Page Companion.

Note that the non-standard nature of this option means that it might stop working when Microsoft makes changes to pages. If that happens, the adjustments that need to be done need to be re-evaluated.

I’m putting the source code out there, so that you are in control as well.

Get in touch if you have any questions.