Vanity URLs

Simple but powerful URL redirects.

Statamic allows you to quickly set up vanity URLs, which let you quickly forward one URL to another.

As an example of when these might be used: perhaps your site is running a promotion but you want to use a short, catchy URL on your marketing campaign. Rather than having to tell someone something like /events/2013-log-cutting-championships-afterparty, you could create a /party vanity URL which will forward to your event detail page.

Defining Vanity URLs

All vanity URLs are defined in the vanity.yaml file within your _config directory. Statamic comes with a vanity.yaml.sample file to give you an example of what a file might look like. Feel free to rename this to vanity.yaml and use this file, or to create your own.

Vanity URLs are simply a YAML file with instructions on how to forward specific URLs. There are two ways to define a vanity URL.

Simple Redirects

The simple redirect takes a URL that someone is going to type in, and the URL that the user should be forwarded to. It will look something like this:

/party: /my-long/page-name

This will forward http://yoursite.com/party to http://yoursite.com/my-long/page-name. Simple.

Detailed Redirects

A detailed redirect lets you set a couple of configuration options for more fine-grained control over how your redirect works. This is an example of a full detailed redirect:

/party:
    start: "May 1, 2013 11:30pm"
    until: "May 5, 2013 12:00am"
    forward_query_string: true
    url: /my-long/page-name
    type: 302

As you can see, you can be much more specific with how and when vanity URLs work. Of the parameters listed above, only url is required. The rest work as follows:

• start is the date that the redirect starts working; leaving this empty will cause forwarding to have started
• until is the date that the redirect stops working; leaving this empty will cause the forwarding to not end until you remove this entry
• forward_query_string will merge the query string passed to the redirect along to the final URL — this can be helpful for tracking campaigns; false by default
• url is the URL to forward people to
• type is the type of redirect to perform, either 301 for a permanent redirect, or 302 for a temporary redirect; 302 by default

Best Practices

While it’s possible to create permanent redirects with the vanity URLs feature, it’s best practice to do this via an .htaccess file or similar method. Vanity URL redirects are going to be slower than server-level redirects (although the difference may not be noticeable in all situations).