docs: add Starlight documentation site and reorganize containerized networks guide

.github/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thank you for your interest in contributing to the Response Verification package for the Internet Computer.
+Thank you for your interest in contributing to icp-cli for the Internet Computer.
 By participating in this project, you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md).
 
 As a member of the community, you are invited and encouraged to contribute by submitting issues, offering suggestions for improvements, adding review comments to existing pull requests, or creating new pull requests to fix issues.
@@ -77,3 +77,109 @@ If you want to submit a pull request to fix an issue or add a feature, here's a
 11. Wait for the pull request to be reviewed.
 12. Make changes to the pull request, if requested.
 13. Celebrate your success after your pull request is merged!
+
+## Contributing to Documentation
+
+The documentation lives in the `docs/` directory and is deployed to https://dfinity.github.io/icp-cli/.
+
+### Documentation Structure
+
+Documentation follows the [Diátaxis framework](https://diataxis.fr/):
+- `docs/guides/` - Task-oriented how-to guides
+- `docs/concepts/` - Understanding-oriented explanations
+- `docs/reference/` - Information-oriented technical specifications
+- `docs/migration/` - Migration guides (e.g., from dfx)
+
+### How Documentation is Built
+
+The documentation site uses [Astro](https://astro.build/) with [Starlight](https://starlight.astro.build/):
+
+1. **Source files** (`docs/`) are plain Markdown without frontmatter
+2. **Build script** (`scripts/prepare-docs.sh`) runs before each build and:
+   - Copies docs to `.docs-temp/` directory (excluding schemas and READMEs)
+   - Adjusts relative paths and strips `.md` extensions for Starlight's clean URLs
+   - Extracts titles from H1 headings and adds frontmatter
+3. **Starlight** reads from `.docs-temp/` and builds the site
+4. **GitHub Actions** automatically deploys to GitHub Pages on push to main
+
+This architecture keeps source docs clean and GitHub-friendly while providing a polished documentation site.
+
+### Writing Documentation
+
+1. **Create a markdown file** in the appropriate directory:
+   ```bash
+   # Example: Add a new guide
+   touch docs/guides/my-new-guide.md
+   ```
+
+2. **Start with an H1 heading** (used as the page title):
+   ```markdown
+   # My New Guide
+
+   Content here...
+   ```
+
+3. **Use plain Markdown** - No frontmatter needed in source files:
+   - Standard GitHub-flavored Markdown
+   - Relative links with `.md` extension: `[text](./other-doc.md)`
+   - Code blocks with language: ` ```bash `
+   - The build process handles transformations automatically
+
+4. **Add to the sidebar** - Update `docs-site/astro.config.mjs`:
+   ```js
+   sidebar: [
+     {
+       label: 'Guides',
+       items: [
+         { label: 'My New Guide', slug: 'guides/my-new-guide' },
+         // ...
+       ],
+     },
+   ]
+   ```
+
+   Note: The sidebar must be manually updated because Starlight's autogenerate feature doesn't work with Astro's glob loader.
+
+5. **Preview your changes locally**:
+   ```bash
+   cd docs-site
+   npm install  # First time only
+   npm run dev
+   ```
+   Opens the site at http://localhost:4321
+
+### Generated Documentation
+
+Some documentation is auto-generated:
+
+- **CLI reference** (`docs/reference/cli.md`) - Run `./scripts/generate-cli-docs.sh` when commands change
+- **Config schemas** (`docs/schemas/*.json`) - Run `./scripts/generate-config-schemas.sh` when manifest types change
+
+These scripts should be run before committing changes to code that affects CLI commands or configuration types.
+
+### Documentation Guidelines
+
+- **Keep it simple** - Plain Markdown is easier to maintain and renders well on GitHub
+- **Be concise** - Users value clear, direct explanations
+- **Use examples** - Show concrete code examples rather than abstract descriptions
+- **Test your examples** - Make sure code examples actually work
+- **Link related docs** - Help users discover related content
+- **Follow Diátaxis** - Place content in the correct category:
+  - **Tutorial**: Learning-oriented, takes users by the hand
+  - **Guides**: Task-oriented, shows how to solve specific problems
+  - **Concepts**: Understanding-oriented, explains how things work
+  - **Reference**: Information-oriented, technical descriptions
+
+### Documentation Pull Requests
+
+When submitting a documentation PR:
+- Ensure the sidebar in `docs-site/astro.config.mjs` is updated if adding new pages
+- Preview the site locally before submitting
+- Check that all links work (both in GitHub and on the site)
+- Follow the Diátaxis framework for placing content in the right section
+- Verify your examples work by testing them
+- Run `./scripts/prepare-docs.sh` locally to check for build errors
+
+For more details on the documentation system, see:
+- [docs/README.md](../docs/README.md) - Documentation writing guide
+- [docs-site/README.md](../docs-site/README.md) - Technical documentation site details

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'docs-site/**'
+      - 'scripts/prepare-docs.sh'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'docs-site/**'
+      - 'scripts/prepare-docs.sh'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+
+      - name: Setup Node
+        uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./docs-site
+        run: npm ci
+
+      - name: Build documentation site
+        working-directory: ./docs-site
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: ./docs-site/dist
+
+  # Deployment job - only runs on main branch
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -13,3 +13,9 @@
 # often-used binaries
 pocket-ic
 icp-cli-network-launcher
+
+# Documentation build artifacts
+docs-site/.astro/
+docs-site/dist/
+docs-site/node_modules/
+docs-site/.docs-temp/

README.md

@@ -31,10 +31,14 @@ If you're coming from dfx (the previous Internet Computer SDK), see the **[Migra
 
 ## Documentation
 
+📚 **[Full Documentation Site](https://dfinity.github.io/icp-cli/)** — Complete guides, tutorials, and reference
+
+Or browse the markdown docs directly:
+
 - **[Tutorial](docs/tutorial.md)** — Deploy your first canister
-- **[Guides](docs/guides/index.md)** — How to accomplish common tasks
-- **[Concepts](docs/concepts/index.md)** — Understand how icp-cli works
-- **[Reference](docs/reference/index.md)** — Complete CLI and configuration reference
+- **[Guides](docs/guides/)** — How to accomplish common tasks
+- **[Concepts](docs/concepts/)** — Understand how icp-cli works
+- **[Reference](docs/reference/cli.md)** — Complete CLI and configuration reference
 
 ## Examples
 
@@ -65,7 +69,9 @@ The [`examples/`](examples/) directory contains example projects to help you get
 
 ## Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for detailed guidelines.
+
+### Development Quick Start
 
 ### Prerequisites
 
@@ -99,13 +105,35 @@ cargo run -- <command>
 cargo build --release
 # Binary is at target/release/icp
 
+# Format and lint
+cargo fmt && cargo clippy
+
 # Generate CLI docs (after changing commands)
 ./scripts/generate-cli-docs.sh
 
 # Update config schemas (after changing manifest types)
 ./scripts/generate-config-schemas.sh
 ```
 
+### Working with Documentation
+
+```bash
+# Preview documentation site locally
+cd docs-site && npm install && npm run dev
+# Opens at http://localhost:4321
+
+# Prepare docs for build (runs automatically during build)
+./scripts/prepare-docs.sh
+```
+
+Documentation structure follows the [Diátaxis framework](https://diataxis.fr/):
+- [`docs/guides/`](docs/guides/) - Task-oriented how-to guides
+- [`docs/concepts/`](docs/concepts/) - Understanding-oriented explanations
+- [`docs/reference/`](docs/reference/) - Information-oriented specifications
+- [`docs/migration/`](docs/migration/) - Migration guides
+
+See [docs/README.md](docs/README.md) for documentation writing guidelines.
+
 ## License
 
 [Apache-2.0](LICENSE)