bloodstone — Astro Blog Template

SHA-256: 91e3b49a163e2885ea259727b3673f0c45e8e6e89e471a15d2617740019b6ecb

2026-10-13T01:31:34.858Z

# Bloodstone

A minimalist editorial blog theme for [Astro](https://astro.build/) and [Preact](https://preactjs.com/). Bloodstone publishes history, biography, and world-event articles with a neutral tone and fact-based narrative.

[![Astro](https://img.shields.io/badge/Astro-7-48477C?logo=astro&logoColor=white&labelColor=1F1F2E)](https://astro.build/)
[![Preact](https://img.shields.io/badge/Preact-10-673AB8?logo=preact&logoColor=white&labelColor=1F1F2E)](https://preactjs.com/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-38BDF8?logo=tailwindcss&logoColor=white&labelColor=1F1F2E)](https://tailwindcss.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

![Bloodstone screenshot](./screenshot.png)

## Live Preview
[Bloodstone](https://bloodstone-oss.pages.dev/)

## Description

Bloodstone is a static, editorial blog theme built with Astro 7 and Preact 10, styled with Tailwind CSS 4. It includes content collections for posts, authors, and pages, plus a search overlay, article saving, sharing, series browsing, and a table of contents, all ready to use out of the box.

## Features

- Content collections for **posts**, **authors**, and **pages**
- Responsive article list and detail pages
- Dropdown table of contents on article pages
- Article series with a dedicated series index
- Client-side article search with keyboard shortcuts (`⌘K` / `Ctrl+K`, `Esc`, `↵`)
- Save articles to local storage
- Share popover with social links, native sharing, and copy link
- AI-powered article summaries via Google AI Mode, DeepSeek, and Perplexity
- Syntax-highlighted code blocks with Shiki
- `sitemap.xml` and Google News sitemap
- Schema.org JSON-LD structured data
- Open Graph and Twitter card metadata
- PWA support with a web app manifest and offline service worker
- WCAG 2.1 AA accessibility (skip links, focus indicators, reduced-motion support, accessibility statement)
- Mobile-first responsive layout

## Accessibility (WCAG)

Bloodstone is built with accessibility in mind and targets conformance to the **Web Content Accessibility Guidelines (WCAG) 2.1 Level AA**.

### Accessibility Features

- **Skip navigation** – A skip-to-content link lets keyboard users bypass the header and jump straight to the main content.
- **Semantic HTML** – Correct landmark regions, heading hierarchy, and native elements throughout the theme.
- **Keyboard support** – All interactive components (search, menus, popovers) are fully keyboard-operable with visible focus indicators.
- **ARIA attributes** – Icon-only buttons and dynamic regions use appropriate ARIA labels and states.
- **Color contrast** – Text and interactive elements meet AA contrast ratios.
- **Alt text** – All meaningful images include descriptive alt text; decorative icons are hidden from screen readers.
- **Responsive design** – Content is usable at all screen sizes and zoom levels up to 200%.
- **Reduced motion** – Animation and transitions are disabled for users who prefer reduced motion.
- **Accessibility statement** – A dedicated page at `/accessibility` documents the theme's accessibility features and provides a feedback channel.

## Tech Stack

- [Astro](https://astro.build/) 7
- [Preact](https://preactjs.com/) 10
- [Tailwind CSS](https://tailwindcss.com/) 4
- [TypeScript](https://www.typescriptlang.org/)
- [Shiki](https://shiki.style/) for syntax highlighting
- [Lucide](https://lucide.dev/) icons
- [pnpm](https://pnpm.io/) for package management

## Demo

Replace `site` in `astro.config.mjs` and `SITE_URL` in `src/consts.ts` with your production URL, then deploy the generated `dist/` directory to any static hosting service.

## Quick Start

Requires Node.js **18.17.1** or later.

```bash
# install dependencies
pnpm install
# or
npm install

# start the dev server
npm run dev

# build for production
npm run build

# preview the production build
npm run preview
```

## Configuration

All site-wide values live in `src/consts.ts`:

- `SITE_NAME`: the site name shown in metadata, the header, and the footer.
- `SITE_URL`: the canonical production URL used by sitemaps and JSON-LD.
- `SITE_DESCRIPTION`: the default meta description.
- `SITE_EMAIL`: the contact email used by the contact page.

Also update `site` in `astro.config.mjs` so it matches `SITE_URL`.

## Project Structure

```
public/            # Static assets (favicon, manifest, service worker, robots.txt, etc.)
src/
  components/      # Reusable UI and interactive components
  content/         # Markdown content for authors, pages, and posts
  content.config.ts# Content collections schema
  hooks/           # Custom Preact hooks
  layouts/         # Astro page layouts
  lib/             # Utility modules
  pages/           # Astro routes
  styles/          # Global Tailwind CSS
astro.config.mjs   # Astro configuration
package.json       # Dependencies and scripts
```

## Donations

Bloodstone supports multiple donation platforms. All configuration lives in `src/lib/donations.ts`.

### Supported Platforms

- **Ko-fi**
- **Buy Me a Coffee**
- **Liberapay**
- **GitHub Sponsors**
- **PayPal**

### Activating / Deactivating Platforms

Each platform has an `enabled` boolean in `src/lib/donations.ts`. Set it to `true` to show the platform or `false` to hide it:

```ts
{
  id: 'kofi',
  name: 'Ko-fi',
  description: 'Buy us a coffee on Ko-fi',
  url: 'https://ko-fi.com/yourusername',
  enabled: true, // ← toggle this
},
```

### Updating Your Donation Links

Replace the `url` value for each platform with your actual donation link.

### Components

- **DonateButton** – Popover button in the footer that lists all active platforms.
- **DonationSwitcher** – Interactive selector on the `/donate` page where visitors pick their preferred platform.
- **DonatePlaceholder** – Reusable placeholder widget that lists all active platforms. Add it anywhere (e.g., end of an article) with `<DonatePlaceholder client:load />`.

## Content Guide

### Posts

Create new posts inside `src/content/posts/` as Markdown files with frontmatter:

```yaml
---
title: Article Title
description: Short description of the article.
pubDate: 2026-08-08T08:00:00Z
authors:
  - Bloodstone
category:
  - History
tags:
  - tag-name
series: Series Name
heroImage: https://example.com/image.jpg
---
```

### Authors

Author profiles live in `src/content/authors/`:

```yaml
---
name: Author Name
avatar: https://example.com/avatar.jpg
bio: Brief bio.
position: Editorial
social:
  github: username
---
```

### Pages

Static pages such as About, FAQ, and Contact are managed as Markdown entries in `src/content/pages/`. The contact page itself is a dedicated route at `src/pages/contact.astro`.

## License

[MIT](./LICENSE)