Versioned Docs in 30 Seconds with Amplify Console's Branch Subdomains

Amplify Console just got the ability 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) at https://www.my-library.com/. You can turn custom subdomain branch deployments (and automatic deletion) on in 3 clicks:

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 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:

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 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:

which becomes…