Ā· 7 min read

Can I convert a Publishing page to the modern experience?

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?' The answer is Yes.

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?' The answer is Yes.

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):

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:

Can a page from a publishing site, even those that I have heavily customized, with custom CSS, JavaScript and HTML be converted?

Yes, the page transformation tool supports this type of conversion. This focuses explicitly around theĀ content in yourĀ pages such as the web parts you use, the fields and metadata - the mapping of this does require aĀ mapping fileĀ to select what elements of the classic page you wish to preserve and include in modernizing. The conversion ignores your customizations, including custom CSS and JavaScript - simply because the modern experience does not support them. There are many new capabilities included out of the box which you would have had to previous code, for example, mobile-friendly, visually stunning and responsive design, accessibility and simpler editing experience. If there is specific functionality you wish to keep, then consider rewriting these customizations into the SharePoint Framework that is a supported model for custom web parts.

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:

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.

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:

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.

Enjoy!

Share:
Back to Blog