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

[swyxio]

---

source: devto
devToUrl: "https://dev.to/swyx/versioned-docs-in-30-seconds-with-amplify-console-s-branch-subdomains-4k73"
devToReactions: 31
devToReadingTime: 2
devToPublishedAt: "2020-06-26T16:34:09.932Z"
devToViewsCount: 215
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 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...