Requirements
- Node.js 22.12 or newer
- npm, pnpm or yarn
- Basic familiarity with Astro and Tailwind CSS
Installation
npm install
npm run dev # http://localhost:4321
npm run build # type-check + static build into ./dist
npm run preview # preview the production build
Project structure
src/
├─ components/ UI building blocks (cards, blocks, widgets, header, footer)
├─ content/
│ ├─ blog/ Articles (.md / .mdx)
│ └─ page/ Static pages such as Privacy, Terms and this page
├─ data/
│ ├─ authors.ts Author profiles
│ └─ site.ts Site name, socials, categories & navigation
├─ layouts/MainLayout.astro
├─ lib/posts.ts Collection helpers (sorting, URLs, pagination)
├─ pages/ File-based routes
└─ styles/style.css Design tokens (colours, fonts) & component classes
Branding
Open src/data/site.ts to change the site name, tagline, description, social links and posts per page.
Replace public/img/logo.png (dark mode) and public/img/logo-light.png (light mode) with your own logos; they switch automatically with the theme. The favicon is public/favicon.svg.
Colours
All colours are CSS variables in src/styles/style.css. Light values live in :root, dark values in .dark.
Change --tm-accent to rebrand the whole theme in one line. Category colours are defined as --color-cat-*.
Fonts
Fonts are loaded with the Astro Fonts API in astro.config.mjs (Space Grotesk, IBM Plex Sans, JetBrains Mono).
Swap the name values for any Google font and keep the cssVariable names.
Writing articles
Create a new .mdx file in src/content/blog/:
---
title: "Your headline"
cover: "/img/covers/blog36.jpg"
date: "2026-11-20"
category: "ai" # must match a slug in site.ts to get colours & icon
tags: [AI, Research]
readTime: 6
featured: true # appears in the hero & "Most read"
authorId: "nadia-rahman" # key from src/data/authors.ts
score: 8.5 # optional — turns the post into a review
excerpt: "One or two sentences shown on cards and in search."
draft: false
---
The article URL is generated automatically as /{category}/{file-name}.
Categories & navigation
Categories are defined once in src/data/site.ts. The first PRIMARY_NAV_COUNT appear in the main menu;
the rest go into the More dropdown. Each category gets an archive page with pagination.
Homepage blocks
The homepage (src/pages/index.astro) is assembled from reusable blocks. Every block takes a category prop:
| Component | Layout |
|---|---|
HeroBento |
Lead story, two tiles and numbered top stories |
BlockSpotlight |
One large overlay card + text list |
BlockGrid |
2, 3 or 4 column card grid |
BlockTerminal |
Full-width dark terminal band |
BlockColumns |
Two categories side by side |
BlockReviews |
Horizontal scroller with score rings |
ArticleListSection |
Paginated latest feed |
Search
/search.json is generated at build time. The ⌘K palette and the /search page load it on demand,
so there is no server or third-party service required.
SEO
Each page outputs canonical URLs, Open Graph and Twitter tags. Articles add NewsArticle or Review JSON-LD.
A sitemap (/sitemap-index.xml) and RSS feed (/rss.xml) are generated automatically — set site in astro.config.mjs.
Deployment
The output is fully static. Deploy the dist/ folder to Netlify, Vercel, Cloudflare Pages, GitHub Pages or any static host.