Rewrite classic page transformation guidance around PnP PowerShell

docs/toc.yml

@@ -1858,6 +1858,38 @@
       items:
       - name: Transform with PnP PowerShell
         href: transform/modernize-userinterface-site-pages-powershell.md
+      - name: Run page wave scripts
+        href: transform/modernize-userinterface-site-pages-wave-scripts.md
+      - name: Validate transformed pages
+        href: transform/modernize-userinterface-site-pages-validation.md
+      - name: Reference
+        items:
+        - name: In-place versus cross-site transformation
+          href: transform/modernize-userinterface-site-pages-approach.md
+        - name: Security requirements
+          href: transform/modernize-userinterface-site-pages-security.md
+        - name: Configuration options
+          href: transform/modernize-userinterface-site-pages-configuration.md
+        - name: Classic Web Part mappings
+          href: transform/modernize-userinterface-site-pages-webparts.md
+        - name: Page transformation model
+          href: transform/modernize-userinterface-site-pages-model.md
+        - name: Publishing page transformation model
+          href: transform/modernize-userinterface-site-pages-model-publishing.md
+        - name: Functions and selectors
+          href: transform/modernize-userinterface-site-pages-api.md
+        - name: User mapping
+          href: transform/modernize-userinterface-site-pages-usermapping.md
+        - name: URL mapping
+          href: transform/modernize-userinterface-site-pages-urlmapping.md
+        - name: Term mapping
+          href: transform/modernize-userinterface-site-pages-termmapping.md
+        - name: Layout transformation
+          href: transform/modernize-userinterface-site-pages-layout.md
+        - name: .NET integration
+          href: transform/modernize-userinterface-site-pages-dotnet.md
+        - name: Videos
+          href: transform/modernize-userinterface-site-pages-videos.md
   - name: Modernizing your classic SharePoint sites
     items:
     - name: Overview
@@ -1877,35 +1909,6 @@
           href: transform/modernize-userinterface-lists-and-libraries-optout.md
       - name: Transform classic pages to modern pages
         href: transform/modernize-userinterface-site-pages.md
-        items:
-        - name: Page transformation via PowerShell
-          href: transform/modernize-userinterface-site-pages-powershell.md
-        - name: Page transformation via .Net
-          href: transform/modernize-userinterface-site-pages-dotnet.md
-        - name: Page transformation videos
-          href: transform/modernize-userinterface-site-pages-videos.md
-        - name: Page transformation configuration options
-          href: transform/modernize-userinterface-site-pages-configuration.md
-        - name: Classic web part to modern mapping
-          href: transform/modernize-userinterface-site-pages-webparts.md
-        - name: In-place versus cross-site page transformation
-          href: transform/modernize-userinterface-site-pages-approach.md
-        - name: Page transformation security
-          href: transform/modernize-userinterface-site-pages-security.md
-        - name: Page transformation model
-          href: transform/modernize-userinterface-site-pages-model.md
-        - name: Publishing Page transformation model
-          href: transform/modernize-userinterface-site-pages-model-publishing.md
-        - name: Page transformation Functions and Selectors
-          href: transform/modernize-userinterface-site-pages-api.md
-        - name: User mapping
-          href: transform/modernize-userinterface-site-pages-usermapping.md
-        - name: URL mapping
-          href: transform/modernize-userinterface-site-pages-urlmapping.md
-        - name: Term mapping
-          href: transform/modernize-userinterface-site-pages-termmapping.md
-        - name: Page layout mapping
-          href: transform/modernize-userinterface-site-pages-layout.md
     - name: SharePoint Modernization scanner
       items:
       - name: Overview

docs/transform/assess-sharepoint-modernization.md

@@ -36,6 +36,7 @@ Mapping readiness is an input to planning, not a guarantee that the transformed
 1. [Interpret and prioritize the page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference
 

docs/transform/assessment-tool-classic-pages-report.md

@@ -81,7 +81,7 @@ Use `classicpagewebparts.csv` for the per-page decision:
 
 Use `classicwebpartunique.csv` to identify web part types that affect many pages. `InMappingFile` is weaker than `IsMappable`: it only means that the type has an entry in the mapping file.
 
-The current Assessment implementation deliberately treats the community mappings for `ScriptEditorWebPart` and `SimpleFormWebPart` as unavailable. It also doesn't support the legacy Scanner's on-disk mapping-file override.
+The current Assessment implementation deliberately treats the community mappings for `ScriptEditorWebPart` and `SimpleFormWebPart` as unavailable. It also doesn't support an on-disk mapping-file override.
 
 ## Use rollups
 
@@ -98,7 +98,7 @@ Rollups are useful for sequencing, but return to the page and web part CSV files
 
 `classicpublishingsitesummaries.csv` provides a site-collection-level publishing summary. Detailed legacy web-level publishing configuration isn't included.
 
-See [Understand publishing portal coverage](assessment-tool-publishing-coverage.md) before replacing an established Publishing Scanner workflow.
+See [Understand publishing portal coverage](assessment-tool-publishing-coverage.md) before planning publishing page transformation.
 
 ## Move from assessment to transformation
 
@@ -123,64 +123,17 @@ Turn the report into a transformation backlog:
 
 The Assessment app is read-only. Use a separate PnP PowerShell connection with permission to create or update pages in the source or target web.
 
-### Transform one selected Wiki or Web Part page
-
-This example selects one assessed page and transforms it in place. Filter on the exact `PageUrl` that you approved for the migration wave.
-
-```powershell
-$row = Import-Csv .\classicpages.csv |
-  Where-Object PageUrl -eq '/sites/source/SitePages/ApprovedPage.aspx' |
-  Select-Object -First 1
-
-if ($row.PageType -notin @('WikiPage', 'WebPartPage')) {
-  throw "This example only handles WikiPage and WebPartPage rows."
-}
-
-$sourceWebUrl = if ($row.WebUrl -eq '/') {
-  $row.SiteUrl
-}
-else {
-  "$($row.SiteUrl.TrimEnd('/'))$($row.WebUrl)"
-}
-
-$source = Connect-PnPOnline `
-  -Url $sourceWebUrl `
-  -Interactive `
-  -ClientId <application-id> `
-  -ReturnConnection
-
-$libraryPath = $row.ListUrl.TrimEnd('/')
-if (-not $row.PageUrl.StartsWith("$libraryPath/", [StringComparison]::OrdinalIgnoreCase)) {
-  throw "PageUrl isn't under ListUrl."
-}
-
-$pageRelativeToLibrary = $row.PageUrl.Substring($libraryPath.Length).TrimStart('/')
-$pageName = [IO.Path]::GetFileName($pageRelativeToLibrary)
-$folder = [IO.Path]::GetDirectoryName($pageRelativeToLibrary) -replace '\\', '/'
-$libraryName = [Uri]::UnescapeDataString([IO.Path]::GetFileName($libraryPath))
-
-$parameters = @{
-  Identity = $pageName
-  Connection = $source
-}
-
-if ($libraryName -ne 'SitePages') {
-  $parameters.Library = $libraryName
-}
-if (-not [string]::IsNullOrWhiteSpace($folder)) {
-  $parameters.Folder = $folder
-}
-
-ConvertTo-PnPPage @parameters
-```
+### Continue with the transformation task
+
+Use the field mapping to approve the exact Assessment row and record the expected content. Then follow [Transform selected classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md) for the current application, permission, source-identity, draft-output, logging, and validation safeguards.
 
 Route other page types deliberately:
 
 - `PublishingPage`: use `-PublishingPage`, a target web, and the [publishing page-layout model](modernize-userinterface-site-pages-model-publishing.md).
 - `BlogPage`: use `-BlogPage`, `PageName` as the blog-title identity, and a target web. Blog rows don't receive the detailed mapping-readiness enrichment described for Wiki, Web Part, and Publishing pages.
 - `ASPXPage` and `DelveBlogPage`: exclude them from this automated transformation queue; the page assessment doesn't provide an equivalent readiness path for them.
 
-Start with [Transform classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md). Use the [page transformation model](modernize-userinterface-site-pages-model.md) for custom Web Part mappings and the [publishing model](modernize-userinterface-site-pages-model-publishing.md) for publishing page layouts.
+Start with [Transform selected classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md), and then [validate each transformed page](modernize-userinterface-site-pages-validation.md). Use the [page transformation model](modernize-userinterface-site-pages-model.md) for custom Web Part mappings and the [publishing model](modernize-userinterface-site-pages-model-publishing.md) for publishing page layouts.
 
 ## Power BI and CSV
 

docs/transform/assessment-tool-classic-pages-requirements.md

@@ -101,6 +101,7 @@ Assessment output can contain tenant and site URLs, application identifiers, use
 1. [Interpret and prioritize the classic page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference
 

docs/transform/assessment-tool-classic-pages-run.md

@@ -139,6 +139,7 @@ Use `--delimiter Semicolon` when a semicolon-delimited export is required. Use `
 1. [Interpret and prioritize the classic page results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ## Reference
 

docs/transform/assessment-tool-classic-pages.md

@@ -25,6 +25,7 @@ In the current implementation, Delve Blog pages appear in `classicpages.csv` but
 1. [Interpret and prioritize the results](assessment-tool-classic-pages-report.md).
 1. [Review publishing-page readiness](assessment-tool-publishing-coverage.md), when applicable.
 1. [Transform selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
+1. [Validate the transformed pages](modernize-userinterface-site-pages-validation.md).
 
 ### Reference
 
@@ -91,7 +92,7 @@ Use the assessment output to select pages and identify Web Parts that need remed
 1. Remove, replace, or map blocking Web Parts.
 1. Start with a small representative wave.
 1. [Transform the selected pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md).
-1. Validate the generated modern pages before expanding the wave.
+1. [Validate the generated modern pages](modernize-userinterface-site-pages-validation.md) before expanding the wave.
 
 For the complete transformation model and advanced mapping options, see [Transform classic pages to modern pages](modernize-userinterface-site-pages.md).
 

docs/transform/assessment-tool-publishing-coverage.md

@@ -58,31 +58,19 @@ The current page assessment doesn't provide these publishing transformation inpu
 - Global, security-group, and SharePoint-group audience values.
 - Master-page, alternate-CSS, navigation, approval, versioning, scheduling, variation, audience, and ownership configuration.
 
-These areas are outside the Page Assessment scope. The lifecycle of legacy Scanner reports is handled separately from this guidance.
+These areas are outside the Page Assessment scope.
 
 ## Continue to publishing-page transformation
 
 1. Group publishing pages by `Layout`.
 1. Review `MappingPercentage` and `UnmappedWebParts`.
 1. Identify custom layouts that need a page-layout mapping.
-1. Validate representative pages before processing a complete portal.
+1. [Transform representative publishing pages](modernize-userinterface-site-pages-powershell.md#route-other-page-types).
+1. [Validate representative pages](modernize-userinterface-site-pages-validation.md) before processing a complete portal.
 
-For an out-of-the-box publishing layout, use the built-in layout mapping where possible:
+For an out-of-the-box publishing layout, use the built-in layout mapping where possible. For a custom publishing layout, generate and review a mapping before transformation.
 
-```powershell
-Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/source -Interactive -ClientId <application-id>
-
-ConvertTo-PnPPage `
-  -PublishingPage `
-  -Identity Article.aspx `
-  -TargetWebUrl https://contoso.sharepoint.com/sites/target
-```
-
-For a custom publishing layout, generate and review a mapping before transformation:
-
-```powershell
-Export-PnPPageMapping -CustomPageLayoutMapping -Folder C:\temp
-```
+Continue with [Transform selected classic pages with PnP PowerShell](modernize-userinterface-site-pages-powershell.md#route-other-page-types) and the [Publishing Page transformation model](modernize-userinterface-site-pages-model-publishing.md).
 
 ## Reference