# Astro Quickstart Template - Full Documentation

> A minimal Astro quickstart template with comprehensive SEO optimization including OG images, structured data, IndexNow integration, and LLM discovery.

## Table of Contents

1. [About](#about)
2. [Features](#features)
3. [SEO Optimizations](#seo-optimizations)
4. [Project Structure](#project-structure)
5. [Configuration](#configuration)
6. [Usage Examples](#usage-examples)
7. [Deployment](#deployment)

## About

This Astro starter template is designed with SEO and discoverability as top priorities. It includes all the modern best practices for search engines, social media platforms, and AI/LLM crawlers.

### Target Audience

- Web developers looking for a solid Astro foundation
- Agencies building client websites
- Startups needing fast, SEO-optimized sites
- Content creators who want maximum discoverability

## Features

### Core Features

- **Astro 5+**: Latest version with View Transitions
- **Tailwind CSS 4+**: Modern utility-first CSS framework
- **TypeScript**: Full type safety
- **Responsive Design**: Mobile-first approach

### SEO Features

1. **Meta Tags**: Comprehensive meta tags including:
   - Open Graph (Facebook, LinkedIn)
   - Twitter Cards
   - Canonical URLs
   - Author and description tags

2. **Structured Data**: Schema.org JSON-LD for:
   - Organization
   - Website
   - Product (optional)
   - Article (optional)
   - Breadcrumbs (optional)

3. **IndexNow Integration**:
   - Instant search engine notification
   - Supported by Bing, Yandex, and others
   - Automated URL submission utilities

4. **LLM Discovery**:
   - llms.txt for AI crawler guidance
   - Structured information for training data
   - Clear attribution and linking

5. **Sitemap**:
   - Automatic XML sitemap generation
   - Configurable priority and change frequency
   - Filtered for private pages

6. **robots.txt**:
   - Search engine crawler directives
   - LLM-specific guidance
   - Sitemap references

## SEO Optimizations

### Open Graph Tags
All pages include OG tags for rich social media previews:
- og:title, og:description, og:image
- og:url, og:type, og:site_name

### Twitter Cards
Optimized for Twitter/X sharing:
- Large image cards by default
- Customizable per page
- Twitter handle attribution

### Canonical URLs
Every page has a canonical URL to prevent duplicate content issues.

### Structured Data
JSON-LD structured data for search engines:
- Helps Google understand your content
- Rich snippets in search results
- Knowledge Graph eligibility

## Project Structure

```
/
├── public/
│   ├── robots.txt          # Search engine directives
│   ├── llms.txt            # LLM discovery file
│   ├── llms-full.txt       # Extended LLM context
│   ├── og-image.png        # Default Open Graph image
│   ├── favicon.svg         # Site icon
│   └── [api-key].txt       # IndexNow verification
├── src/
│   ├── components/
│   │   ├── StructuredData.astro   # Schema.org component
│   │   ├── Nav.astro              # Navigation
│   │   └── Footer.astro           # Footer
│   ├── config/
│   │   └── seo.ts                 # Centralized SEO config
│   ├── layouts/
│   │   ├── BaseLayout.astro       # Base HTML + SEO meta
│   │   └── Layout.astro           # App layout wrapper
│   ├── pages/
│   │   ├── index.astro            # Homepage
│   │   ├── about.astro            # About page
│   │   └── contact.astro          # Contact page
│   ├── styles/
│   │   └── global.css             # Global styles
│   └── utils/
│       └── indexnow.ts            # IndexNow utilities
└── astro.config.mjs               # Astro configuration
```

## Configuration

### Quick Start: Update src/config/seo.ts

This is the ONLY file you need to update for new projects:

```typescript
export const seoConfig = {
  site: {
    name: "Your Site Name",
    title: "Your Site Title",
    description: "Your site description...",
    url: "https://yoursite.com",
    author: "Your Name",
    email: "your@email.com",
  },
  social: {
    twitter: "@yourhandle",
  },
  indexNow: {
    key: "your-generated-api-key",
    enabled: true,
  },
  // ... more options
};
```

### IndexNow Setup

1. Generate a key: `crypto.randomUUID()` or use online generator
2. Add key to `src/config/seo.ts`
3. Create `public/[your-key].txt` with the key as content
4. Deploy and verify at Bing Webmaster Tools

### Image Assets

Replace these with your branding:
- `public/og-image.png` (1200x630px) - Social media preview
- `public/favicon.svg` - Browser icon

## Usage Examples

### Basic Page

```astro
---
import Layout from "../layouts/Layout.astro";
import StructuredData from "../components/StructuredData.astro";

const pageTitle = "Page Title";
const pageDescription = "Page description for SEO";
---

<Layout title={pageTitle} description={pageDescription}>
  <StructuredData type="website" />
  <h1>{pageTitle}</h1>
  <!-- Your content -->
</Layout>
```

### Page with Custom OG Image

```astro
---
import Layout from "../layouts/Layout.astro";

const pageTitle = "Special Page";
const pageDescription = "This page has a custom image";
const customImage = "/images/special-og.png";
---

<Layout
  title={pageTitle}
  description={pageDescription}
  image={customImage}
>
  <!-- Your content -->
</Layout>
```

### Product Page with Structured Data

```astro
---
import Layout from "../layouts/Layout.astro";
import StructuredData from "../components/StructuredData.astro";

const productData = {
  name: "My Product",
  description: "Product description",
  image: "/images/product.png",
  offers: [
    {
      "@type": "Offer",
      priceCurrency: "USD",
      price: "99.00",
      availability: "https://schema.org/InStock",
    },
  ],
};
---

<Layout title={productData.name}>
  <StructuredData type="product" data={productData} />
  <!-- Product content -->
</Layout>
```

### Submit to IndexNow

```typescript
import { submitToIndexNow } from "../utils/indexnow";

// Submit single URL
await submitToIndexNow("https://yoursite.com/new-page");

// Submit multiple URLs
await submitToIndexNow([
  "https://yoursite.com/page1",
  "https://yoursite.com/page2",
]);

// Submit entire sitemap
import { submitSitemapToIndexNow } from "../utils/indexnow";
await submitSitemapToIndexNow();
```

## Deployment

### Build Command
```bash
npm run build
```

### Preview Build
```bash
npm run preview
```

### Environment Variables

Create `.env` file for local development:
```
SITE=https://yoursite.com
```

For production, set this in your hosting platform (Vercel, Netlify, etc.)

### Post-Deployment Checklist

1. ✅ Verify robots.txt is accessible: `yoursite.com/robots.txt`
2. ✅ Check sitemap: `yoursite.com/sitemap-index.xml`
3. ✅ Verify llms.txt: `yoursite.com/llms.txt`
4. ✅ Test OG images with: https://www.opengraph.xyz/
5. ✅ Submit to Google Search Console
6. ✅ Submit to Bing Webmaster Tools
7. ✅ Verify IndexNow setup in Bing Webmaster Tools

## Technical Details

### Performance Optimizations

- Automatic image optimization (Astro built-in)
- CSS inlining for above-the-fold content
- Prefetching for faster navigation
- Static site generation for maximum speed

### Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Mobile browsers (iOS Safari, Chrome Mobile)
- Progressive enhancement approach

### Accessibility

- Semantic HTML structure
- ARIA labels where appropriate
- Keyboard navigation support
- Screen reader friendly

## Best Practices

### SEO Best Practices Implemented

1. ✅ Unique title and description per page
2. ✅ Proper heading hierarchy (h1, h2, h3)
3. ✅ Semantic HTML elements
4. ✅ Fast page load times
5. ✅ Mobile responsive design
6. ✅ HTTPS (when deployed)
7. ✅ XML sitemap
8. ✅ Structured data
9. ✅ Canonical URLs
10. ✅ Social media meta tags

### Content Recommendations

- Keep titles under 60 characters
- Keep descriptions under 160 characters
- Use descriptive URLs (enabled by default)
- Include relevant keywords naturally
- Create high-quality, original content

## Support & Resources

### Documentation
- Astro Docs: https://docs.astro.build/
- Schema.org: https://schema.org/
- IndexNow: https://www.bing.com/indexnow
- LLMs.txt: https://github.com/tldrrun/llms.txt

### Contact
Email: hello@copilance.com

### License
MIT License - feel free to use for any project!

---

Last updated: 2025-12-05
Version: 1.0.0