1# custom domains
2
3any folder on sublimated can have its own domain. two options: a `*.sublimated.com` subdomain or your own custom domain.
4
5## sublimated subdomain
6
7claim a subdomain like `kanapka.sublimated.com` for any folder.
8
9option 1 — add to `.sbl/config.yml` in the folder:
10
11```yaml
12subdomain: kanapka
13```
14
15push the file and the subdomain is live immediately.
16
17option 2 — use the settings UI on sublimated.com (folder settings > domains).
18
19option 3 — API:
20
21```bash
22curl -X POST https://api.sublimated.com/v1/spaces/yourspace/subdomains \
23  -H "Authorization: Bearer $TOKEN" \
24  -H "Content-Type: application/json" \
25  -d '{"subdomain": "kanapka", "url_path": "sites/kanapka"}'
26```
27
28subdomain rules: 3-63 chars, lowercase alphanumeric and hyphens, no leading/trailing hyphens.
29
30## custom domain
31
32use your own domain (e.g. `mysite.com`) for any folder.
33
34option 1 — add to `.sbl/config.yml`:
35
36```yaml
37domain: mysite.com
38```
39
40option 2 — use settings UI or API.
41
42after adding the domain, set up DNS:
43
441. add a CNAME record pointing your domain to `run.sublimated.com`
452. if you want `www.mysite.com` too, add a CNAME for `www` pointing to `run.sublimated.com`
46
47```
48mysite.com     CNAME  run.sublimated.com
49www.mysite.com CNAME  run.sublimated.com
50```
51
52SSL is provisioned automatically via Cloudflare. verification usually completes in a few minutes.
53
54you can check domain status in the settings UI or via API:
55
56```bash
57curl https://api.sublimated.com/v1/spaces/yourspace/domains \
58  -H "Authorization: Bearer $TOKEN"
59```
60
61## which folders support domains?
62
63any folder that serves web content: zola sites, mdx pages, or any folder with an `index.html`. the domain maps to the folder — all files inside are served under that domain.
64
65## live example
66
67[kanapka.sublimated.com](https://kanapka.sublimated.com) — a zola food blog with a sublimated subdomain.