Skip to content

README.md

Latest commit

 

History

History
104 lines (73 loc) · 3.4 KB

README.md

File metadata and controls

104 lines (73 loc) · 3.4 KB

ICP CLI Documentation

This directory contains the source documentation for ICP CLI, written in Markdown.

Structure

docs/
├── index.md              # Homepage
├── tutorial.md           # Getting started tutorial
├── guides/               # How-to guides
├── concepts/             # Conceptual explanations
├── reference/            # Technical reference
├── migration/            # Migration guides
└── schemas/              # JSON schemas (not rendered)

Writing Documentation

Each Markdown file needs minimal YAML frontmatter with a title and description:

---
title: Your Page Title
description: A brief summary of what this page covers.
---

Content here...

Starlight renders the title as the page's H1 heading, so do not add a separate # Heading in the content.

Best Practices

  • Use standard Markdown — keep it simple and GitHub-friendly
  • Always include title and description in frontmatter
  • Use relative links with .md extensions: [text](./other-doc.md) (works on GitHub; a rehype plugin strips .md at build time)
  • Use .md files (not .mdx) for better GitHub rendering
  • Code blocks with language: ```bash
  • Use em dashes (—) to separate list item subjects from descriptions: - **Term** — Description

Generated Documentation

Some docs are auto-generated from code:

  • reference/cli.md — Generated by scripts/generate-cli-docs.sh from CLI command definitions
  • schemas/*.json — Generated by scripts/generate-config-schemas.sh from Rust types

Run these scripts when command-line options or config types change.

Build Process

The documentation website is built using Astro + Starlight. Starlight reads directly from the docs/ directory via a glob content loader — no preprocessing step is needed.

A rehype plugin (docs-site/plugins/rehype-rewrite-links.mjs) rewrites .md links at build time so that relative links with .md extensions work on both GitHub and the documentation site.

Preview

On GitHub

Docs are rendered automatically when browsing on GitHub. The directory structure provides natural navigation.

Local Preview

See the documentation website locally:

cd ../docs-site
npm run dev

This starts a Starlight site at http://localhost:4321 that reads from this docs/ directory.

Deployment

The documentation website is automatically built and deployed to GitHub Pages:

Adding New Documentation

  1. Create a .md file in the appropriate directory
  2. Add YAML frontmatter with title and description
  3. Write standard Markdown content (no H1 heading — Starlight renders the title)
  4. Add the page to the sidebar in ../docs-site/astro.config.mjs under the appropriate section: 
    {
  label: 'Guides',
  items: [
    { label: 'Your New Guide', slug: 'guides/your-new-guide' },
    // ...
  ],
}

Directory Guidelines

  • guides/ — Task-oriented, step-by-step instructions
  • concepts/ — Understanding-oriented explanations
  • reference/ — Information-oriented specifications
  • migration/ — Version or tool migration guides

This follows the Diátaxis documentation framework.