A minimal static blog built with Astro and MDX, inspired by the Hey WordPress theme, and hosted on GitHub Pages.
- 📝 Write posts in MDX (Markdown + JSX)
- 🎨 Clean, minimal design inspired by the Hey WordPress theme
- 🚀 Static site generation with Astro
- 📦 Zero JavaScript by default
- 🌐 Deployed to GitHub Pages
# Install dependencies
npm install
# Start dev server
npm run dev
# Build for production
npm run build
# Preview production build
npm run previewCode is formatted with Prettier (plus prettier-plugin-astro for .astro files).
# Format every file in place
npm run format
# Check formatting without writing (CI-friendly)
npm run format:check-
Create a GitHub repository for your blog
-
Update
astro.config.mjs:export default defineConfig({ site: "https://yourusername.github.io", base: "/your-repo-name", // Remove this line if using yourusername.github.io integrations: [mdx()], });
-
Initialize git and push:
git init git add . git commit -m "Initial commit" git branch -M main git remote add origin https://github.com/yourusername/your-repo-name.git git push -u origin main
-
Enable GitHub Pages:
- Go to your repository settings
- Navigate to "Pages" in the sidebar
- Under "Build and deployment", select "GitHub Actions" as the source
- The workflow will automatically deploy on push to main
Create a new .mdx file in src/pages/posts/:
---
layout: ../../layouts/PostLayout.astro
title: "Your Post Title"
date: "2024-01-15"
description: "A brief description of your post"
---
Your post content here...Prettier formats the JavaScript inside an MDX {…} expression (e.g. a component's
items={[…]} prop) only if it can parse the whole expression as one unit. A blank
line inside the {…} container breaks MDX's parse boundary, so Prettier silently gives
up and leaves the entire expression unformatted — and npm run format:check won't flag it,
because an unparseable expression reads as "already formatted."
<Timeline
items={[
{ title: "Day 1", embeds: [] },
👈 a blank line here breaks formatting of the whole prop
{ title: "Day 2", embeds: [] },
]}
/>Blank lines between separate JSX elements are fine — just keep them out of {…}
expressions. If a .mdx file looks "stuck" and won't reformat, look for a stray blank line
(or a real syntax error) inside an embedded expression.
Edit the navigation link in src/layouts/BaseLayout.astro:92
Modify CSS variables in src/layouts/BaseLayout.astro:24-29:
--color-primary: Main text color--color-secondary: Secondary text color--color-tertiary: Borders and accents--color-background: Background color
Add a <link> tag in the <head> section of BaseLayout.astro and update the font-family in the body styles.
/
├── .github/workflows/
│ └── deploy.yml # GitHub Actions deployment workflow
├── public/
│ └── favicon.svg
├── src/
│ ├── layouts/
│ │ ├── BaseLayout.astro # Main layout with styling
│ │ └── PostLayout.astro # Blog post layout
│ └── pages/
│ ├── index.astro # Homepage (blog list)
│ └── posts/
│ ├── first-post.mdx
│ └── second-post.mdx
├── astro.config.mjs # Astro configuration
└── package.json
MIT