Versioned Docs in 30 Seconds with Amplify Console's Branch Subdomains
Tags: aws, inthirtyseconds
Published: 2020-06-26 16:34:09

---
title: Versioned Docs in 30 Seconds with Amplify Console's Branch Subdomains
published: true
description: Amplify Console just got the ability to create a custom subdomain for every new branch. This makes creating versioned docs a cinch!
tags: AWS, inthirtyseconds
cover_image: https://user-images.githubusercontent.com/6764957/85811265-36283600-b790-11ea-8832-1110e6d0d60e.png
slug: amplify-console-branch-subdomains
canonical_url: https://www.swyx.io/writing/amplify-console-branch-subdomains
---

> Amplify Console [just got the ability](https://aws.amazon.com/about-aws/whats-new/2020/06/amplify-console-adds-support-for-automatically-creating-deleting-custom-sub-domains-for-every-branch-deployment/) to create a custom subdomain for every new branch. This makes creating versioned docs a cinch! Let me try to explain it in 30 seconds.

Let's say you have your docs hosted on an existing Amplify site ([get one here](https://docs.amplify.aws/start)) at `https://www.my-library.com/`. You can turn custom subdomain branch deployments (and automatic deletion) on in 3 clicks:

![image](https://user-images.githubusercontent.com/6764957/85810347-5c98a200-b78d-11ea-9c75-3d75c470c34a.png)

I have chosen to enable this feature just for branches that start with `v`, so `v1`, `v2.1`, `v2.0-alpha3`, etc all work, but a `feat/my-new-pr` or `patch-1` branch don't cause a build.

Now, whenever I cut a new release, I can `git checkout -b v3` to create a new branch and push it up to GitHub. Amplify Console will see that and generate a permanent subdomain with that branch's name. Now I can keep developing on my main branch, but my docs for `v3` will always live at `https://v3.my-library.com/`! 

**That's it!!** Versioned docs are a highly demanded feature for open source libraries. Because this is based on git branches, I can move and delete files, and *even completely change site generators* without ever affecting my old docs. **Now you have no excuse not to have versioned docs!**

---

See my example [11ty](http://11ty.io/) docs site here: 

- Main: https://main.d7jllnhqfi58b.amplifyapp.com/
- v1.1: https://v1-1.d7jllnhqfi58b.amplifyapp.com/
- v2: https://v2.d7jllnhqfi58b.amplifyapp.com/
- v3: https://v3.d7jllnhqfi58b.amplifyapp.com/
- Source: https://github.com/sw-yx/test-eleventy/


You can fork and deploy my example with this nifty button: 
[![amplifybutton](https://oneclick.amplifyapp.com/button.svg)](https://console.aws.amazon.com/amplify/home#/deploy?repo=https://github.com/sw-yx/test-eleventy)

---

P.S. Pro tip - you don't have to manually update the version numbers inside the docs yourself. Since I name the branches after the exact version number, I can make use of [Amplify Console's provided environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html#amplify-console-environment-variables) which give me the `AWS_BRANCH`, which I can use inside my docs site generator to always make sure that the docs reflect the accurate version!

This is how I set it up [in my demo project](https://github.com/sw-yx/test-eleventy/tree/main):

![image](https://user-images.githubusercontent.com/6764957/85811429-b9e22280-b790-11ea-94bb-8c4787a4b47c.png)

which becomes...

![image](https://user-images.githubusercontent.com/6764957/85811265-36283600-b790-11ea-8832-1110e6d0d60e.png)