Documentation site¶

This site is built with MkDocs Material and deployed to HomeCloud SO static website hosting.

URL: https://docs.web.holab.abrdns.com

How it works¶

flowchart LR
  Push[git push main] --> CI[GitHub Actions]
  CI --> Build[mkdocs build]
  Build --> Sync[homecloud so sync]
  Sync --> Bucket[so://docs/]
  Bucket --> Web[docs.web.holab.abrdns.com]

One-time homelab setup¶

1. Create bucket `docs`¶

Console → Storage → Create bucket → name: docs

2. Enable static website¶

Console → bucket docs → Website tab:

Setting	Value
Enabled	✓
Index document	`index.html`
Error document	`404.html`

MkDocs Material generates index.html and 404.html automatically.

3. Public read (website)¶

Bucket policy — allow public so:GetObject:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": ["so:GetObject"],
      "Resource": ["arn:holab:so:::docs/*"]
    }
  ]
}

4. CI Access Key¶

Create IAM Access Key with:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["so:ListBucket", "so:PutObject", "so:DeleteObject"],
      "Resource": ["arn:holab:so:::docs", "arn:holab:so:::docs/*"]
    }
  ]
}

5. GitHub secrets (`homecloud-docs` repo)¶

Secret	Value
`HOMECLOUD_ACCESS_KEY_ID`	`HCAK…`
`HOMECLOUD_SECRET_ACCESS_KEY`	secret
`HOMECLOUD_APEX`	`holab.abrdns.com`

Local development¶

pip install -r requirements.txt
mkdocs serve
# → http://127.0.0.1:8000  (English)
# → http://127.0.0.1:8000/he/  (Hebrew)

Source pages live under docs/en/ and docs/he/ (Hebrew falls back to English when a page is not translated yet). Theme and chrome match the HomeCloud console (docs/stylesheets/homecloud.css).

Manual deploy¶

mkdocs build
homecloud so sync ./site so://docs/ --delete

Crawlers and LLMs¶

The site ships discovery files at the bucket root (synced with each deploy):

Path	Purpose
`/robots.txt`	Allow crawl + point at sitemap
`/sitemap.xml`	Full URL inventory (MkDocs)
`/llms.txt`	Compact index for AI assistants (llmstxt.org)

SO static website returns HTTP 404 (with 404.html body) for missing paths — not a soft 404 with status 200.

CI workflow¶

See .github/workflows/deploy.yml — runs on every push to main.