Astro Paper — Theme Blog Minimal Cho Astro

Khi xây dựng blog cá nhân với Astro, chọn theme phù hợp là bước quan trọng. Bạn muốn blog nhanh, đẹp, dễ SEO, nhưng cũng đừng quá phức tạp để custom.

Astro Paper là một trong những theme blog phổ biến nhất trong hệ sinh thái Astro — được tạo bởi Sat Naing ↗, focus vào sự tối giản, accessibility, và hiệu suất.

Tổng Quan#

Astro Paper là theme blog mã nguồn mở (MIT License) cho Astro, được thiết kế dựa trên blog cá nhân của tác giả. Nó chạy hoàn toàn trên Astro, không React, không Vue — output là HTML/CSS tĩnh, siêu nhẹ.

Triết lý: Tối giản nhưng đầy đủ. Đủ tính năng cho một blog chuyên nghiệp, nhưng không phình to thành một CMS cồng kềnh.

Tính Năng Nổi Bật#

Hiệu Suất & SEO#

• Lighthouse 100/100 — Performance, Accessibility, Best Practices, SEO
• SEO-Friendly — Meta tags, sitemap, RSS feed có sẵn
• Responsive — Hoạt động tốt từ mobile đến desktop
• Accessible — Đã test với VoiceOver (Mac) và TalkBack (Android)

Nội Dung#

• Markdown & MDX — Cả hai định dạng, type-safe
• Code Highlighting — Shiki, hỗ trợ nhiều ngôn ngữ
• Collapsible TOC — Mục lục có thể thu gọn/mở rộng
• Draft Posts — Bài viết nháp, không publish

UX#

• Dark Mode — Chuyển đổi sáng/tối mượt mà
• Static Search (Pagefind) — Tìm kiếm không server
• Dynamic OG Images — Tự động tạo ảnh preview cho bài viết
• Pagination — Phân trang tự động
• i18n Ready — Sẵn sàng đa ngôn ngữ

Developer Experience#

• TypeScript — Toàn bộ codebase type-safe
• TailwindCSS — Styling linh hoạt
• Highly Customizable — Config trung tâm, dễ chỉnh sửa
• Best Practices — ESLint, Prettier có sẵn

Cài Đặt#

Tạo project mới với một dòng lệnh:

# pnpm (khuyên dùng)
pnpm create astro@latest --template satnaing/astro-paper

# npm
npm create astro@latest -- --template satnaing/astro-paper

# yarn
yarn create astro --template satnaing/astro-paper

# bun
bun create astro@latest -- --template satnaing/astro-paper

Sau đó chạy:

cd ten-du-an
pnpm install
pnpm dev

Mở http://localhost:4321 — bạn đã có blog chạy ngay lập tức.

Cấu Hình#

Astro Paper dùng file astro-paper.config.ts ở thư mục gốc để quản lý toàn bộ cấu hình:

export default defineAstroPaperConfig({
  site: {
    url: 'https://example.com',
    title: 'Blog Của Tôi',
    description: 'Mô tả blog',
    author: 'Tên bạn',
    lang: 'vi',
    timezone: 'Asia/Ho_Chi_Minh',
    googleVerification: '...', // tuỳ chọn
  },
  posts: {
    perPage: 6,       // 6 bài mỗi trang
    perIndex: 5,      // 5 bài trên trang chủ
    scheduledPostMargin: 15, // phút
  },
  features: {
    lightAndDarkMode: true,
    dynamicOgImage: true,
    showArchives: true,
    showBackButton: true,
    search: { provider: 'pagefind' },
    editPost: {
      url: 'https://github.com/you/your-blog/edit/main/src/content/posts',
    },
  },
  socials: [
    { name: 'github', href: 'https://github.com/you' },
    { name: 'twitter', href: 'https://twitter.com/you' },
  ],
  shareLinks: ['twitter', 'facebook', 'linkedin'],
})

Mọi thứ đều có IntelliSense — gõ defineAstroPaperConfig là được IDE gợi ý ngay.

Thêm Bài Viết#

Đặt file .md hoặc .mdx vào src/content/posts/:

---
title: 'Tiêu đề bài viết'
description: 'Mô tả ngắn'
publishDate: '2026-07-03'
tags: [Astro, Tutorial]
ogImage: '/path/to/image.jpg' # tuỳ chọn, nếu không có thì dùng OG động
---

Bạn có thể tổ chức bài viết vào thư mục con — tên thư mục sẽ thành một phần của URL. Ví dụ src/content/posts/javascript/closure.md → /posts/javascript/closure.

Tuỳ Chỉnh Giao Diện#

Màu Sắc#

Astro Paper dùng CSS variables, sửa trong src/styles/theme.css:

/* Light mode */
:root {
  --color-accent: 47, 109, 225;
  --color-accent-bg: #eef3ff;
  --color-card: #ffffff;
  --color-bg: #f8f9fa;
  --color-text: #1a1a2e;
}

/* Dark mode */
:root.dark {
  --color-accent: 98, 157, 255;
  --color-accent-bg: #1a2332;
  --color-card: #1e1e2e;
  --color-bg: #0d0d1a;
  --color-text: #e4e4e7;
}

Theme có sẵn nhiều bảng màu predefined — bạn có thể chọn hoặc tự custom.

Font#

Muốn đổi font? 3 bước:

1. Khai báo font trong astro.config.ts
2. Cập nhật component <Font /> trong src/layouts/Layout.astro
3. Sửa biến CSS --font-app trong src/styles/theme.css

Logo#

Có 3 cách:

• Text — Cấu hình trong astro-paper.config.ts
• SVG — File SVG tĩnh
• Image — Astro Image component trong Header.astro

Cấu Trúc Thư Mục#

/
├── public/              # Static assets
│   ├── pagefind/        # Tự động sinh khi build
│   └── favicon.svg
├── src/
│   ├── assets/          # Icons, images
│   ├── components/      # UI components
│   ├── content/
│   │   ├── pages/       # Trang tĩnh (about, ...)
│   │   └── posts/       # Bài viết blog
│   ├── i18n/            # Đa ngôn ngữ
│   ├── layouts/         # Page layouts
│   ├── pages/           # Route pages
│   ├── styles/          # CSS, theme
│   ├── config.ts        # Config mặc định (không sửa)
│   └── content.config.ts
├── astro-paper.config.ts # Config người dùng
└── astro.config.ts

Commands#

Deployment#

Astro Paper là static site — deploy được ở bất kỳ đâu:

• Cloudflare Pages (khuyên dùng)
• Vercel
• Netlify
• GitHub Pages

Chỉ cần kết nối repo, build command là pnpm build, output dir là dist.

So Sánh#

Astro Paper phù hợp nếu bạn muốn blog tối giản, hiệu suất cao, dễ custom, và có sẵn các tính năng core như search, OG động, i18n.

Kết Luận#

Astro Paper là một trong những theme blog Astro tốt nhất hiện tại — minimal, performance-first, accessibility-aware. Nó cung cấp đủ tính năng cho một blog chuyên nghiệp mà không làm bạn choáng ngợp.

Nếu bạn đang tìm theme để bắt đầu blog với Astro, Astro Paper là lựa chọn đáng thử nhất.

Tài liệu tham khảo#

• Astro Paper GitHub Repository ↗
• Astro Official Documentation ↗
• Pagefind — Static Search Library ↗
• Satori — OG Image Generation ↗