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

• @algorandfoundation/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 @algorandfoundation/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 a .env file in the project root. Run source .env before running import commands.

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 matter is used for page metadata

Example:

---
title: Your Page Title
description: Page description for SEO
---

Your content here...

Images and Assets

• Images: Place in src/assets/ and reference with relative paths
• Icons: SVG icons go in src/icons/ for use with astro-icon
• Static assets: Place in public/ directory (e.g., favicons)

Importing External Documentation

The project uses @algorandfoundation/astro-github-loader to import documentation from external repositories. Configure imports in imports/configs/. See the documentation for details on how to configure external documentation imports.

Contributing

See the CONTRIBUTING.md guide for detailed information on how to submit changes.

Development Workflow

1. Create a feature branch
2. Make your changes
3. Run pnpm run lint:fix to ensure code quality
4. Test locally with pnpm run build
5. Submit a pull request

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct.

Useful Links

• Starlight Documentation
• Astro Documentation
• Algorand Developer Portal
• Algorand Foundation

Deployment

This project is currently served via Cloudflare. In addition to serving statically generated pages of styled HTML, the deployment also leverages their ability to serve pages as markdown upon request by content negotiation headers. This is particularly useful for AI agents with limited context window sizes, as page content rendered as markdown can be 80-98% smaller than the original HTML markup.

This feature is enabled by a rule configured in the Cloudflare dashboard under Rules --> Overview --> rule named "Serve docs to agents as markdown".

One can quickly see the difference in content by requesting a page with/without the Accept: text/markdown header.

curl https://dev.algorand.co/getting-started/portal-guide/ \
  -H "Accept: text/markdown" | wc -c

License

See LICENSE for more information.