Associate multiple sites to a Hubsite using PowerShell PnP

Hubsites have been announced at Microsoft Ignite in 2017, and provide a way to display content from multiple sites (once they’re connected) with same branding, and also a search functionality across all connected sites.

In today’s post, we’ll see how to use PowerShell PnP (Patterns & Practices) to associate teams and/or communication sites to a hubsite.
You can have a total of 100 hubsites per tenant, and there’s no maximum in the number of sites that can be connected.

[Update: June, 5th 2019]: As announced at SPC19, the limit for hubsites per tenant is now 2000 and rolling out soon!

Create & Register your hubsite

Microsoft recommends a modern Team Site or Communication site as a hubsite (template) instead of a “classic” team site. That is, if you want to avoid a poor experience…
First, create the site using the New-PnPSite, and then convert it as a hubsite using the Register-PnPHubSite cmdlet.

In this scenario, I have created a new site under the URL https://<TENANT_NAME>.sharepoint.com/sites/companyevents using the Communication site template.

Now that the site is accessible, we need to register it (convert it into a hubsite).
This is pretty straight forward. Run Register-PnPHubsite -Site https://<TENANT_NAME>.sharepoint.com/sites/companyevents and it’s now converted 😎

Hubsite registered

If you have the new SPO Admin Center, look under the “Hubsite association” column…

Site converted

Set permissions for specific users

In this section, we will set permissions for some users to be the ONLY ONES who can associate sites with this hubsite.
This is optional, but recommended.

Grant-PnPHubSiteRights -Identity https://<TENANT_NAME>.sharepoint.com/sites/companyevents -Principals "user1@mydomain.com","user2@mydomain.com" -Rights Join

For the -Rights parameter, you have the choice between Join or None.

To check if those rights have been applied correctly, run:

Get-PnPHubsite -Identity <Site_Url> | Select-Object Permissions

Hubsite permissions applied

Associate sites with the Hubsite

Now’s the time to associate our teams and/or communication sites to the newly converted hubsite.

Let’s imagine that we have dozens of sites we wish to link, you could use a Csv file for example. Here I’ve got 3 sites, but I’m sure you got the picture 😉

List of sites to associate

$Sites = Import-Csv -Path "C:\users\$env:USERNAME\Desktop\SitesToAssociate.csv"
$myHubsite = "https://<TENANT_NAME>.sharepoint.com/sites/companyevents"

foreach ($site in $Sites) {
    Add-PnPHubSiteAssociation -Site $site.SiteUrl -HubSite $myHubsite
}

Now to check what sites have been associated to a Hubsite, run the Get-PnPHubsiteAssociation. Wait… 🤔 Can’t find this one….
Indeed, at this point in time (Nov. 2018), there’s no PnP or SPO cmdlets for checking which sites are associated with a Hubsite.

However, if you have the modern SPO admin center, you can check the “Hubsite association” column, it will tell you if your site is associated or not, and with which hubsite.

Associated with Hubsite

💡 Another way could be to use the “Site” webpart in the Hubsite.

“Sites” Webpart