Configuring Hub Site Navigation using PnP PowerShell

A Hub Site in SharePoint Online helps organize related sites by providing consistent navigation, branding, and search. Using PnP PowerShell, administrators can efficiently configure and manage hub site navigation, ensuring a seamless user experience.

Why configure hub site navigation with PnP PowerShell?

Automate adding, updating, or removing navigation links
Maintain consistent structure across all associated sites
Improve user experience with well-organized navigation

Prerequisites

Before running PowerShell commands:

Install PnP PowerShell (if not installed)

Install-Module -Name PnP.PowerShell -Force -AllowClobber

Connect to SharePoint Admin Center

Connect-PnPOnline -Url "https://yourtenant-admin.sharepoint.com" -Interactive

Ensure permissions

You must be a SharePoint Admin or Site Collection Administrator
The site must be registered as a Hub Site

Step 1: Register a Hub Site

If your site is not already a hub site, register it using:

Register-PnPHubSite -Site "https://yourtenant.sharepoint.com/sites/YourHubSite"

Registers the site as a hub site.

To verify existing hub sites:

Get-PnPHubSite

Step 2: Add a Navigation Link to Hub Site

To add a new link to hub site navigation:

Add-PnPNavigationNode -Title "HR Portal" -Url "https://yourtenant.sharepoint.com/sites/HR" -Location TopNavigationBar

Adds “HR Portal” to the hub site’s top navigation.

For sub-menu links under an existing node:

$parent = Add-PnPNavigationNode -Title "Departments" -Url "#" -Location TopNavigationBar
Add-PnPNavigationNode -Title "IT Department" -Url "https://yourtenant.sharepoint.com/sites/IT" -Parent $parent

Creates a Departments menu with IT Department as a sub-item.

Step 3: Update an Existing Navigation Link

To modify an existing navigation link:

Set-PnPNavigationNode -Identity "HR Portal" -Title "HR Resources" -Url "https://yourtenant.sharepoint.com/sites/HRResources"

Renames “HR Portal” to “HR Resources” and updates its link.

Step 4: Remove a Navigation Link

To delete a navigation link:

Remove-PnPNavigationNode -Identity "HR Portal"

Removes the HR Portal link from navigation.

To remove all navigation links:

$links = Get-PnPNavigationNode -Location TopNavigationBar
foreach ($link in $links) {
    Remove-PnPNavigationNode -Identity $link.Id
}

Clears all hub site navigation links.

Step 5: Applying Navigation to Multiple Hub Sites

If you manage multiple hub sites, apply the same navigation structure across all sites:

$hubSites = @("https://yourtenant.sharepoint.com/sites/Hub1", "https://yourtenant.sharepoint.com/sites/Hub2")

foreach ($hub in $hubSites) {
    Connect-PnPOnline -Url $hub -Interactive
    Add-PnPNavigationNode -Title "Company News" -Url "https://yourtenant.sharepoint.com/sites/News" -Location TopNavigationBar
}

Ensures all hub sites have a common navigation link.

Step 6: Automating Hub Site Navigation Updates

You can automate weekly updates using a scheduled PowerShell script:

$logPath = "C:\Logs\HubNavigationLog_$(Get-Date -Format 'yyyyMMdd').txt"

function Update-HubNavigation {
    param ($siteUrl, $title, $url)

    Connect-PnPOnline -Url $siteUrl -Interactive
    Add-PnPNavigationNode -Title $title -Url $url -Location TopNavigationBar
    "[$(Get-Date)] Added navigation link '$title' to $siteUrl" | Out-File -Append -FilePath $logPath
}

$hubSites = @("https://yourtenant.sharepoint.com/sites/Hub1", "https://yourtenant.sharepoint.com/sites/Hub2")

foreach ($hub in $hubSites) {
    Update-HubNavigation -siteUrl $hub -title "IT Support" -url "https://yourtenant.sharepoint.com/sites/ITSupport"
}

Logs navigation changes for future reference.

Step 7: Verifying Navigation Changes

To check the current navigation structure:

Get-PnPNavigationNode -Location TopNavigationBar | Select Title, Url

Displays all hub site navigation links.

Troubleshooting Issues

1️⃣ Navigation Not Updating?

Ensure you have Admin permissions
Run Update-Module PnP.PowerShell to get the latest version

2️⃣ Error Connecting to Hub Site?

Check if the site is registered as a hub site using Get-PnPHubSite
Verify SharePoint Admin Center access