You have an on-premises SharePoint farm with an Intranet, Publishing Portal, Blogs or Wikis - we will go through the approach on how you can transform your SharePoint on-premises portal to SharePoint modern sites using a more direct method.

Updates to the modernization tooling

There have been many updates to the PnP Transformation tool since the last post that adds new options, features and approaches to the modernization of your Intranet.

The most significant of those, that we have used with our clients are:

  • Support for on-premises to SharePoint Online conversions
  • URL rewriting and custom mapping via CSV file
  • Support for provisioning Page properties

Lots of hard work is going on by Bert Jansen and multiple community contributors to improve this tool so you can see the details of all the latest bug fixes, changes and enhancements to the tooling at: Modernization Framework Release Notes

So what’s the direct approach

Previously, to go from on-premises to SharePoint Online, you were required to use a 3rd party migration tool to copy all the content and structure to SharePoint Online classic portal, with the support for on-premises with the PnP transformation tooling, this is now an option not a dependency.

For example:

Direct approach method

Direct approach method

With PnP PowerShell, you can establish a connection from your on-premises implementation from SharePoint 2013, 2016 and 2019 to target the destination site in SharePoint Online to transform pages including assets.

Note: Modernization tooling in PnP Framework no longer supports SharePoint 2010 because it is deprecated, for 2010 use the latest SharePointPnPPowerShellOnline classic module.

You can update your strategy to avoid using the 3rd party tooling altogether and pull across only the content you require without all of the extra configuration artifacts in SharePoint Online.

In comparison to the post: “Taking the leap from On-Premises Portals to Modern sites”, this article discussed how to move to SharePoint Online modern site using a migrated site then transforming the content.

Indirect approach method

Indirect approach method

This offers greater flexibility and choice to the approach you can use when deciding what you want to keep. However, there are advantages and disadvantages to the direct approach:


  • Substantially quicker transform of pages from the true source environment, only the pages and related assets are included, so you only transfer what content is used or specified.
  • Flexibility for last minute transformations if you are using the original approach - this is super useful in maintaining and updating the deltas between two intranets prior to switch over without the extra hop to copy the site.
  • Reduce the security risk of potentially migrating a vulnerability in classic portal customization with scripts or 3rd party libraries are used to enhance the experience.


  • You will only have the pages from the original portal - the PnP transformation tooling is not a migration tool, it will not include other artifacts outside of Web Part, Wiki or Publishing pages
  • There is advantages to keeping a archive of the original portal in SharePoint Online, such as
    • The ability to reference the original portal if there is content that is missed or overlooked during the migration process
    • After the switch over to the new Intranet, you can decommission your previous portal but retain a copy of it live in SharePoint Online.

Achieving this with PnP PowerShell

To start with, you need to obtain the latest version of PnP PowerShell, using the instructions provided here: SharePoint PnP Cmdlets | Microsoft Docs

You need to use the SharePoint Online version. Why? The target connection is SharePoint Online and modern pages are the latest features with capabilities not provided in the on-premises versions - you can use this version to connect to the source for SharePoint 2013, 2016 and 2019 to transform to SharePoint Online Modern.

For a full script, we submitted a sample script on PnP Script Samples gallery to help you get started.

How do the other features help

Although these features are not specifically for this type of transformation scenario, these can be used in SharePoint Online classic to Modern as well, they do greatly improve the transformation experience and significantly reduce effort for any manual or scripted post transformation tasks.

URL rewriting and custom mapping via CSV file

The move to SharePoint Online involves changes in the URL structure and domain. As your domain changes from, for example, http://myportal to, any URL references in Content Editor web parts, Summary Links or HTML content fields that hyperlink to other pages will break. However with this feature, you can map out the source and destination URLs in the CSV file and this will be updated along with the transform.

This significantly reduces the effort required to update all the new Quick Links web parts pointing to the new locations for resources and pages during post transform clean up and page QA processes.

To find out more using this feature visit: Modernize User Interface Site Pages: Url Mapping | Microsoft Docs

Support for showing Page properties

The Page Properties web part provides the ability to surface metadata from modern site page libraries to pages. This can now be mapped in the page layout files to surface this content by selecting which metadata fields from the source is shown in the Page properties web part.

SharePoint Patterns and Practices

Parker the Mascot for PnP

Parker the Mascot for PnP

The SharePoint Patterns and Practices program is a community of people using their knowledge and experience to build a large pool of resources for libraries, provisioning, transformation, sample SharePoint Framework web parts and extensions.

PnP Modernization Project

If you wish to contribute, have an issue or get more information about the project visit:

See our post: Blog: Getting Started with modernizing your Intranet to being your journey to modern SharePoint.

Update: The modernization tooling is now integrated into PnP Framework, thus please report bugs there as above. For further information about the updates to Modernization tooling, please go to the Blog - Modernization lives on in PnP Framework

Feel free to contact me on Twitter, LinkedIn, or via GitHub if you have any questions!