Why and when you should be using relative links in SharePoint

Consider either of these scenarios:

Re-branding/Restructuring/Renaming

• Your organization and its departments are re-structuring and changing names
• Your IT department and content strategists decide on a new naming convention that affects your site names and URLs to access those sites OR you’re changing from http to https
• You have hundreds (thousands?) of documents, links, content queries and script references across your sites that refer to the old URLs and are now broken

Copying Sites/Structures or Creating Templates

• You need to create a team site template that contains default content and page designs
• You create the template with script references, page and promoted links that are absolute
• You have to update all of those links (some perhaps buried deep in your layouts folder) to the new site location URL unless those links are meant to call back to a different site.

Keep in mind that if a user doesn’t have access to the site or subsite library where referenced scripts are held, those scripts won’t run for that user no matter what. This can affect the look, feel, and function of the site which causes confusion and confidence issues when they call and you say “Looks fine to me!” and they have a different experience

Many of these issues and “cleanup tasks” can be avoided (for the most part) by using relative URLs instead of absolute URLs.

What’s the difference?

Absolute URLs contain your site’s domain (contoso.com) and point specifically to an item in an exact location.

“https://sharepoint.contoso.com/sites/HR/Documents”

Relative URLs do not contain your domain and typically include just the destination name of an item that exists on the same web app where the link is placed. The following example, from any site or subsite in the collection, would take you to the top-level site’s “Documents” library if it existed.

“/Documents”

Or, if the item you’re referring to is on a subsite or different subsite, it would need to contain that level of the URL as well, but still be relative because it’s not looking back to the domain. So if you copied the HR site to a different site collection, the links would still work, assuming the content stayed in tact.

“/sites/HR/Documents”

You can imagine in the absolute URL example OR the third example of a link to an item from a different site collection within the web app, if the site “HR” changed its path to “HumanResources” all of the absolute URLs and relative URLs that contained “HR” are now broken.

That being said: Relative URLs are best used for “short-range” linking (i.e. a script referenced in a CEWP on a subsite’s home page and the script is stored in the same subsite). The further your destination is from the link location, the higher your risk of broken links or errors down the road.

Then what’s so great about relative URLs?

There’s a case to be made for using both types of URLs in different scenarios, but in SharePoint where we’re not worried so much about SEO, I consider it a “better” practice to use Relative URLs where possible within a single web app. Even better, within a single site collection.

Relative URLs don’t break when you:

• Change a SharePoint site collection top-level site URL
• Change a SharePoint subsite name and URL
• Copy a subsite to a different site collection
• Make a subsite a template with default content and use it repeatedly
• Replicate to a dev/test environment. You want those links to be relative, and not referring to production sites via absolute URL

Relative URLs also allow your page to load faster (though by a mere fraction of a percent).

Keep in mind that all of these benefits are conditional on the type of relative URL you’re creating. If you’re creating a “long-range” relative URL that includes the site collection URL piece then you’re at risk for broken links when the site collection URL changes. Best practice would be to keep relative URLs as short as possible.

The Good News

SharePoint will automatically convert absolute URLs to relative URLs for you! This happens when you:

• Create a link in a rich text/multi-line text field or content editor web part (upon saving/publishing, it will convert a full URL to just the necessary part:
• Use the “Add from SharePoint” options to browse for video, images, links, etc. Once selected it automatically provides the relative URL:

The Nitty-Gritty

/Documents vs Documents

Whenever you use a “/” at the front of a reference, it will resolve to include the document root of your site. Let’s say you’re currently on page https://sharepoint.contoso.com/HR/SitePages/Benefits.aspx and click each of these links:

Link	Destination
/Documents	https://sharepoint.contoso.com/Documents (root)
/HR/Documents	https://sharepoint.contoso.com/HR/Documents (subsite root)
Documents	https://sharepoint.contoso.com/HR/SitePages/Documents which fails (previous level, SitePages, root)

Note: If you’re using a hyperlink field in a default SharePoint form (like changing a navigation link) you must use /Documents or /HR/Documents. It’s only in your scripts and custom hyperlinks built in rich text/content editor parts you’d be able to use Documents with no slashes instead.

http:// and https://

Many people have intranets that might include both http:// and https:// areas. If you must use an absolute URL to access local resources, you could leave out http:// and https:// and start the reference with just //. This will look at your current page and if it’s “http://” it will add “http://” to the front of the URL. Or if you’re currently on an “https://” page and click a link reference starting with “//” it will resolve to “https://…”