docs: publish the site at docs.sogeor.com

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://github.com/sogeor/docs/security/advisories/new
     about: Report vulnerabilities privately, not in public issues.
   - name: Documentation site
-    url: https://sogeor.github.io/docs/
+    url: https://docs.sogeor.com/
     about: Platform overview, deployment guide, ADRs and runbooks.

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
       link-args: >-
         --exclude-path docs/repos
         --exclude '^https://github\.com/sogeor/[^/]+/(security|issues/new)'
-        --exclude '^https://sogeor\.github\.io/docs'
+        --exclude '^https://docs\.sogeor\.com'
         --exclude '^https?://127\.0\.0\.1'
 
   site:

CHANGELOG.md

@@ -25,3 +25,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Site aggregates `.github` v0.3.0; repository status table updated (`.github` v0.3.0, `workflows` v0.1.1, `modules` in progress).
 - Pinning guidance: annotated tags are pinned by the peeled commit SHA.
 - Renovate proposes versions only 7 days after release (`minimumReleaseAge`); pins of aggregated repositories in `sources.yaml` are exempt.
+- Site address is `https://docs.sogeor.com/` (`site_url`, README, issue template, link check exclusion); setup and troubleshooting pages describe the custom domain, DNS-only record and HTTPS.

README.md

@@ -14,7 +14,7 @@ End-to-end documentation of the sogeor DevSecOps platform and the source of its
 - "Deploy everything": one guide from an empty account to a working platform.
 - Platform ADRs ([MADR](https://adr.github.io/madr/)), runbooks, threat models, postmortems and exercises.
 - Aggregates the `docs/` directory of every platform repository, pinned by tag and SHA.
-- Builds and publishes the site to GitHub Pages: <https://sogeor.github.io/docs/>.
+- Builds and publishes the site to GitHub Pages: <https://docs.sogeor.com/>.
 
 ## How it works
 

ROADMAP.md

@@ -10,7 +10,6 @@ Horizon: through Q4 2027. Order follows the sogeor platform plan.
 - Platform ADRs for every foundational decision.
 - "Deploy everything" guide from an empty account to a working platform, completed as repositories are released.
 - Runbooks (including incident response), threat models, postmortem and exercise templates.
-- Custom domain `docs.sogeor.com`.
 
 ## Not planned
 

docs/about/configuration.md

@@ -36,7 +36,7 @@ Base site configuration. `tools/aggregate.py` writes `mkdocs.generated.yml`, whi
 
 | Key | Value | Notes |
 |---|---|---|
-| `site_url` | `https://sogeor.github.io/docs/` | Change in a fork or when a custom domain is added |
+| `site_url` | `https://docs.sogeor.com/` | Address of the published site; change it in a fork ([Custom domain](setup.md#custom-domain)) |
 | `strict` | `true` | Any warning fails the build |
 | `validation` | all `warn` | Broken links, unknown anchors, pages outside `nav` fail the strict build |
 | `theme.features` | tabs, sections, indexes, code copy | No edit button: aggregated pages belong to other repositories |

docs/about/setup.md

@@ -15,7 +15,7 @@ features work. Steps are in order; each ends with a check.
 | Field | Value |
 |---|---|
 | Description | `Documentation of the sogeor DevSecOps platform: overview, cluster constructor, network, security and compliance, platform ADRs, runbooks and threat models, with pinned docs of every platform repository built into one MkDocs site.` |
-| Website | `https://<owner>.github.io/docs/` (later the custom documentation domain) |
+| Website | `https://docs.sogeor.com/` (in a fork: your custom domain or `https://<owner>.github.io/docs/`) |
 | Topics | `documentation` `mkdocs` `mkdocs-material` `github-pages` `devsecops` `platform-engineering` `architecture-decision-records` `adr` `runbooks` `threat-modeling` `kubernetes` `gitops` `infrastructure-as-code` `supply-chain-security` `compliance` |
 | Include in the home page | Releases — off until the first release; Deployments — on; Packages — off |
 
@@ -76,9 +76,22 @@ Check: the **Security** tab shows **Report a vulnerability**.
 
 Check: **Settings → Pages** shows **Your site is live at `https://<owner>.github.io/docs/`**.
 
-!!! note "Custom domain"
-    A custom domain is configured later: **Settings → Pages → Custom domain**, plus a `CNAME` DNS record
-    pointing to `<owner>.github.io`, and `site_url` in `mkdocs.yml`.
+### Custom domain
+
+The reference site uses `docs.sogeor.com`. In a fork, replace `docs.example.com` with your domain.
+
+1. In your DNS provider, create a record: type `CNAME`, name `docs`, target `<owner>.github.io`.
+   In Cloudflare: **DNS → Records → Add record**, **Proxy status: DNS only** (grey cloud).
+2. **Settings → Pages → Custom domain:** `docs.example.com` → **Save**. Wait for **DNS check successful**.
+3. When the certificate is issued (up to an hour), enable **Enforce HTTPS**.
+4. Set `site_url: https://docs.example.com/` in `mkdocs.yml` and the domain in the `lychee` exclusion of
+   `.github/workflows/docs.yml`; merge the change so `pages` republishes the site.
+
+Check: `https://docs.example.com/` opens the home page, and `https://<owner>.github.io/docs/` redirects to it.
+
+!!! warning "Keep the record DNS only"
+    With the Cloudflare proxy (orange cloud) enabled, GitHub cannot issue the certificate and
+    **Enforce HTTPS** stays unavailable. See [Troubleshooting](troubleshooting.md#custom-domain-returns-404-or-https-is-unavailable).
 
 ## Renovate
 

docs/about/troubleshooting.md

@@ -40,6 +40,20 @@
 **Cause:** the entry does not match the expected order `url`, `ref`, `sha` on consecutive lines.
 **Fix:** keep the key order from [Configuration](configuration.md#sourcesyaml).
 
+## Custom domain returns 404 or HTTPS is unavailable
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The home page returns `404 There isn't a GitHub Pages site here`, while other pages work; the response has a large `Age` header | The CDN of GitHub Pages cached a 404 from before the first deployment | Run **Actions → pages → Run workflow** on `master`, or wait 10–20 minutes; reload with cache bypass |
+| **Enforce HTTPS** is unavailable: *domain is not properly configured to support HTTPS* | The DNS record is proxied by Cloudflare, so GitHub cannot issue the certificate | Set the record to **DNS only**, wait up to an hour, then enable **Enforce HTTPS** |
+| `sitemap.xml` and canonical links point to the old address | `site_url` in `mkdocs.yml` was not changed | Set `site_url` to the custom domain |
+
+Check the response headers:
+
+```bash
+curl -sS -o /dev/null -D - https://docs.example.com/
+```
+
 ## Pages deployment fails with `Branch "…" is not allowed to deploy to github-pages`
 
 **Cause:** the environment allows only `master`.

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: sogeor platform
 site_description: Documentation of the sogeor DevSecOps platform
-site_url: https://sogeor.github.io/docs/
+site_url: https://docs.sogeor.com/
 repo_url: https://github.com/sogeor/docs
 repo_name: sogeor/docs
 copyright: Copyright © sogeor. Licensed under Apache-2.0.