Skip to content

docs: make icp CLI primary, add deprecation banners for dfx pages#6228

Closed
artkorotkikh-dfinity wants to merge 1 commit intomasterfrom
fix/icp-cli-primary-retire-dfx-default
Closed

docs: make icp CLI primary, add deprecation banners for dfx pages#6228
artkorotkikh-dfinity wants to merge 1 commit intomasterfrom
fix/icp-cli-primary-retire-dfx-default

Conversation

@artkorotkikh-dfinity
Copy link
Copy Markdown
Contributor

Summary

This PR fixes the P0 docs issue identified in the ICP presence audit: every new developer landing on docs.internetcomputer.org was being routed through the legacy dfx CLI with no mention of icp.

Changes

  • install.mdxicp CLI is now the primary install path (npm install -g @icp-sdk/icp-cli); dfx moved to a clearly-labelled ## IC SDK (dfx) — legacy section with a caution admonition and link to the migration guide
  • dev-tools-overview.mdx — added icp CLI section first with "recommended" framing; demoted dfx section to legacy with caution admonition linking to cli.internetcomputer.org/docs/migration; CDK section description de-coupled from dfx-specific wording
  • docusaurus.config.js — added cli.internetcomputer.org as the first item in the Resources nav dropdown so the icp CLI is discoverable from every docs page
  • src/theme/DocItem/Layout/index.js — new Docusaurus theme swizzle that injects a deprecation banner on every /developer-tools/dfx/* page: "⚠️ Heads up: dfx is the legacy CLI. New projects should use the icp CLI instead. View the dfx → icp migration guide →"

What this fixes

Before After
Install page: dfx install / dfx --version as primary, no icp mention Install page: icp CLI primary at top; dfx demoted to legacy section
dev-tools-overview: dfx described as "the primary tool", icp-cli not listed dev-tools-overview: icp CLI listed first as recommended; dfx as legacy
Every dfx command page: no deprecation notice Every dfx/* page: yellow banner → icp CLI + migration guide
Resources nav: no link to cli.internetcomputer.org Resources nav: icp CLI link added

Note on dfx command reference pages

The dfx command reference pages (e.g. dfx deploy, dfx canister, etc.) live in the submodules/sdk git submodule. The deprecation banner injected via DocItem/Layout covers all of these pages without requiring changes to the submodule.

Test plan

  • yarn build passes without errors
  • /building-apps/getting-started/install shows icp CLI section before dfx section
  • /building-apps/developer-tools/dev-tools-overview shows icp CLI section first with recommended tag
  • Any /building-apps/developer-tools/dfx/* page shows the yellow deprecation banner
  • Resources dropdown in nav includes icp CLI link to cli.internetcomputer.org

🤖 Generated with Claude Code

- install.mdx: icp CLI is now the primary install path (npm install -g @icp-sdk/icp-cli); dfx moved to a clearly-labelled legacy section with a migration callout
- dev-tools-overview.mdx: icp CLI section added first with recommended tag; dfx section demoted to legacy with caution admonition; CDK section description updated to remove dfx-specific wording
- docusaurus.config.js: add cli.internetcomputer.org to the Resources nav dropdown so the icp CLI is discoverable from every page
- src/theme/DocItem/Layout/index.js: inject deprecation banner on every /developer-tools/dfx/* page pointing to cli.internetcomputer.org and the migration guide

Fixes: every new developer was being routed through the wrong CLI. This is the P0 docs fix identified in the ICP presence audit.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
@artkorotkikh-dfinity artkorotkikh-dfinity requested a review from a team as a code owner April 16, 2026 21:11
@github-actions github-actions bot added the documentation Changes to Developer Docs label Apr 16, 2026
@artkorotkikh-dfinity artkorotkikh-dfinity marked this pull request as draft April 16, 2026 21:11
@raymondk
Copy link
Copy Markdown
Contributor

@artkorotkikh-dfinity I'm not sure if it's worth spending time on this

We're working on - https://beta-docs.internetcomputer.org/ coming out of https://github.com/dfinity/developer-docs
And it might be easier to swap them out.

@artkorotkikh-dfinity
Copy link
Copy Markdown
Contributor Author

Makes sense @raymondk ! Marko reached out to me, and I gave the context that it was not fully intentional. Was experimenting with agents, and this one was a bit too proactive... Sorry for the noise and looking forward to the new portal!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Changes to Developer Docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants