AstroPaper 📄

---

AstroPaper is a minimal, responsive, accessible and SEO-friendly Astro blog theme. This theme is designed and crafted based on my personal blog.

This theme follows best practices and provides accessibility out of the box. Light and dark mode are supported by default. Moreover, additional color schemes can also be configured.

This theme is self-documented _ which means articles/posts in this theme can also be considered as documentations. Read the blog posts or check the README Documentation Section for more info.

🔥 Features

• type-safe markdown
• super fast performance
• accessible (Keyboard/VoiceOver)
• responsive (mobile ~ desktops)
• SEO-friendly
• light & dark mode
• fuzzy search
• draft posts & pagination
• sitemap & rss feed
• followed best practices
• highly customizable
• dynamic OG image generation for blog posts #15 (Blog Post)
• 🎙️ blog-to-podcast system - Convert blog posts to audio with RSS feeds (See docs)
• 📊 Mermaid diagram support - Create flowcharts, sequence diagrams, and more in markdown (See guide)

Note: I've tested screen-reader accessibility of AstroPaper using VoiceOver on Mac and TalkBack on Android. I couldn't test all other screen-readers out there. However, accessibility enhancements in AstroPaper should be working fine on others as well.

✅ Lighthouse Score

🚀 Project Structure

Inside of AstroPaper, you'll see the following folders and files:

/
├── public/
│   ├── assets/
│   │   └── logo.svg
│   │   └── logo.png
│   └── favicon.svg
│   └── astropaper-og.jpg
│   └── robots.txt
│   └── toggle-theme.js
├── src/
│   ├── assets/
│   │   └── socialIcons.ts
│   ├── components/
│   ├── content/
│   │   |  blog/
│   │   |    └── some-blog-posts.md
│   │   └── config.ts
│   ├── layouts/
│   └── pages/
│   └── styles/
│   └── utils/
│   └── config.ts
│   └── types.ts
└── package.json

Astro looks for .astro or .md files in the src/pages/ directory. Each page is exposed as a route based on its file name.

Any static assets, like images, can be placed in the public/ directory.

All blog posts are stored in src/content/blog directory.

📖 Documentation

Documentation can be read in two formats_ markdown & blog post.

• Configuration - markdown | blog post
• Add Posts - markdown | blog post
• Customize Color Schemes - markdown | blog post
• Predefined Color Schemes - markdown | blog post

For AstroPaper v1, check out this branch and this live URL

💻 Tech Stack

cmwen.github.io

Personal blog built with AstroPaper (Astro + TypeScript + React + TailwindCSS). Focused on AI-assisted development, agent systems, and practical engineering playbooks.

Tech

• Astro, React, TypeScript, TailwindCSS
• Content collections with frontmatter validation (src/content/config.ts)
• Client search via FuseJS
• Dynamic OG images
• Vendored OG fonts (IBM Plex Mono, Noto Sans TC) under src/assets/fonts for reliable multilingual rendering

Project structure

• Posts: src/content/blog/
• Pages: src/pages/
• Layouts: src/layouts/
• Components: src/components/
• Utilities: src/utils/

Local development

Use pnpm for all commands.

pnpm install
pnpm run dev
# open http://localhost:4321

Build and preview:

pnpm run build
pnpm run preview

Formatting and linting:

pnpm run format:check
pnpm run format
pnpm run lint

Writing a post

Create a Markdown file in src/content/blog/ with required frontmatter:

---
title: Your title
description: One-line description
pubDatetime: 2025-08-26
author: Your name
tags: [ai, agents]
featured: false
draft: false
---

Images go in public/ or reference external URLs. Draft posts are excluded from build.

CI/CD

GitHub Actions builds and deploys to gh-pages and runs basic Playwright smoke tests (see .github/workflows/). Use pnpm run cz for conventional commit messages.

Automated dependency updates

Dependabot keeps the project evergreen by regularly checking for new releases:

• npm (pnpm) dependencies are reviewed weekly so Astro, AstroPaper, and other direct dependencies stay current.
• GitHub Actions workflows are refreshed weekly to pick up the latest CI features and fixes.
• Python tooling for the podcast generator is scanned monthly to balance stability with security updates.

When Dependabot raises a pull request, run pnpm install (for JavaScript) or uv sync (for Python) locally to verify the lockfiles and execute the relevant test suites before merging.

License

MIT Made with 🤍 by Sat Naing 👨🏻‍💻 and contributors.