---
name: astro-marketing-websites
description: Build maintainable Astro marketing/company websites with content collections, design tokens, performant motion, and Git-based content workflows.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [astro, marketing-sites, content-collections, static-sites, web-design, three-js, seo]
related_skills: [writing-plans, design-md, popular-web-designs]
---
# Astro Marketing Websites
Use this skill when creating or extending a modern company/marketing website in Astro, especially when the site must be easy to maintain through Git/Markdown and may include subtle motion or Three.js enhancement.
## Core approach
1. **Start with strategy before scaffold**
- Capture target audiences, priority services, conversion goal, region/SEO focus, trust signals, tone, and maintenance model.
- Save decisions in `docs/brand-and-content-brief.md` or equivalent before coding.
2. **Use Astro for content-first company sites**
- Astro is a strong default for static/hybrid business websites with pages like services, references/case studies, news, team, and contact.
- Keep the first version simple: static pages + content collections + optimized assets.
- Add heavy interaction only after the page hierarchy and conversion paths work.
3. **Prefer Content Collections for maintainability**
- Use collections for repeatable content: references/case studies, news/updates, team members, jobs, FAQs.
- Store each entry as Markdown/MDX with frontmatter.
- Include fields that support filtering and SEO: category, location, year/date, summary, hero image, gallery, featured flag.
4. **Use real images as soon as possible**
- For construction/architecture/company sites, real project/team photos are major trust assets.
- Placeholders are acceptable early, but make the structure ready for per-reference images.
5. **Design tokens first**
- Put brand decisions in `DESIGN.md` or another token source.
- Translate tokens into CSS variables early: colors, fonts, spacing, radii, focus styles.
- Validate contrast and keep brand accents restrained.
## Astro v5/v6 Content Collections pattern
Astro’s newer content API uses `src/content.config.ts` plus loaders. Avoid legacy `src/content/config.ts` if the installed Astro version reports `LegacyContentConfigError`.
Recommended shape:
```ts
// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
const references = defineCollection({
loader: glob({ pattern: '**/*.md', base: './src/content/references' }),
schema: z.object({
title: z.string(),
category: z.string(),
location: z.string(),
year: z.string(),
summary: z.string(),
heroImage: z.string(),
gallery: z.array(z.string()).default([]),
featured: z.boolean().default(false),
}),
});
export const collections = { references };
```
When using `glob` loaders, route slugs are typically exposed as `entry.id`, not `entry.slug`.
```astro
---
import { getCollection } from 'astro:content';
const references = await getCollection('references');
---
{references.map((reference) => (
{reference.data.title}
))}
```
Dynamic routes:
```astro
---
import { getCollection, render } from 'astro:content';
export async function getStaticPaths() {
const references = await getCollection('references');
return references.map((reference) => ({
params: { slug: reference.id },
props: { reference },
}));
}
const { reference } = Astro.props;
const { Content } = await render(reference);
---
```
## Development server for client review
When the user wants to review progress from another device, run Astro on all interfaces:
```bash
npm run dev -- --host 0.0.0.0
```
Then discover the local IP and share:
```bash
hostname -I | awk '{print $1}'
```
If an older dev server is bound to `127.0.0.1`, stop/restart it. Verify with:
```bash
ss -ltnp | grep ':4321'
curl -I http://127.0.0.1:4321/
```
If mobile cannot reach the URL, suspect network/VPN/firewall routing and offer a tunnel rather than changing the site.
## Subtle Three.js / animated logo pattern
Use Three.js as progressive enhancement, not as a dependency for core content.
Recommended pattern:
- Keep a normal `![]()
` logo fallback visible by default only when it is not visually competing with the WebGL version.
- Add a `