---
title: Links
slug: cms-12/docs/links
docTags: 
createdAt: 2026-08-10T15:55:57.000Z
---

In Optimizely Content Management System (CMS), internal links are stored in an internal permanent format, meaning you can rename files and templates and change host names without affecting the links.

## Content

CMS does not store links in HTML but instead stores permanent link references. When you access a reference through a property, CMS resolves the reference to an actual link so you see an HTML link in the content. When you save the content, the property parses the HTML and stores a permanent link.

:::hint{type="info"}
**Note**
You can paste a permanent URL into a web browser for debugging.
:::

CMS preserves additional URL segments and query parameters (after the content-specifying part of the URL) when it converts a permanent link. So, you can link to a specific action on a controller (potentially with parameters) or something routed by a partial router. A registered route must match the URL.

## Built-in properties

Many of the built-in types, such as `Url` (corresponding to `PropertyUrl` and `PropertyImageUrl` properties), `XHtmlString` (corresponding to `PropertyXhtmlString`) and `LinkItemCollection` (corresponding to `PropertyLinkItemCollection`) support permanent links. However, the basic **string** (corresponding to `ProperyString` or `PropertyLongString`) does not support permanent links because it may contain formats other than HTML. Use the `XhtmlString` for HTML content to make use of permanent links.

## Track link integrity

When you save a content instance, CMS parses the properties (such as `PropertyUrl`, `PropertyXhtmlString`, `PropertyLinkItemCollection`, and `PropertyContentArea`) for links to other content instances or files, and stores the references in a reference table to track the items that link to each other.

## Export and import

The export package contains links in a permanent format when transferring content. It makes sure links within the package are preserved during import. If you must use links other than the built-in ones (for example, if you have a custom property not based on any of the ones listed in the previous section), you must handle the conversion during export or import.

## API references

The `EPiServer.Core.Transfer.IReferenceMap` interface on your `PropertyData` object tells Optimizely that you need to handle permanent links. The `PermanentLinkMapper` handles conversion between permanent links and dynamic links. Access the API using the `EPiServer.Web.PermanentLinkUtility` class. The `EPiServer.Web.IPermanentLinkMapper` and `EPiServer.Web.PermanentLinkMap` classes are underlying components in the `PermanentLink` architecture, and you typically do not need to access them directly.

## Content links references

Permanent links to content consist of the GUID associated with content, also available as the property `IContent.ContentGuid`.

**Definition** – `~/link/ContentGUID.extension?EXTRAINFO`.