From 5cc4bd960b27653064f2dc8b633bf82d12b60040 Mon Sep 17 00:00:00 2001
From: kiootic <kiootic@oursky.com>
Date: Wed, 29 Nov 2023 18:16:29 +0800
Subject: [PATCH] Update docs on custom domain

---
 docs/SUMMARY.md                       |  1 +
 docs/guides/features/custom-domain.md | 32 +++++++++++++++++++++++++++
 docs/references/configuration-file.md |  5 ++++-
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/features/custom-domain.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 06a1b4f..ab12945 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -16,6 +16,7 @@
     - [Automatic TLS](guides/features/automatic-tls.md)
     - [GitHub Actions Integration](guides/features/github-actions-integration.md)
     - [Access Control](guides/features/access-control.md)
+    - [Custom Domain](guides/features/custom-domain.md)
 
 # References
 
diff --git a/docs/guides/features/custom-domain.md b/docs/guides/features/custom-domain.md
new file mode 100644
index 0000000..76223df
--- /dev/null
+++ b/docs/guides/features/custom-domain.md
@@ -0,0 +1,32 @@
+# Custom Domains
+
+Pageship supports custom domains for serving pages for an app. We assume a
+cooperative model for custom domain association, so domain ownership
+verification is not required.
+
+To enable custom domain, configure `pageship.toml` and specify the site to serve
+from the domain:
+
+```toml
+# 2 sites for the app: 'main' & 'dev'
+[[app.sites]]
+name = "main"
+
+[[app.sites]]
+name = "dev"
+
+# For 'main' site, serve it at 'example.com'. Traffic to default domain is
+# redirected to the configured domain automatically.
+[[app.domains]]
+domain="example.com"
+site="main"
+```
+
+If the domain name is already in-use by other apps, the custom domain would not
+be activated automatically when first added to the configuration. It can be
+activated/deactivated manually using `pageship domains activate <domain name>`/
+`pageship domains deactivate <domain name>` command.
+
+Custom domains of the app can be listed with `pageship domains` command.
+Additional setup instruction (e.g. DNS setup) would be shown if provided by
+server operator.
diff --git a/docs/references/configuration-file.md b/docs/references/configuration-file.md
index e8a8e81..2e9b98b 100644
--- a/docs/references/configuration-file.md
+++ b/docs/references/configuration-file.md
@@ -24,7 +24,10 @@ server.
   subdomain.
 - `app.deployments`: Configuration for preview deployments
     - `access`: ACL rules controlling access of preview deployments.
-    - `ttl`: the lifetime of a preview deployment (default to `24h`)``
+    - `ttl`: the lifetime of a preview deployment (default to `24h`)
+- `app.domains`: Configuration for custom domains
+    - `domain`: The custom domain to use
+    - `site`: The site name associated the custom domain
 
 ### `site` section