In Optimizely Content Management System (CMS), internal links are stored in an internal permanent format meaning you can rename files and templates, 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.

📘

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`/`PropertyLongString`) does not support permanent links because it may contain formats other than HTML. Use the XhtmlString for all HTML content to make use of permanent links.

### Link integrity tracking

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 link format when you are transferring content. It makes sure links within the package are preserved during import. If you need to use any other links 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 have to handle the conversion during export/import yourself.

### API references

The `EPiServer.Core.Transfer.IReferenceMap` interface on your `PropertyData` object tells CMS 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 a content, also available as the property `IContent.ContentGuid`.

**Definition** – _~/link/ContentGUID.extension?EXTRAINFO_