A GitHub pages site to host the AIPs

.github/workflows/aip-frontmatter.yml

@@ -0,0 +1,19 @@
+name: AIP Frontmatter Validation
+
+on:
+  pull_request:
+    paths:
+      - 'aips/**'
+
+jobs:
+  validate-frontmatter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Validate AIP frontmatter
+        run: node scripts/validate-frontmatter.mjs

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+name: Deploy Starlight to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        env:
+          GITHUB_ACTIONS: "true"
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,13 @@
 .idea
 notes.md
-.DS_Store
+.DS_Store
+
+# Astro/Starlight
+node_modules
+.astro
+dist
+.vercel
+.netlify
+.env
+.env.*
+package-lock.json

.npmrc

@@ -0,0 +1,2 @@
+auto-install-peers=true
+strict-peer-dependencies=false

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the Aptos Improvement Proposals (AIPs) repository, which contains the specification documents and website for the Aptos blockchain protocol improvements. It's an Astro-based static site generator using Starlight for documentation.
+
+## Development Commands
+
+Development server:
+```bash
+npm run dev
+npm start  # alias for dev
+```
+
+Build and validation:
+```bash
+npm run build  # runs astro check then astro build
+npm run check  # type checking and validation
+```
+
+Preview built site:
+```bash
+npm run preview
+```
+
+## Architecture and Structure
+
+### Core Components
+- **AIPs Directory (`aips/`)**: Contains all AIP markdown files (aip-0.md through aip-135.md+)
+- **Astro Configuration (`astro.config.mjs`)**: Configures Starlight with dynamic base paths for GitHub Pages deployment
+- **Content Schema (`src/content/config.ts`)**: Defines and validates AIP frontmatter with normalization functions
+- **Remark Plugin (`scripts/remark-aip-images.mjs`)**: Processes image paths in AIP markdown files
+
+### Content Management
+- Uses Astro's content collections to manage AIPs as structured data
+- Frontmatter schema validates and normalizes AIP metadata (status, type, dates, authors)
+- Auto-generates sidebar navigation from the `aips/` directory
+- Supports symlinks for content files (preserved via Vite config)
+
+### AIP Structure
+AIPs follow the TEMPLATE.md format with required frontmatter:
+- `aip`: Number (assigned by AIP manager)
+- `title`: AIP title
+- `author`: List of authors
+- `status`: Draft | In Review | Accepted | Rejected | On Hold
+- `type`: Framework | Core | Gas | Cryptography | Ecosystem | etc.
+- `created`: Creation date
+- Optional: `updated`, `requires`, `discussions-to`
+
+### Build Configuration
+- Dynamic base path configuration for GitHub Pages deployment
+- Image path normalization for diagrams in `/diagrams/` directory
+- TypeScript support with strict checking
+- Starlight integration for documentation theming
+
+## Styling and Theming
+- The site uses a custom Aptos-inspired theme with teal/turquoise accent colors
+- Typography uses Inter font family for modern, clean appearance
+- Dark/light theme support with Aptos brand colors
+- Custom CSS variables for consistent color usage across components
+
+## Key Files for Development
+- `src/content/config.ts`: Content schema and validation logic
+- `astro.config.mjs`: Site configuration and integrations  
+- `scripts/remark-aip-images.mjs`: Image processing plugin
+- `src/styles/theme.css`: Aptos brand theming and custom styles
+- `TEMPLATE.md`: Template for new AIPs

README-WEBSITE.md

@@ -0,0 +1,168 @@
+# AIPs Website Development
+
+This repository contains a [Starlight](https://starlight.astro.build)-based documentation website for Aptos Improvement Proposals (AIPs).
+
+## 🚀 Quick Start
+
+### Local Development
+
+1. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+2. **Start the development server**:
+   ```bash
+   npm run dev
+   ```
+
+   The site will be available at `http://localhost:4321/`
+
+3. **Build for production**:
+   ```bash
+   npm run build
+   ```
+
+4. **Preview the production build**:
+   ```bash
+   npm run preview
+   ```
+
+## 📁 Project Structure
+
+```
+/
+├── aips/                   # AIP markdown files (preserved in original location)
+├── diagrams/               # Images and diagrams referenced by AIPs
+├── src/
+│   ├── content/
+│   │   ├── docs/
+│   │   │   ├── aips/      # Symlink to /aips directory
+│   │   │   ├── index.mdx  # Homepage
+│   │   │   └── submit.md  # Submission guide
+│   │   └── config.ts      # Content schema with AIP metadata normalization
+│   ├── pages/
+│   │   └── aips/
+│   │       ├── index.astro  # Interactive browse page with filters
+│   │       └── data.json.ts # JSON API endpoint for AIP metadata
+│   └── styles/
+│       └── theme.css      # Custom Aptos theme styling
+├── scripts/
+│   └── remark-aip-images.mjs  # Plugin to rewrite image paths
+├── public/
+│   └── diagrams/          # Symlink to /diagrams directory
+├── astro.config.mjs       # Astro configuration
+└── tsconfig.json          # TypeScript configuration
+```
+
+## ✨ Key Features
+
+### 1. **No File Movement**
+All AIP markdown files remain in the original `/aips/` directory. The website uses symlinks to access them without moving or modifying the original files.
+
+### 2. **Interactive Browse Page**
+The `/aips/` page provides:
+- **Search**: Find AIPs by number or title
+- **Filters**: Filter by status (Draft, Accepted, In Review, etc.) and category (Framework, Core, Gas, etc.)
+- **Sorting**: Sort by AIP number, status, or category
+
+### 3. **Metadata Normalization**
+AIP frontmatter is automatically normalized during build:
+- **Status**: Inconsistent status values (e.g., "Draft ", "draft", "DRAFT") are normalized to consistent values
+- **Category/Type**: Various type formats (e.g., "Standard (Framework)", "Framework", "Standard Framework") are normalized to canonical categories
+
+### 4. **Global Search**
+Powered by Pagefind, the search function indexes all AIP content and allows users to quickly find relevant proposals.
+
+### 5. **Responsive Design**
+The site is fully responsive and works on desktop, tablet, and mobile devices.
+
+## 🔧 Adding a New AIP
+
+1. Create your AIP markdown file in the `/aips/` directory following the naming convention:
+   ```bash
+   cp TEMPLATE.md aips/your-feature-name.md
+   ```
+
+2. The new AIP will automatically appear on the website after the next build. No configuration changes needed!
+
+3. For local development, the dev server will hot-reload and show your new AIP immediately.
+
+## 🎨 Customization
+
+### Theme Colors
+Edit `src/styles/theme.css` to customize the Aptos brand colors and styling.
+
+### Homepage
+Edit `src/content/docs/index.mdx` to update the homepage content.
+
+### Sidebar
+Edit the `sidebar` configuration in `astro.config.mjs` to customize navigation.
+
+## 🚀 Deployment
+
+### GitHub Pages
+The site is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the `main` branch.
+
+**Workflow file**: `.github/workflows/pages.yml`
+
+The workflow:
+1. Checks out the code
+2. Installs Node.js 20 and dependencies
+3. Builds the site with `npm run build`
+4. Deploys the `dist/` folder to GitHub Pages
+
+### Manual Deployment
+To manually trigger a deployment, go to the Actions tab on GitHub and run the "Deploy Starlight to GitHub Pages" workflow.
+
+## 📝 Content Schema
+
+AIPs are automatically validated and normalized using Zod schemas defined in `src/content/config.ts`:
+
+- **aip** (number): AIP number
+- **title** (string): AIP title
+- **author** (string | string[]): Author(s)
+- **discussions-to** (string): Discussion URL
+- **status** (string): Normalized status value
+- **type** (string): Normalized category value
+- **created** (date): Creation date
+- **updated** (date): Last update date
+- **requires** (string | string[]): Required AIPs
+
+## 🐛 Troubleshooting
+
+### Symlinks not working
+Ensure git is configured to handle symlinks:
+```bash
+git config core.symlinks true
+```
+
+### Build fails with "Cannot find module"
+Try removing `node_modules` and reinstalling:
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Images not showing
+Verify that the `/public/diagrams` symlink points to the correct location:
+```bash
+ls -la public/diagrams
+```
+
+## 📚 Learn More
+
+- [Starlight Documentation](https://starlight.astro.build/)
+- [Astro Documentation](https://docs.astro.build/)
+- [AIP Submission Guide](https://github.com/aptos-foundation/AIPs/blob/main/README.md)
+
+## 🤝 Contributing
+
+Contributions to improve the website are welcome! Please follow the standard GitHub workflow:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+For AIP content contributions, please refer to the main [README.md](README.md).

aips/aip-000-aptos-improvement-proposals.md

@@ -1,5 +1,6 @@
 ---
 aip: 0
+slug: aips/0
 title: Aptos Improvement Proposals
 authors: aptos-foundation
 status: Accepted

aips/aip-001-proposer-selection-improvements.md

@@ -1,5 +1,6 @@
 ---
 aip: 1
+slug: aips/1
 title: Proposer selection improvements
 author: igor-aptos
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/9

aips/aip-002-multiple-token-changes.md

@@ -1,5 +1,6 @@
 ---
 aip: 2
+slug: aips/2
 title: Multiple Token Changes
 author: areshand
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/2

aips/aip-003-multi-step-governance-proposal.md

@@ -1,5 +1,6 @@
 ---
 aip: 3
+slug: aips/3
 title: Multi-step Governance Proposal
 author: 0xchloe
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/3

aips/aip-004-update-simple-map-to-save-gas.md

@@ -1,5 +1,6 @@
 ---
 aip: 4
+slug: aips/4
 title: Update Simple Map To Save Gas
 author: areshand
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/15

aips/aip-006-delegation-pool-for-node-operators.md

@@ -1,5 +1,6 @@
 ---
 aip: 6
+slug: aips/6
 title: Delegation pool for node operators
 author: alexfilip2/alexandru@bwarelabs.com
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/20

aips/aip-007-transaction-fee-distribution.md

@@ -1,10 +1,11 @@
 ---
 aip: 7
+slug: aips/7
 title: Transaction fee distribution
 author: georgemitenkov
 discussions-to: https://github.com/aptos-foundation/AIPs/issues/23
 Status: Draft
-last-call-end-date (*optional):
+last-call-end-date:
 type: Standard (framework)
 created: 12/20/2022
 ---