Aptos Docs

This repository contains the source code for the official Aptos Developer Documentation, built using Astro and Starlight.

Quick Start

# Clone the repository
git clone https://github.com/aptos-labs/aptos-docs.git
cd aptos-docs

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env

# Start the development server
pnpm dev

Visit http://localhost:4321 to see the documentation running locally.

Editing Documentation

The main documentation content is located in the src/content/docs/ directory:

• Content is organized in directories that match the URL structure
• Files are written in Markdown MDX (.mdx) format
• Each file begins with frontmatter (metadata between --- delimiters)

Example frontmatter:

---
title: Your Page Title
description: A brief description of the page content
---

For more resources on authoring content within this environment, see:

• Authoring Content in Markdown
• Using Components

With the development server running (pnpm dev), your changes will be reflected immediately.

Prerequisites

• Node.js: Version 22.x (specified in .nvmrc, use nvm)
• pnpm: Version 10.2.0 or higher (npm install -g pnpm)
• Git: For cloning the repository

Key Features

• Multi-language support
• Interactive components (GraphiQL editor, Testnet Faucet)
• API Reference via OpenAPI specifications
• Move Reference documentation
• Search functionality (Algolia DocSearch, with Pagefind as a fallback)
• Dynamic OG Images

Common Commands

Command	Description
pnpm dev	Start the development server
pnpm build	Build the site for production
pnpm preview	Preview the production build
pnpm lint	Check for linting issues
pnpm format	Fix formatting issues
pnpm check:search	Report which search provider will ship

Environment Variables

Key environment variables:

Variable	Type	Purpose	Required?
GITHUB_TOKEN	Secret	Fetching Move Reference docs	Only if ENABLE_MOVE_REFERENCE=true
ENABLE_API_REFERENCE	Public	Build REST API reference pages	Optional (default: false)
ENABLE_MOVE_REFERENCE	Public	Build Move Reference docs	Optional (default: false)
Firebase Credentials	Public	Authentication features	Required for Faucet/Auth
Algolia Credentials	Public	Documentation search	Optional
SEARCH_PROVIDER	Public	Force algolia or pagefind	Optional (default: auto)
GTAG_ID	Public	Google Analytics tracking	Optional
OG_IMAGES_SECRET	Secret	Dynamic OG image generation	Recommended for Vercel

Search

The site ships Algolia DocSearch only when a build can prove the configured Algolia index serves results, and uses Starlight's built-in Pagefind search otherwise. Pagefind indexes the built HTML and runs entirely in the browser, so search keeps working when a deleted Algolia application, a rotated search key, an index the crawler never populated, or an unreachable Algolia would otherwise leave the site with an empty search modal.

Run pnpm check:search to see which provider the current environment would ship and, when Algolia is unhealthy, what needs fixing. Set SEARCH_PROVIDER=algolia or SEARCH_PROVIDER=pagefind to bypass the probe.

Project Structure

.
├── config/                 # Global sidebar configuration helper
├── patches/                # Patched npm dependencies
├── public/                 # Static assets
├── scripts/                # Utility scripts (Migration & Middleware generation)
├── src/
│   ├── assets/             # Site assets
│   ├── components/         # Reusable components
│   ├── config/             # Configuration helpers (i18n, docSearch, sidebar)
│   ├── content/            # Content Collections
│   │   ├── docs/           # Main documentation content
│   │   ├── i18n/           # UI translations
│   │   └── nav/            # Sidebar translations
│   ├── integrations/       # Custom integrations
│   ├── lib/                # Utility functions
│   ├── loaders/            # Content Collection loaders
│   ├── middlewares/        # Edge Middleware
│   ├── pages/              # Astro pages
│   ├── plugins/            # Remark/Rehype plugins
│   ├── starlight-overrides/ # Overridden components
│   ├── stores/             # State management
│   ├── styles/             # CSS styles
│   └── utils/              # General utilities
└── Various config files    # Configuration files

Configuration Files

File	Purpose
.env.example	Example environment variables
astro.config.mjs	Main configuration
astro.sidebar.ts	Documentation sidebar structure
package.json	Project dependencies and scripts
vercel.json	Vercel deployment configuration and redirects

Redirects

Redirects are handled in ./vercel.json for optimal performance. This approach ensures redirects are processed at the CDN level before middleware logic runs, providing faster response times for users and less potential for conflicts.

The vercel.json file contains all URL redirects with the following structure:

{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ]
}

Benefits of CDN-level redirects:

• Performance: Redirects are handled at the edge, closest to users
• Speed: No server-side processing or middleware execution required
• Efficiency: Bypasses i18n middleware and other application logic
• Reliability: Reduces server load and potential points of failure

When adding new redirects, always update the vercel.json file rather than implementing them in middleware to maintain optimal performance.

For more information on configuring redirects, see the Vercel redirects documentation.

Technologies Used

Category	Technology	Description
Framework	Astro	Web framework for content-driven sites
Docs Framework	Starlight	Documentation toolkit for Astro
Styling	Tailwind CSS	Utility-first CSS framework
UI Components	React	UI library (via Astro Islands)
Package Manager	pnpm	Fast, disk space efficient package manager
Search	Algolia DocSearch	Documentation search (Pagefind fallback)
Authentication	Firebase	Auth and backend services
Deployment	Vercel	Hosting platform

Contributing

• Ensure code adheres to ESLint rules (pnpm lint)
• Format code using Prettier (pnpm format)