Rapidly generate enterprise-grade websites with AI.

Astrical is an open-source Astro theme and framework designed specifically for AI-driven development. It decouples content and structure from code, allowing AI agents to build, update, and manage complex websites purely by manipulating structured YAML data.

Traditional web development requires AI to understand complex codebases, component logic, and framework nuances. Astrical flips this model:

• Content as Configuration: The entire site—pages, menus, styles, and component compositions—is defined in declarative YAML files.
• AI-Optimized Architecture: The project structure is documented in a way that allows AI to "read the manual" and immediately start building without hallucinating non-existent APIs.
• Zero-Code Content Management: Add pages, change layouts, and update copy without touching a single line of TypeScript or JSX.
• Production Ready: Built on Astro and Tailwind CSS, deploying to Cloudflare Pages (or any static host) for blazing fast performance.

• Framework: Astro (Static Site Generation)
• Styling: Tailwind CSS
• Language: TypeScript
• Data Source: YAML (Parsed at build time)

• Node.js (v22.0.0 or higher)
• npm

1. Clone the repository:

   git clone https://github.com/nexical/astrical.git
   cd astrical

2. Install dependencies:

   npm install

Start the local development server:

npm run dev

This will start the site at http://localhost:4321.

Build the static site:

npm run build

The output will be in the dist/ directory.

Are you an AI agent? Start here.

This repository includes a comprehensive "AI Operations Manual" designed to teach you how to manipulate this project effectively.

1. Read the Manual: Start by reading dev/content_management.rst. This file explains the YAML schema, available components, and how to construct pages.
2. Understand the Architecture: Review dev/architecture.rst to understand how the YAML data is transformed into the final website.
3. Follow the Rules:
   • Do not modify files in src/ unless explicitly instructed to create a new capability that the current component library cannot handle.
   • Do perform all site updates by modifying files in content/.
   • Do use the npm run validate command to check your work against the schemas.

• Content Management Guide: The primary manual for AI agents. Defines schemas, components, and recipes.
• Architecture Overview: Deep dive into the technical implementation.
• Theme Design: How to customize the visual look and feel via style.yaml.
• Component Development: Guide for human developers (or advanced AI) extending the core component library.

• content/: The AI Workspace. All site content, menus, and configuration live here.
• src/: The Engine. Heavily documentedAstro components, layouts, and logic.
• dev/: The Manuals. Detailed documentation guides for AI and humans.
• public/: Static assets.

Astrical includes a modular form submission system that supports multiple backend handlers (e.g., Mailgun, SMTP).

Form handlers are configured in site:config (via content/config.yaml).

formHandlers:
  defaults: ['mailgun']
  handlers:
    mailgun:
      enabled: true
    smtp:
      enabled: false

• Mailgun: Sends emails using the Mailgun API. Requires MAILGUN_* environment variables.
• SMTP: Sends emails via SMTP. Requires SMTP_* environment variables.

To develop new handlers, implement the FormHandler interface and register it with the FormHandlerRegistry.

We welcome contributions! Whether you're a human or an AI, please feel free to submit a Pull Request.

Apache License 2.0