Recently, I heard a question at GlobalCon2 in an ask me anything session and the question was “Is there any easy way to convert a publishing site into the modern experience?” - a really good question (and thanks for the shout out - Matt Weston). The answer is “Yes” there is a way to convert a site from Wiki, Web Part Pages, Classic Blogs and Publishing Pages over to the modern experience using the PnP Page Transformation tooling.
PnP Page Transformation is a community project created by Bert Jansen at Microsoft. The project contains two elements: a Modernization scanner to provide an inventory report of your classic artefacts and page transformation which is part of the PnP PowerShell library that contains a set of cmdlets for performing modernization. These cmdlets are (and links to their associated documentation):
- ConvertTo-PnPPage - the main tool for conversion
- Export-PnPPageMapping - for generating an XML mapping file of your publishing layout pages
- Save-PnPPageConversionLog - for writing the logs to disk in a bulk logging scenario
The tools do assume that you as the implementer will know how to use PowerShell and are familiar with the details of how classic and modern experiences work to understand how you can take advantage of the modern features. The conversion story is complicated, and the tools handle the majority of scenarios to get you going with minimal effort to make this easier to perform. Here are some common questions that I have encountered:
My source site is on-premises can I use the tooling for this?
Yes, the page transformation tool supports a range of source SharePoint versions, including SharePoint 2010 to 2019. There is a strategy to consider to either directly convert from these source systems OR use a 3rd party migration tool (first-party, e.g. SPMT does not support this scenario) to duplicate the site in SharePoint Online classic then convert the site to modern. These strategies go into more detail in the following blogs:
- Migration then conversion scenario - Taking the leap from On-Premises Portals to Modern sites
- Direct conversion from on-premises - Taking a direct approach leaping to a modern Intranet
I don’t use publishing sites and have wiki pages or web part pages. I have a classic blog, can I convert that too?
Yes, the tooling supports multiple modes of conversion from these sources - these can be done in-place or cross-site collection into a Modern Team Site (Office 365 Team or Modern Team) and Communication site.
I’m just the admin, how can I tell what areas of my Office 365 tenant that I can modernize?
Yes, the tooling includes a Modernization Scanner, that connects to your online environment to assess what artefacts can be modernized - this can provide a report on all of the classic features that could be modernized. Using these reports, you can see which areas of SharePoint Online that can be converted - this, however, does not support on-premises environments and the current recommendation is to use the SharePoint Migration Analysis Tool for a similar detail.
My pages have references to assets and links to resources can I include these?
Yes - the page transformation tool includes assets such as images referenced in web parts and transfers these into the site assets library, following the standard folder structure, as if you manually uploaded an image to a modern site, e.g. Site Assets > SitePages > [PageName]. URLs are also included and can be remapped to target new locations for those pages if required - this is useful if you are migration a range of existing sites with a lot of references to pages that are also being modernized.
Do you have any scripts that can help me get started with this?
Yes, there are a set of sample modernization scripts in the PnP Script Samples gallery under Modernize to help you get started. If there is a script you would like or help with using the cmdlet, feel free to create an issue, and we can look to help you or point you in the right direction.
What web parts are supported, I heard that not all of them exist in modern experience?
That’s right modern web parts are not an exact match for their classic counterparts, some operate differently, and there are web parts that are no longer supported in the modern experience. Those web parts that work differently, there is a mapping mechanism to convert classic to modern - you have the option of changing the mapping (see example 2) to suit your requirements. For further detail on what classic to modern web parts are supported, visit this site.
Why are there so many mapping files? And are they all required?
No, the mapping files are not required - without these files, the tooling has default modes to work out these types of conversions for you, however for the highest flexibility of options to cater for a wide variety of SharePoint configurations, these are provided to override the default and choose your specific settings. The following optional mapping files are:
- Web Part Mapping - that maps classic web parts to modern web parts, to generate this file use Export-PnPPageMapping to export the default mapping file.
- Page layout mapping file - XML mapping file that maps your publishing page layout files, the web parts, metadata and options to modern experience. To generate this file, use Export-PnPPageMapping to scan your existing page layout files to create the map.
- User Mapping File - CSV file to map source users to target users
- URL Mapping File - CSV file to map URLs from the source to new URLs in the target
- Taxonomy Mapping File - CSV file to map taxonomy terms in the source environment term store to SharePoint Online taxonomy term store.
What resources are there to get started?
In addition to the resources already mentioned, here are more resources to help you get you started, check these out:
- Main GitHub Project - PnP Framework | GitHub
- PnP Transformation documentation - Modernize Classic Sites | Microsoft Docs
- My blog post on getting started - Blog: Getting started with modernizing your intranet
- ESPC Webinar from Bert Jansen - Taking your SharePoint to the next level transform existing sites to the modern experience | SharePoint Europe
- YouTube series on Page Transformation - Page Transformation | YouTube
- Video example of converting classic to modern by Bert Jansen - Community call demo - Transforming classic SharePoint blog pages to modern pages | YouTube
- My slide deck for Black Country User Group- Getting Started Modernizing your Intranet (PowerPoint)
- If you find a bug, have an issue or enhancement, please post to the issues list on GitHub
Update: The modernization tooling is now integrated into PnP Framework additionally, this blog has been updated with the new cmdlets used in PnP PowerShell. For further information about the updates to Modernization tooling, please go to the Blog - Modernization lives on in PnP Framework
Feel free to reach out on Twitter, or the GitHub issues list, if you have more questions, I’d be happy to help.