A personal blog built with Astro, Tailwind CSS, and TypeScript. Designed as a fast, fully static site with a dark-mode aesthetic, deployed to GitHub Pages.
Live site: michifumi.de
- Markdown blog posts: Write posts in
.mdfiles with typed frontmatter (title, description, pubDate, tags, draft status, update date). - GitHub-style callout alerts: Native support for styled blockquote alerts (
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING],> [!CAUTION]) viaremark-github-blockquote-alert. - Draft support: Set
draft: truein frontmatter to hide a post from production without deleting it. - Tag system: Every post requires at least one tag. Tags are aggregated automatically and shown in a filterable sidebar.
- Language switcher: Embed bilingual content blocks within a post; readers toggle between languages with a single click.
- Randomised header subtitle: A curated list of quotes is randomly displayed beneath the site title on each page load.
- Giscus comments: GitHub Discussions-powered comment system on every blog post, with reactions, lazy loading, and strict discussion matching.
- Full-text search: A client-side search bar filters posts by title, description, body, and tags instantly: no server required.
- Tag filtering sidebar: Desktop users see a sticky sidebar of all tags; clicking one or more tags filters the post list in real time. Mobile users get a collapsible tag menu.
- Table of contents: Long posts (≥3 headings) feature an interactive Table of Contents. On desktop, it renders as a sticky right-hand sidebar with a real-time scroll spy highlighting sections (
h2) and sub-sections (h3). On mobile, it collapses into a native, accessible dropdown. - Back-to-top button: A floating button appears on scroll and smoothly returns users to the top of the page. Respects
prefers-reduced-motion. - Auto-hiding header: The fixed header slides out of view on scroll to maximise reading space.
- Smooth in-page navigation: Clicking anchor links or Table of Contents items smoothly glides to the target heading with automatic clearance beneath the sticky header. Respects
prefers-reduced-motion. - Image lightbox: Click any image inside a blog post to view it full-screen in a lightbox overlay. Press
Escapeor click to dismiss. - JPEG XL (JXL) image fallback: A custom Remark plugin (
remark-jxl-hint.mjs) automatically transforms images withalt="jxl hint"into helpful fallback links for browsers without native JXL support. - Code block copy button: Every
<pre>code block gets a one-click copy button with visual feedback (copied ✓ / failed ✗). - Customised code typography: Code snippets and
<pre>blocks are styled using a self-hosted Google Sans Code variable font. - External link handling: Links to external domains automatically open in a new tab with
rel="noopener". - Responsive layout: Sidebar + content grid on desktop, single-column on mobile, with dedicated mobile toggles for tags and section navigation.
- RSS feed: Auto-generated at
/rss.xmlfrom all published posts. The footer RSS button copies the feed URL to clipboard. - XML sitemap: Auto-generated at
/sitemap.xmlwith<lastmod>using each post's update date (or publish date). - robots.txt: Dynamically generated, pointing crawlers to the sitemap.
- JSON-LD structured data:
BlogPostingschema markup is injected into every post page for rich search results. - Open Graph & Twitter cards: Full social-media meta tags on every page.
- Canonical URLs: Every page includes a
<link rel="canonical">tag. - Comprehensive favicons: PNG, SVG, Apple Touch Icon, and
favicon.icofor maximum compatibility across browsers and RSS clients. - Automated SEO validation: A pre-flight script (
scripts/check-title-length.mjs) automatically audits blog titles (≤ 70 characters with site suffix) and descriptions (25–160 characters) duringpnpm devandpnpm build.
- Self-hosted analytics: Lightweight, privacy-respecting pageview tracking via
navigator.sendBeaconto a self-hosted endpoint. No cookies, no third-party scripts. - GitHub Pages deployment: Ships with a GitHub Actions workflow (
.github/workflows/deploy.yml) for automated builds and deploys on push. - Content Security Policy: A strict CSP meta tag is applied site-wide.
| Layer | Technology |
|---|---|
| Framework | Astro 7 (static-site generation) |
| Styling | Tailwind CSS 4 via @tailwindcss/vite + @tailwindcss/typography |
| Typography | 100% self-hosted Inter (body, subtitle), Uncial Antiqua (title), and Google Sans Code (code) |
| Language | TypeScript, JavaScript, HTML, CSS |
| Deployment | GitHub Pages via GitHub Actions |
git clone https://github.com/Shawshank01/record.git
cd record
pnpm installUpdate the following to make the blog your own:
| What | Where |
|---|---|
| Site URL | astro.config.mjs → site |
| Blog title & meta | src/layouts/BaseLayout.astro → default props |
| Header subtitles | src/data/subtitles.ts |
| Custom domain (CNAME) | CNAME (delete if not using a custom domain) |
| Analytics endpoint & CSP | src/scripts/analytics.ts → endpoint & hostname guard; src/layouts/BaseLayout.astro → CSP connect-src (or remove script) |
| Accent colour | src/styles/global.css → @theme block |
| Background colours | src/styles/global.css → @theme block |
| Social / OG image | public/icon.png (replace with your own raster image; Open Graph requires PNG/JPEG) |
| Giscus comments | src/pages/blog/[slug].astro → giscus data-repo and IDs |
| Giscus config | giscus.json → origins, comment order |
Create a new .md file in src/content/blog/:
---
title: "My First Post"
description: "A short summary of the post."
pubDate: 2025-01-01
tags: ["Example"]
---
Write your content here in Markdown.Frontmatter fields:
| Field | Required | Description |
|---|---|---|
title |
✅ | Post title |
description |
✅ | Short summary shown on cards and in meta tags |
pubDate |
✅ | Publication date (YYYY-MM-DD) |
tags |
✅ | Array of tag strings (at least one) |
draft |
❌ | Set to true to hide the post from production |
updateDate |
❌ | Last-updated date, used in sitemap, post header and post cards |
pnpm devThe dev server starts at http://localhost:4321 with hot reload.
pnpm build # Generate static files in dist/
pnpm preview # Preview the production build locallyThe included GitHub Actions workflow automatically builds and deploys to GitHub Pages on every push to the default branch. To use it:
- Go to your repository Settings → Pages.
- Set the source to GitHub Actions.
- Push to the default branch: the workflow handles the rest.