refactor(reference): split ic-interface-spec into 7 focused sub-pages#188
Merged
refactor(reference): split ic-interface-spec into 7 focused sub-pages#188
Conversation
Replaces the 483 KB monolith docs/reference/ic-interface-spec.md with a docs/reference/ic-interface-spec/ directory containing one page per major section of the spec: index.md — Introduction, Pervasive concepts, System state tree https-interface.md — HTTPS Interface canister-interface.md — Canister module format + System API management-canister.md — Management canister + Bitcoin + Provisional APIs certification.md — Certification + HTTP Gateway protocol abstract-behavior.md — Abstract behavior (formal state machine) changelog.md — Changelog All 204 heading anchors remapped; cross-file (#anchor) references updated to (./target.md#anchor) via split_ic_interface_spec.py. Abstract behavior carries a note directing application developers to practical sections. Fixes page-size-markdown and page-size-html afdocs check failures (#181). Also updates: - docs/reference/index.md: link to ic-interface-spec/index.md - AGENTS.md (CLAUDE.md): sync checklist updated with section-to-file map - .docs-plan/decisions.md: decision recorded
- 4 depth bugs in split files: cycles-costs.md (×3 in canister-interface.md) and bitcoin.mdx (management-canister.md) needed extra path level - 16 bare links to deleted ic-interface-spec.md across concepts/, guides/, and reference/ — each routed to the correct sub-page - 10 anchor links in http-gateway-spec.md updated to new sub-page paths; absolute /references/ URLs converted to relative ./ic-interface-spec/ paths - 6 stale links in internet-identity-spec.md (missed in review) - Link replacement comments updated throughout to reflect new paths
… and internet-identity-spec Both files contain manually adapted links pointing into the split ic-interface-spec/ sub-pages. Without explicit guidance, agents syncing these files would not know to convert portal/upstream absolute URLs to the correct relative sub-page paths. Adds: - Step 3 (http-gateway-spec) expanded with link adaptation step and grep command to detect newly introduced ic-interface-spec links - internetidentity per-submodule table row updated with note reference - New link adaptation block for internet-identity-spec.md with the same detection command and anchor lookup fallback
- certification.md: fix wrong-depth link ./http-gateway-spec.md → ../http-gateway-spec.md - abstract-behavior.md: remove banned em-dash in :::note admonition - changelog.md: add missing 0.59.0 entry (sender_info / msg_caller_info_* / list_canisters) - CLAUDE.md: clarify changelog source is _attachments/interface-spec-changelog.md, not ic-interface-spec.md; add git log command for that file
…ection, not spec index
raymondk
previously approved these changes
May 4, 2026
…r 0 so changelog is last
…ke https-interface/ are not treated as external
…name Reference to References
…with link to /reference/ic.did
… nav consistency - Move all 16 reference pages and ic-interface-spec/ subdirectory - Update all 75 internal links across 42 files - Update sidebar.mjs slugs and autogenerate directory - Update AGENTS.md paths, project structure, and section list - Update .docs-plan/decisions.md paths - Build verified: 159 pages, 0 errors
…r file was touched
raymondk
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/reference/ic-interface-spec.mdmonolith withdocs/reference/ic-interface-spec/containing 7 focused pages, one per major section(#anchor)references updated to(./target.md#anchor)byscripts/split_ic_interface_spec.pyabstract-behavior.md(formal state machine notation, 207 KB) carries a note directing application developers to the practical sectionspage-size-markdownandpage-size-htmlafdocs check failures from issue infra: agent-friendly docs spec v0.5.0 compliance gaps #181Page mapping
index.mdhttps-interface.mdcanister-interface.mdmanagement-canister.mdcertification.mdabstract-behavior.mdchangelog.mdAlso updated
docs/reference/index.md: link updated toic-interface-spec/index.mdAGENTS.md/CLAUDE.md: portal bump sync checklist updated with section-to-file mapping table so future portal diffs can be applied to the correct file.docs-plan/decisions.md: decision recorded with rationale and sync guidanceSync recommendation
informed by dfinity/portal — docs/references/ic-interface-spec.md