diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md index da5256c7..36c5811c 100644 --- a/.docs-plan/decisions.md +++ b/.docs-plan/decisions.md @@ -275,3 +275,10 @@ Record decisions that constrain future work — things an agent needs to know th **Rationale:** Dynamic SVG generation in the build plugin adds ~30 lines of complexity for a one-time change. Static is simpler and good enough. **Alternatives considered:** Generate SVG dynamically in `plugins/astro-agent-docs.mjs` using `siteUrl` from Astro config (more robust, but over-engineered for a single domain change) + +## 2026-04-28: Production domain cutover to docs.internetcomputer.org + +**Context:** The site was previously served from `beta-docs.internetcomputer.org` as a staging domain during the transition from `dfinity/portal`. The portal has now been retired and this site is the canonical ICP developer docs. +**Decision:** Switch all domain references from `beta-docs.internetcomputer.org` to `docs.internetcomputer.org`. Updated files: `astro.config.mjs` (site URL + og/twitter/schema.org meta), `public/robots.txt` (sitemap), `public/og-image.svg` (footer text), `README.md`, `AGENTS.md` (never-link rule + portal tracking section), `scripts/validate.js` (error messages). The `docs.internetcomputer.org` lint rule in validate.js is kept — it still enforces relative paths for internal links. +**Rationale:** The beta domain was always a temporary staging address. With the portal retired, `docs.internetcomputer.org` is the permanent home. +**Alternatives considered:** Keep beta domain as a redirect origin (handled at DNS/CDN level, not in code) diff --git a/AGENTS.md b/AGENTS.md index e5ffc880..cb581932 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,7 +141,7 @@ git checkout main - Write code snippets from memory — find and adapt from actual upstream code in `.sources/` - Modify the rationale or context of existing decisions in `.docs-plan/decisions.md` — you may remove entries that are fully reflected in the current codebase but never alter reasoning behind active decisions - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions -- Link to `internetcomputer.org/docs/` or `docs.internetcomputer.org` — those URLs will break. Link to pages in this site (relative paths), Learn Hub, or explain inline. +- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Link to Learn Hub or explain inline for external content. - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls ` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both). - Link externally when an internal page exists — check `docs/` before using an external URL - Offer, suggest, or perform PR reviews unless a human explicitly asks @@ -369,10 +369,7 @@ sidebar: ## Portal tracking -The old portal (`dfinity/portal`) is still live during the transition period. -- **Ignore:** dfx-only changes, JSX/component changes, release notes, NNS dapp guides -- **Flag for rewrite:** Content updates to topics we cover -- **Evaluate:** New content — does it belong in the new docs? +The old portal (`dfinity/portal`) has been replaced by this site. The `.sources/portal` submodule is kept as a read-only reference for spec content (see `ic.did` sync checklist above) but no longer needs active monitoring for content changes. ## Commands diff --git a/README.md b/README.md index fa12ddf6..89236d37 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,14 @@ # ICP Developer Docs -Developer documentation for the [Internet Computer](https://internetcomputer.org) — built with [Astro](https://astro.build) + [Starlight](https://starlight.astro.build), deployed at [beta-docs.internetcomputer.org](https://beta-docs.internetcomputer.org). +Developer documentation for the [Internet Computer](https://internetcomputer.org) — built with [Astro](https://astro.build) + [Starlight](https://starlight.astro.build), deployed at [docs.internetcomputer.org](https://docs.internetcomputer.org). ## Background -The existing ICP docs live at [internetcomputer.org/docs](https://internetcomputer.org/docs), sourced from [dfinity/portal](https://github.com/dfinity/portal) (Docusaurus). That site accumulated content over years without a consistent information architecture, making it hard to navigate and harder to keep accurate. - -This repo is a ground-up rewrite: a flat Diataxis structure (Getting Started, Guides, Concepts, Languages, Reference), content verified against pinned upstream repos, and a workflow built for both human contributors and AI coding agents from day one. +This repo is a ground-up rewrite of the ICP developer docs: a flat Diataxis structure (Getting Started, Guides, Concepts, Languages, Reference), content verified against pinned upstream repos, and a workflow built for both human contributors and AI coding agents from day one. It replaces the previous [dfinity/portal](https://github.com/dfinity/portal) (Docusaurus) site. ## Current state -Most pages are content-complete. A small number of pages remain as stubs (vetkeys, encryption). The existing production docs remain live during the transition. +Most pages are content-complete. A small number of pages remain as stubs (vetkeys, encryption). ## Content areas diff --git a/astro.config.mjs b/astro.config.mjs index 7d0a64f8..aa0f9f3e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -13,7 +13,7 @@ import { TITLE, DESCRIPTION, PUBLISHER, OG_ALT } from "./src/branding.mjs"; // https://astro.build/config export default defineConfig({ - site: "https://beta-docs.internetcomputer.org", + site: "https://docs.internetcomputer.org", markdown: { // Rehype plugins work with Starlight (remark plugins don't — Starlight overrides them). // See: https://github.com/dfinity/icp-cli/issues/423 @@ -61,7 +61,7 @@ export default defineConfig({ }, { tag: "meta", - attrs: { property: "og:image", content: "https://beta-docs.internetcomputer.org/og-image.png" }, + attrs: { property: "og:image", content: "https://docs.internetcomputer.org/og-image.png" }, }, { tag: "meta", @@ -69,7 +69,7 @@ export default defineConfig({ }, { tag: "meta", - attrs: { name: "twitter:image", content: "https://beta-docs.internetcomputer.org/og-image.png" }, + attrs: { name: "twitter:image", content: "https://docs.internetcomputer.org/og-image.png" }, }, { tag: "script", @@ -79,15 +79,15 @@ export default defineConfig({ "@graph": [ { "@type": "WebSite", - "@id": "https://beta-docs.internetcomputer.org/#website", + "@id": "https://docs.internetcomputer.org/#website", "name": TITLE, "description": DESCRIPTION, - "url": "https://beta-docs.internetcomputer.org", - "publisher": { "@id": "https://beta-docs.internetcomputer.org/#organization" }, + "url": "https://docs.internetcomputer.org", + "publisher": { "@id": "https://docs.internetcomputer.org/#organization" }, }, { "@type": "Organization", - "@id": "https://beta-docs.internetcomputer.org/#organization", + "@id": "https://docs.internetcomputer.org/#organization", "name": PUBLISHER, "url": "https://dfinity.org", }, diff --git a/public/.well-known/ic-domains b/public/.well-known/ic-domains index e8d4e654..d538f6f3 100644 --- a/public/.well-known/ic-domains +++ b/public/.well-known/ic-domains @@ -1 +1,2 @@ +docs.internetcomputer.org beta-docs.internetcomputer.org diff --git a/public/og-image.svg b/public/og-image.svg index 04b7eacb..578d5ae2 100644 --- a/public/og-image.svg +++ b/public/og-image.svg @@ -35,6 +35,6 @@ DFINITY Foundation · beta-docs.internetcomputer.org + font-size="17" font-weight="400" fill="#6e6660">DFINITY Foundation · docs.internetcomputer.org diff --git a/public/robots.txt b/public/robots.txt index 83f36293..b48933f2 100644 --- a/public/robots.txt +++ b/public/robots.txt @@ -1,8 +1,8 @@ User-agent: * Allow: / -Sitemap: https://beta-docs.internetcomputer.org/sitemap-index.xml +Sitemap: https://docs.internetcomputer.org/sitemap-index.xml # LLM and AI agent discovery (llmstxt.org) -# https://beta-docs.internetcomputer.org/llms.txt -# https://beta-docs.internetcomputer.org/llms-full.txt +# https://docs.internetcomputer.org/llms.txt +# https://docs.internetcomputer.org/llms-full.txt diff --git a/scripts/validate.js b/scripts/validate.js index e0b6b6f3..ff185ddf 100644 --- a/scripts/validate.js +++ b/scripts/validate.js @@ -44,8 +44,8 @@ function checkFrontmatter(file, content) { const FORBIDDEN = [ { re: /mo:base/, msg: '"mo:base" is banned — use "mo:core" instead' }, - { re: /internetcomputer\.org\/docs/, msg: 'internetcomputer.org/docs URLs will break — link internally or inline' }, - { re: /docs\.internetcomputer\.org/, msg: 'docs.internetcomputer.org URLs will break — link internally or inline' }, + { re: /internetcomputer\.org\/docs/, msg: 'internetcomputer.org/docs is retired — link internally or inline' }, + { re: /docs\.internetcomputer\.org/, msg: 'docs.internetcomputer.org is this site — use relative paths for internal links' }, ]; function checkEmdash(file, content) {