Astro Haze

astro-haze is an open-source, glassmorphism-styled Astro 7 theme by developer kpab for building static blogs, portfolio case-study sites, and config-driven product landing pages with search, SEO, and accessibility built in.

What is astro-haze?

astro-haze is a static, content-first Astro 7 theme that takes Markdown and MDX files in src/content/ plus a src/site.config.ts configuration file and produces a fully static site with a glassmorphism UI system, paginated blog, portfolio galleries, RSS feed, XML sitemap, and Pagefind-powered search. The theme is MIT-licensed and deploys to GitHub Pages or Cloudflare Pages. Its project structure is modular, with components split into blog, common, landing, portfolio, and UI directories, and all content collection schemas are validated with Zod in src/content.config.ts.

Key features

• Glass UI system — Prebuilt glassmorphism components (cards, buttons, badges, tags, sections, containers) with aurora backgrounds, defined in src/styles/glass.css and design tokens in src/styles/tokens.css.
• Pagefind site search — Static full-text search opens in a glass modal via a header button or the Cmd+K shortcut; the search index is generated during npm run build.
• Light/dark mode — System-aware theme toggle with a no-flash startup script and synced theme-color; the default mode can be light, dark, or system.
• Blog features — Pagination, tag archives, table of contents, reading time, share links, and previous/next navigation, all configurable in site.config.ts.
• Portfolio features — Work index with technology filters, case-study pages, and responsive image galleries.
• Config-driven landing page — Hero, features, benefits, pricing, gallery, testimonials, FAQ, and final CTA sections loaded from JSON, YAML, or Markdown data in src/content/landing/.
• Zod-validated content — Astro 7 collections in src/content.config.ts validate frontmatter for blog, projects, and landing data, with support for both Markdown and MDX.
• SEO and feeds — Canonical URLs, Open Graph, Twitter cards, JSON-LD, RSS feed at /rss.xml, and an optional XML sitemap via @astrojs/sitemap.
• Optimized images — Images are validated with Astro's image() helper and served as AVIF/WebP with responsive srcset through the shared Picture.astro component.
• Accessibility and reduced motion — Includes landmarks, skip navigation, keyboard focus states, and honors prefers-reduced-motion and prefers-reduced-transparency.

Who should use astro-haze?

Bloggers who want a polished glassmorphism layout with pagination, tags, table of contents, and reading time without building those features from scratch. Designers, developers, or agencies who need a portfolio with a searchable work index, technology filters, case-study pages, and image galleries. Product teams preparing a landing page who want hero, pricing, testimonials, and FAQ sections defined in JSON or YAML. Developers comfortable with Astro and TypeScript who want a theme to build on, since the codebase is modular and uses strict TypeScript.

Use cases for astro-haze

• Bloggers: publish Markdown or MDX posts in src/content/blog/ with hero images, tags, drafts, and featured flags; Astro generates paginated archive and tag pages automatically.
• Designers and agencies: build a portfolio at /work with per-project case studies that include cover images, responsive galleries, tech stack, role, year, client, and duration fields.
• Product marketers: create a landing page by editing a single JSON or YAML file with hero, features, benefits, pricing tiers, gallery, testimonials, FAQ, and a final CTA.
• Open-source maintainers: use the included GitHub Actions workflow to deploy the static site to GitHub Pages on every push to master.

How do I get started with astro-haze?

Requirements are Node.js 22.12 or later and npm. Run npm install, then npm run dev to start the development server; npm run build outputs a production build to dist/, and npm run preview serves it locally. Astro 7 can detect AI-agent environments and run the dev server in the background, inspectable via npx astro dev status and npx astro dev logs. A StackBlitz demo lets you try the theme in the browser without installing anything.

Site configuration and content

The file src/site.config.ts controls site identity (name, title, description, author, URL), theme settings (accent color, default color mode, theme toggle visibility), navigation, feature flags for blog, portfolio, landing, search, sitemap, and RSS, social links, and per-section options like posts per page. Blog posts go in src/content/blog/, portfolio projects in src/content/projects/, and landing data in src/content/landing/ as .json, .yaml, or .yml. All frontmatter is validated with Zod schemas in src/content.config.ts, and invalid fields raise errors during development and builds.

Pricing and license

astro-haze is free and open source under the MIT License. The repository ships a GitHub Actions workflow that builds with withastro/action and publishes to GitHub Pages; the theme also includes a public/_headers file intended for Cloudflare Pages or Netlify deployments. The same author sells a premium directory theme called Almanac, built on Astro and Cloudflare, as a separate paid product on Gumroad.

Frequently asked questions

Is astro-haze free?

Yes — the theme is released under the MIT License, so you can use it for personal or commercial projects, modify it, and redistribute it. There is no paid tier for the theme itself; the author's premium directory theme, Almanac, is sold separately.

What version of Node.js does astro-haze require?

The theme requires Node.js 22.12 or newer and npm. The project uses TypeScript in strict mode, and the npm run check command runs Astro diagnostics and TypeScript type-checking without emitting files.

Does astro-haze support search?

Yes. The theme integrates Pagefind via the astro-pagefind integration, which is enabled with the features.search flag in site.config.ts. The search index is generated during npm run build; in development you must run npm run build once for local search to work.

Can I deploy astro-haze to GitHub Pages?

Yes. The repository includes a GitHub Actions workflow at .github/workflows/deploy.yml that builds with the withastro/action and publishes to GitHub Pages on every push to master. The included config assumes a project page served from https://kpab.github.io/astro-haze/, and all internal links use a withBase() helper.

What content formats does astro-haze support?

Blog posts and portfolio case studies can be written in Markdown or MDX (processed by the Sätteri engine). Landing-page data can be stored as JSON, YAML, or Markdown. Images referenced in content are validated with Astro's image helper and optimized to AVIF/WebP with responsive srcset.