Algorand Developer Portal

The official Algorand Developer Portal - a comprehensive documentation site for Algorand blockchain developers.

Table of Contents

• Prerequisites
• Quick Start
• Project Structure
• Key Dependencies
• Available Commands
• Configuration
• Content Management
• Contributing

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18+) - JavaScript runtime
• pnpm (v10.6+) - Fast, disk space efficient package manager
• D2 - Diagram scripting language for generating diagrams

Quick Start

1. Clone the repository

   git clone https://github.com/algorandfoundation/devportal.git
   cd devportal
   

2. Install D2 diagram binary

   brew install d2
   

   See D2 docs for other installation options.

3. Install dependencies

   pnpm install
   

4. Start the development server

   pnpm run dev
   

   The site will be available at http://localhost:4321

Project Structure

.
├── .github/
│   └── workflows/          # CI/CD workflows
├── examples/               # Code examples
│   ├── algokit/           # AlgoKit examples
│   └── smart-contracts/   # Smart contract examples
├── imports/
│   ├── configs/           # GitHub loader import configurations
│   └── transforms/        # Content transformation utilities
├── public/                # Static assets (favicons, etc.)
├── scripts/               # Build and utility scripts
│   ├── clean-docs-import.ts       # Clear imported documentation
│   ├── generate-opcode-list.js    # Generate Algorand opcodes list
│   ├── manage-sidebar-meta.js     # Sidebar management
│   └── prose-check.ts             # AI-powered prose quality checker
├── src/
│   ├── assets/            # Images and media files
│   ├── components/        # Reusable Astro/React components
│   ├── content/
│   │   ├── docs/          # Documentation markdown files
│   │   └── config.ts      # Content collections configuration
│   ├── icons/             # Custom SVG icons
│   ├── styles/
│   │   └── global.css     # Global styles and Tailwind customizations
│   └── utils/             # Utility functions
├── templates/             # Handlebars templates for generated content
├── astro.config.mjs       # Astro configuration
├── package.json           # Project dependencies and scripts
├── tailwind.config.mjs    # Tailwind CSS configuration
└── tsconfig.json          # TypeScript configuration

Key Dependencies

Core Framework

• Astro - Modern static site builder
• @astrojs/starlight - Documentation framework built on Astro
• React - UI component library for interactive elements

Styling

• Tailwind CSS - Utility-first CSS framework
• @astrojs/starlight-tailwind - Tailwind integration for Starlight
• @catppuccin/vscode - Code theme

Content & Documentation

• @larkiny/astro-github-loader - Import documentation from GitHub repositories
• starlight-openapi - OpenAPI/Swagger documentation
• starlight-auto-sidebar - Automatic sidebar generation
• astro-d2 - D2 diagram integration

Utilities

• octokit - GitHub API client
• marked - Markdown parser
• js-yaml - YAML parser
• sharp - Image processing

Development Tools

• TypeScript - Type-safe JavaScript
• ESLint - Code linting
• Prettier - Code formatting

Available Commands

All commands are run from the root of the project:

Development

| Command | Description | | ------------------ | ------------------------------------------ | | pnpm run dev | Start local dev server at localhost:4321 | | pnpm run start | Alias for pnpm run dev | | pnpm run build | Build production site to ./dist/ | | pnpm run preview | Preview production build locally |

Code Quality

| Command | Description | | ------------------- | -------------------------------------- | | pnpm run lint | Run ESLint, Prettier, and Astro checks | | pnpm run lint:fix | Fix linting issues automatically |

Content Generation

| Command | Description | | ------------------------------- | --------------------------------------- | | pnpm run generate-opcode-list | Generate Algorand opcodes documentation |

Content Import

Documentation is imported from external GitHub repositories using @larkiny/astro-github-loader. Import configurations are defined in imports/configs/.

| Command | Description | | ------------------------- | ------------------------------------------------------------------- | | pnpm run import:docs | Import all content from GitHub, regenerate sidebar, and fix linting | | pnpm run import:force | Force re-import all content, ignoring cache | | pnpm run import:dry-run | Preview GitHub content imports without making changes | | pnpm run import:clear | Remove all imported documentation content |

Auto-Sidebar Management

The starlight-auto-sidebar plugin enables you to customize the order and appearance of auto-generated sidebar entries, including cascading frontmatter configuration to files within a folder. The following commands enable you to quickly generate the _meta.yml files from the config defined in auto-sidebar-config.yml.

| Command | Description | | ---------------------------- | --------------------------------------- | | pnpm run sidebar:generate | Clean and regenerate sidebar metadata | | pnpm run sidebar:update | Update existing sidebar metadata | | pnpm run sidebar:overwrite | Overwrite all sidebar metadata | | pnpm run sidebar:preview | Preview sidebar changes without writing |

Astro CLI

| Command | Description | | -------------------------- | ------------------------------------------ | | pnpm run astro ... | Run Astro CLI commands (e.g., astro add) | | pnpm run astro -- --help | Get help for Astro CLI |

Configuration

Environment Variables

The following environment variables can be configured:

| Variable | Description | Default | | ---------------- | ------------------------------------------------ | ------- | | GITHUB_TOKEN | GitHub API token (required for importing docs) | - | | IMPORT_GITHUB | Enable GitHub content import | false | | IMPORT_DRY_RUN | Preview imports without writing files | false | | FORCE_IMPORT | Force re-import, ignoring cache | false |

Set these in your shell or use your preferred environment management tool.

Astro Configuration

The main Astro configuration is in astro.config.mjs. Key configurations include:

• Starlight settings - Site title, sidebar, social links
• Content collections - Documentation structure
• Integrations - React, Tailwind, D2, OpenAPI, etc.

Tailwind Configuration

Customize Tailwind in tailwind.config.mjs. Additional custom styles can be added to src/styles/global.css.

Content Management

Writing Documentation

1. Documentation files are stored in src/content/docs/
2. Use .md or .mdx format
3. Files are automatically routed based on their path
4. Front ma