Skip to content

docs: migrate hosting from GitHub Pages to IC asset canister#439

Merged
marc0olo merged 3 commits intomainfrom
docs/migrate-to-ic-asset-canister
Mar 17, 2026
Merged

docs: migrate hosting from GitHub Pages to IC asset canister#439
marc0olo merged 3 commits intomainfrom
docs/migrate-to-ic-asset-canister

Conversation

@marc0olo
Copy link
Member

@marc0olo marc0olo commented Mar 17, 2026

Closes #438

What this does

Moves docs hosting from dfinity.github.io/icp-cli/ to an IC asset canister at https://cli.internetcomputer.org.

Key changes:

  • Removes /icp-cli/ base path prefix — URLs are now cli.icp.build/0.2/... instead of dfinity.github.io/icp-cli/0.2/...
  • docs.yml now pushes built assets to docs-deployment branch instead of gh-pages
  • New docs-deploy.yml workflow deploys docs-deployment to the IC asset canister on every push to that branch
  • IC config files added: icp.yaml, .ic-assets.json5, .well-known/ic-domains

Already done (pre-merge):

  • docs-deployment branch bootstrapped from gh-pages (path rewrites applied, IC config added)
  • First deploy to ak73b-maaaa-aaaad-qlbgq-cai already triggered — verify at https://ak73b-maaaa-aaaad-qlbgq-cai.icp0.io

Before merging

  • Verify https://ak73b-maaaa-aaaad-qlbgq-cai.icp0.io looks correct (all versions, version switcher, links)
  • Confirm the IC mainnet GitHub environment exists with the DFX_IDENTITY_DESIGN_TEAM secret — the docs-deploy.yml workflow requires it
  • DNS is configured separately (CNAME cli.internetcomputer.orgicp1.io)

After merging

The first push to main will rebuild and redeploy all content. gh-pages is not modified by this PR — leave it untouched until the new deployment is confirmed working. Once confirmed, replace gh-pages with redirect pages (/icp-cli/*cli.icp.build/*) as described in #438.

⚠️ Do not merge until the canister URL is verified

The docs-deployment branch and canister already exist. Merging only changes what CI does going forward — it does not affect the already-deployed content.

- Remove /icp-cli/ base prefix from astro config and version switcher
- Add IC asset canister config (icp.yaml, .ic-assets.json5, .well-known/ic-domains)
- Add docs-deploy.yml workflow to deploy docs-deployment branch to IC mainnet
- Update docs.yml to push built assets to docs-deployment instead of gh-pages
- Update VERSIONED_DOCS.md, CONTRIBUTING.md, and README with new deployment info

The docs-deployment branch has been bootstrapped from gh-pages (path rewrites
applied) and is already deployed to ak73b-maaaa-aaaad-qlbgq-cai.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@marc0olo marc0olo requested a review from a team as a code owner March 17, 2026 14:45
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@marc0olo
Copy link
Member Author

Post-merge: rebuild old version docs

After merging, the /0.1/ and /0.2/ folders on docs-deployment still have cli.icp.build baked into their canonical URLs (from the bootstrap). They won't be rebuilt automatically by a push to main.

Fix by triggering a rebuild for each old version:

# Rebuild /0.1/
git push origin docs/v0.1

# Rebuild /0.2/ (branch doesn't exist yet, create from latest tag)
git checkout v0.2.1-beta.0  # or latest v0.2.x tag
git checkout -b docs/v0.2
git push origin docs/v0.2

Each push triggers docs.yml → rebuilds the version with cli.internetcomputer.org → deploys via docs-deploy.yml.

@marc0olo marc0olo merged commit 764ce2a into main Mar 17, 2026
92 checks passed
@marc0olo marc0olo deleted the docs/migrate-to-ic-asset-canister branch March 17, 2026 20:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Migrate docs hosting from GitHub Pages to IC asset canister

2 participants