|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: "Subdomains with GitHub Pages" |
| 4 | +--- |
| 5 | + |
| 6 | +Hey, it's possible to use subdomains with GitHub Pages. |
| 7 | + |
| 8 | +This website `mapsam.com` is hosted at [github.com/mapsam/mapsam.github.io](https://github.com/mapsam/mapsam.github.io) but sometimes I want to put another site at `something.mapsam.com` rather than the standard `mapsam.com/something` location. This allows me to work on other sites without thinking about relative or absolute URIs and incorrectly writing a CSS or JS file path. It's great for single page applications and not buying new domains, plus you can avoid getting squatted on popular domains like Tom Macwright mentions in [this post](https://macwright.com/2024/10/16/domain-second-thoughts). |
| 9 | + |
| 10 | +This assumes your domain A records are pointing to GitHub's IP addresses already. I use Namepcheap for my domain registration. You can find a working example at [sub.mapsam.com](https://sub.mapsam.com), the source is at [github.com/mapsam/sub](https://github.com/mapsam/sub). |
| 11 | + |
| 12 | +### Create a CNAME file in your repository |
| 13 | + |
| 14 | +Commit this to your repo with the full subdomain value. |
| 15 | + |
| 16 | +``` |
| 17 | +sub.mapsam.com |
| 18 | +``` |
| 19 | + |
| 20 | +### Create a CNAME Record on your domain |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +The CNAME record will exist alongside your A records. The host should be your subdomain `sub` and the value should be your github pages endpoint `mapsam.github.io.`. You can dig the domain to verify the DNS has propogated and shows up in the answer section. |
| 25 | + |
| 26 | +```sh |
| 27 | +dig sub.mapsam.com |
| 28 | +``` |
| 29 | + |
| 30 | +``` |
| 31 | +; <<>> DiG 9.10.6 <<>> sub.mapsam.com |
| 32 | +;; global options: +cmd |
| 33 | +;; Got answer: |
| 34 | +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 2831 |
| 35 | +;; flags: qr rd ra; QUERY: 1, ANSWER: 5, AUTHORITY: 0, ADDITIONAL: 1 |
| 36 | +
|
| 37 | +;; OPT PSEUDOSECTION: |
| 38 | +; EDNS: version: 0, flags:; udp: 512 |
| 39 | +;; QUESTION SECTION: |
| 40 | +;sub.mapsam.com. IN A |
| 41 | +
|
| 42 | +;; ANSWER SECTION: |
| 43 | +sub.mapsam.com. 1799 IN CNAME mapsam.github.io. |
| 44 | +mapsam.github.io. 3600 IN A 185.199.111.153 |
| 45 | +mapsam.github.io. 3600 IN A 185.199.108.153 |
| 46 | +mapsam.github.io. 3600 IN A 185.199.109.153 |
| 47 | +mapsam.github.io. 3600 IN A 185.199.110.153 |
| 48 | +
|
| 49 | +;; Query time: 96 msec |
| 50 | +;; SERVER: 75.75.75.75#53(75.75.75.75) |
| 51 | +;; WHEN: Sun Nov 10 22:40:44 PST 2024 |
| 52 | +;; MSG SIZE rcvd: 137 |
| 53 | +``` |
| 54 | + |
| 55 | +### Enable pages on your repo, check DNS |
| 56 | + |
| 57 | +Going to `Repo >> Settings >> Pages` and select your preferred deployment settings. In [github.com/mapsam/sub](https://github.com/mapsam/sub) I'm just using the "Deploy from a branch" classic settings, which uses Jekyll directly from the `main` branch. |
| 58 | + |
| 59 | + |
| 60 | + |
| 61 | +On the same page verify the DNS has been set to the proper value, and that it has been verified. This took about 10 minutes for the first ever subdomain I set up, and only a minute or so for subsequent domains. Even before GitHub can verify the DNS, the propogation is enabled and will work. Verifying the DNS will then allow you to enable HTTPS and get a TLS certificate issued. |
| 62 | + |
| 63 | + |
| 64 | + |
| 65 | +You should be all set after this. 👍 |
0 commit comments