ICP CLI Documentation Site

This directory contains the Starlight-based documentation website for ICP CLI.

Overview

The documentation site is built with Astro and Starlight, reading markdown files directly from the ../docs/ directory.

Architecture

docs-site/
├── astro.config.mjs       # Starlight configuration (sidebar, theme, SEO meta tags, JSON-LD)
├── versions.json          # Version registry (controls root redirect and robots.txt)
├── plugins/
│   ├── rehype-rewrite-links.mjs  # Rewrites .md links for Starlight's clean URLs
│   └── astro-agent-docs.mjs     # Generates llms.txt, feed.xml, og-image.png, sitemap lastmod
├── src/
│   ├── content.config.ts  # Content loader configuration
│   ├── components/        # Custom Starlight component overrides (Footer, Banner, SiteTitle)
│   ├── assets/            # Logo and static assets
│   └── styles/            # DFINITY theme CSS
├── public/
│   ├── og-image.svg       # Source SVG for the social sharing image (converted to PNG at build time)
│   └── ...                # Other static files (favicon, well-known, etc.)
└── package.json           # Dependencies and scripts

Key Features

Content Loading

Uses Astro's glob loader to read directly from ../docs/ (excluding schemas/ and README files)
Source docs use minimal YAML frontmatter (title + description)
A rehype plugin rewrites .md links at build time for Starlight's clean URLs

Build Pipeline

Starlight reads content directly from ../docs/ via the glob content loader
Rehype plugin (plugins/rehype-rewrite-links.mjs) strips .md extensions from relative links and adjusts paths for Astro's directory-based output
DFINITY theme CSS is applied for consistent branding
Static HTML is produced in dist/
astro-agent-docs plugin runs in the astro:build:done hook and generates additional files:
- llms.txt — LLM/agent-friendly page index (agentdocsspec.com)
- llms-full.txt — full content dump for RAG pipelines
- feed.xml — RSS 2.0 feed with git-accurate publish dates per page
- og-image.png — social sharing preview image, rendered from public/og-image.svg via @resvg/resvg-js
- Sitemap <lastmod> injection — adds git commit dates to the Starlight-generated sitemap

Source docs use .md extensions in links (GitHub-friendly), and the rehype plugin transforms them to clean URLs at build time.

Styling

Custom CSS for DFINITY branding
Files: layers.css, theme.css, overrides.css, elements.css
Maintains consistent look with other DFINITY documentation sites

External Links

External links automatically open in new tabs with security attributes (rel="noopener noreferrer")
Implemented via rehype-external-links plugin for content links
Custom script in astro.config.mjs handles social/header links

Global Banner

A feedback banner is shown on every page via a custom Banner component override (src/components/Banner.astro)
No per-page frontmatter needed — the component renders the same banner globally

Navigation

Sidebar is manually configured in astro.config.mjs
This is required because Starlight's autogenerate doesn't work with glob loaders
When adding new docs, update the sidebar configuration

Development

Prerequisites

npm install

Local Development

npm run dev

Opens the site at http://localhost:4321

Build for Production

npm run build

Outputs to ./dist/

Preview Production Build

npm run preview

Clean Build Artifacts

npm run clean

Removes dist/ and .astro/ directories

Scripts

dev - Cleans artifacts and starts development server
build - Builds for production
preview - Previews production build locally
clean - Removes build artifacts (dist/, .astro/)
test:versions - Simulates the full multi-version production layout locally for testing the version switcher UI

Deployment

The site is hosted on an IC asset canister and served at https://cli.internetcomputer.org.

Canister ID: ak73b-maaaa-aaaad-qlbgq-cai

How it works

.github/workflows/docs.yml builds documentation and pushes built files to the docs-deployment branch (one directory per version: 0.1/, 0.2/, main/, etc.)
.github/workflows/docs-deploy.yml is called by docs.yml after publish jobs complete and deploys the entire docs-deployment branch to the IC asset canister

Triggers

Push to main: Rebuilds /main/ docs and root files (index.html, versions.json, robots.txt, sitemap.xml, IC config). Also copies og-image.png, llms.txt, llms-full.txt, and feed.xml from the latest versioned deployment to the root.
Release tags (v*): Builds and deploys versioned docs (e.g., v0.2.0 → /0.2/). Also triggers delete-docs-branch.yml which automatically deletes the docs/v0.2 branch if one exists — preventing stale branches from re-deploying outdated content on accidental pushes.
Docs-override branches (docs/v*): Redeploys versioned docs for a specific minor version without cutting a new code release (e.g., docs/v0.2 → /0.2/). These branches are short-lived by design — created only for an immediate docs fix, then deleted automatically on the next release.

To trigger a re-deploy, create a fresh branch from the latest release tag and push your fix:
```
git fetch origin
git checkout -b docs/v0.2 v0.2.3   # start from the release tag, not stale state
git cherry-pick <commit-sha>        # commit must already be merged to main
git push origin docs/v0.2
```

Root-level files

Several files must live at the deployment root (not inside a versioned subfolder) to be discovered correctly:

robots.txt — generated dynamically by the CI publish-root-files job from versions.json; allows only the latest version's path, disallows old versions, and disallows /main/ (except when no releases exist yet and /main/ is the fallback). Never placed in versioned build output.
sitemap.xml — root sitemap index pointing directly to the latest version's sitemap-0.xml (spec-compliant: a sitemapindex must reference sitemaps, not other sitemapindex files); generated by publish-root-files.
og-image.png — the og:image meta tag always references https://cli.internetcomputer.org/og-image.png. The CI publish-root-files job copies it from the latest versioned build folder to root after each versioned deployment.
llms.txt / llms-full.txt — same pattern as og-image.png; publish-root-files prepends a version navigation header to the root llms.txt.
feed.xml — same pattern; copied from the latest versioned folder to root.

Legacy redirect

The old GitHub Pages site at https://dfinity.github.io/icp-cli/ redirects all paths to https://cli.internetcomputer.org/.

Configuration

Site Settings

In astro.config.mjs:

site: Base URL (https://cli.internetcomputer.org in production)
base: Version path (set via PUBLIC_BASE_PATH, e.g., /0.2/, /main/)
title, description: Site metadata
logo: ICP logo configuration
favicon: Site favicon
customCss: DFINITY theme files
markdown.rehypePlugins: Link rewriting and external link handling

Sidebar Configuration

Manual sidebar definition in astro.config.mjs:

sidebar: [
  {
    label: 'Section Name',
    items: [
      { label: 'Page Title', slug: 'path/to/page' },
      // ...
    ],
  },
  // ...
]

The slug should match the file path relative to docs/ without the .md extension.

Adding New Pages

Create a .md file in ../docs/ in the appropriate directory
Add YAML frontmatter with title and description
Write standard Markdown content (no H1 heading — Starlight renders the title)

Add the page to the sidebar in astro.config.mjs:

{
  label: 'Your Section',
  items: [
    { label: 'Your New Page', slug: 'section/your-new-page' },
    // ...
  ],
}

Troubleshooting

Sidebar shows no pages

Check that:

The file exists in ../docs/ with correct path
The file has YAML frontmatter with at least a title field
The slug in astro.config.mjs matches the file path (without .md)
You ran npm run dev to trigger the build process

Duplicate page titles