mirror of
https://github.com/ChenQihan666/MyBlog-Next.git
synced 2026-08-14 07:33:07 +08:00
Sat Naing
f0b644de3a
* feat: add initial configuration and social icons for AstroPaper theme * feat: add theme styles and design tokens * chore: configure Astro with sitemap, i18n, fonts, and tooling - Set site URL, i18n (single locale, no prefix), sitemap integration - Add Google Sans Code font via stable fonts API - Configure Shiki dual-theme markdown (min-light / night-owl) - Fix astro-paper.config.ts to use relative import (alias not available when Vite loads root-level config files) - Add @astrojs/sitemap and @typescript-eslint/parser dependencies - Wire @typescript-eslint/parser into ESLint so TypeScript syntax in Astro frontmatter (type Props, etc.) parses correctly * feat: add base styles, dark variant, and typography - global.css: dark variant via [data-theme], base layer for * / a / button selectors, scrollbar tokens, layout utilities (max-w-app, app-layout), active-nav as @utility for Tailwind variant support - html and body classes moved directly onto elements in BaseLayout (Tailwind-native approach) so only truly global selectors remain here - typography.css: prose overrides, Shiki light/dark code block switching, diff/highlight/word-highlight transformer styles * feat: add i18n types, English strings, and useTranslations helper Plain typed object approach — no third-party i18n library needed. Paraglide.js was considered but requires SSR output (hard blocker for a static Astro site). - UIStrings interface with nav, post, pagination, and a11y groups - en.ts with `satisfies UIStrings` for literal-type preservation - useTranslations(locale) helper falls back to English automatically Adding a new language is a one-file addition; full routing stays as a registry add-on. * feat: add client-side theme toggle script - Reads window.__theme.value set by the inline FOUC-prevention script to avoid re-detecting the theme on first load - Toggles data-theme on <html> and persists to localStorage - Fills <meta name="theme-color"> with the computed background colour so Android's browser chrome matches the page - Re-runs setup on astro:after-swap for View Transitions navigation - Carries theme-color across astro:before-swap to prevent navbar flicker on Android during page transitions - Syncs with OS prefers-color-scheme changes at runtime * feat: add BaseLayout and PostLayout BaseLayout (replaces scaffold Layout.astro): - Font, canonical URL via Astro.site, RSS autodiscovery - FOUC-prevention inline script sets data-theme before first paint and exposes window.__theme.value for theme.ts to reuse - html/body classes on elements directly (Tailwind-native) - <slot name="head"> for child layout injection - ClientRouter for View Transitions (respects lightAndDarkMode flag) - googleVerification rendered from config instead of .env — it is a public string, not a secret, and not environment-specific PostLayout (new): - Wraps BaseLayout; injects article-specific head content via slot - Overrides og:type to "article" - Adds article:published_time / article:modified_time conditionally - JSON-LD BlogPosting with conditional datePublished/dateModified (fixes old bug where absent dates produced "undefined" string) - Structured data only on actual post pages (not home/archives/tags) SiteConfig: add optional googleVerification field * chore: replace scaffold index page with BaseLayout placeholder * feat: add Header component * feat: add Footer and Socials component * chore: install dayjs, slugify, zod, @astrojs/mdx and add MDX integration * feat: add resolved config that applies defaults in one place Defaults for posts, features, socials, and shareLinks are merged in src/config.ts so all consuming code gets non-optional types with no scattered ?? fallbacks. * feat: add content schema, blog path, and post utilities Renames collection blog→posts, moves content to src/content/posts/, adds .mdx support, and adds a typed pages collection. Includes getSortedPosts, postFilter, getPath, and slugify utilities. * feat: add Datetime and Card components * refactor: switch layouts and components to resolved config Replaces @/astro-paper.config imports with @/config and removes optional chaining on feature flags now that the resolved config guarantees non-optional values. * feat: add home and footer i18n strings * feat: implement home page with hero, featured, and recent posts Replaces the BaseLayout placeholder with the full index page: hero section with RSS link and social links, featured posts section, recent posts capped at posts.perIndex, and an All Posts link. All section labels come from i18n. * feat: add pagination component * feat: add Breadcrumb component with locale support * feat: add Main component * refactor: update code formatting in Card.astro * feat: add posts page * fix: add missing @astrojs/mdx dependency * refactor: rename meta to pages in i18n * refactor: improve code formatting in Breadcrumb * refactor: destructure props in Main component for clarity * feat: add tag pages * feat: add About page * chore: update i18n configuration to use site language from config * feat: add Archives page * feat: integrate Pagefind search functionality * feat: add dynamic Open Graph image generation for posts * feat: add post detail page * feat: add Shiki transformers * chore: remove unused edit link text * chore: update .gitignore to include generated Pagefind directory * chore: update site URL in configuration to production link * chore: replace favicon and remove unused SVG assets, add new Open Graph image * feat: update site config with default values * feat: add default OG image path resolution * fix: ensure edit post feature checks for enabled status correctly * feat: implement dynamic Open Graph image generation * feat: add RSS feed generation functionality * feat: add 404 Not Found page * feat: add robots.txt generation for SEO optimization * refactor: change getSortedPosts to a named export * refactor: change postFilter to a named export * refactor: rename BaseLayout to Layout * refactor: standardize locale handling across components * refactor: update getPostsByGroupCondition location * chore: remove unused Welcome component * refactor(i18n): update links using getRelativeLocaleUrl * refactor(i18n): add dynamic locale loading * fix: update language attribute to use current locale * fix: correct wording for updatedAt in post translations * fix: update layout titles to use correct translation keys for tags pages * chore: use new colors for better DX and a11y * feat: add underline icon for active icon nav * feat: add toc for markdown contents * refactor: remove unused feature flags in config * refactor(i18n): enhance locale handling and path management * fix: ts unused variable hint * refactor: extract locale stripping logic into a util func * refactor(i18n): improve locale handling in tag pages * refactor: update post URL helper functions * refactor(i18n): replace pathWithBase with getRelativeLocaleUrl for locale handling * refactor: rename fileWithBase to getAssetPath * refactor: use runtime agnostic APIs for file paths * refactor: use transition directive for heading transition * refactor: remove unused title element from tag page * fix: decouple ClientRouter from lightAndDarkMode flag * refactor: rename `postPaths.ts` to `getPostPaths.ts` * refactor: remove unused `minutesRead` string from post translations * refactor: simplify AdjacentPostNav component by passing prevPost and nextPost directly * refactor: remove unused code declaration * docs: add existing blog posts * chore: update astro and @astrojs/check dependencies to latest versions * build: use experimental svg optimizer * chore(repo): restore project meta files and Docker configs * refactor: update code formatting with Prettier * docs: update README and docs * docs: add JSDoc comments to utility functions * docs: add JSDoc comments to resolved config file * fix(og): avoid double slashes when appending index.png * chore(ci): update Node.js version to 22.12.0 in CI workflow * feat: improve og image generation with Astro's getFontFileURL API (#632) * feat: improve og image generation with Astro's getFontFileURL API - remove @resvg/resvg-js and use sharp to convert SVG to PNG - update og image generation to use Astro's getFontFileURL API for better font handling * docs: update README and dynamic OG images documentation - remove outdated content and clarify dynamic OG image generation process in README. - add new image example and update instructions for handling non-Latin characters in dynamic OG images. - adjust copyright year in README to 2026. * fix(header): adjust icon button alignment in mobile * feat(docs): add ResponsiveTable to use it in MDX posts (#634) * feat(docs): add ResponsiveTable to use it in MDX posts Introduce ResponsiveTable with variant-based styling. Rename docs posts to .mdx, wrap tables in the component, and remove redundant table `code` rules from prose typography. * chore(prettier): ignore .mdx files when checking format * chore(ci): update Node.js version to 24 in CI workflow * bump: upgrade Astro and dependencies * fix: remove redundant backUrl script bug * fix(header): adjust button and icon alignment * fix(a11y): improve muted-foreground color contrast * docs: update predefined color schemes * chore: support site verification env as fallback for googleVerification * docs: add astro paper v6 updates in docs * docs: add AstroPaper-v6.png in astro-paper-6 blog post * fix: update back-to-top button DOM placement (#641) Closes #626, #131, #493
167 lines
7.5 KiB
Markdown
167 lines
7.5 KiB
Markdown
# AstroPaper 📄
|
|
|
|
|
|
[](https://www.figma.com/community/file/1356898632249991861)
|
|
|
|
|
|
[](https://conventionalcommits.org)
|
|
[](http://commitizen.github.io/cz-cli/)
|
|
|
|
AstroPaper is a minimal, responsive, accessible and SEO-friendly Astro blog theme. This theme is designed and crafted based on [my personal blog](https://satnaing.dev/blog).
|
|
|
|
Read [the blog posts](https://astro-paper.pages.dev/posts/) or check [the README Documentation Section](#-documentation) for more info.
|
|
|
|
## 🔥 Features
|
|
|
|
- [x] type-safe markdown
|
|
- [x] super fast performance
|
|
- [x] accessible (Keyboard/VoiceOver)
|
|
- [x] responsive (mobile ~ desktops)
|
|
- [x] SEO-friendly
|
|
- [x] light & dark mode
|
|
- [x] static search ([Pagefind](https://pagefind.app/))
|
|
- [x] draft posts & pagination
|
|
- [x] sitemap & rss feed
|
|
- [x] MDX support
|
|
- [x] collapsible table of contents
|
|
- [x] followed best practices
|
|
- [x] highly customizable
|
|
- [x] dynamic OG image generation for blog posts ([Blog Post](https://astro-paper.pages.dev/posts/dynamic-og-image-generation-in-astropaper-blog-posts/))
|
|
- [x] i18n ready
|
|
|
|
_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
|
|
|
|
<p align="center">
|
|
<a href="https://pagespeed.web.dev/report?url=https%3A%2F%2Fastro-paper.pages.dev%2F&form_factor=desktop">
|
|
<img width="710" alt="AstroPaper Lighthouse Score" src="AstroPaper-lighthouse-score.svg">
|
|
</a>
|
|
</p>
|
|
|
|
## 🚀 Project Structure
|
|
|
|
Inside of AstroPaper, you'll see the following folders and files:
|
|
|
|
```bash
|
|
/
|
|
├── public/
|
|
│ ├── pagefind/ # auto-generated on build
|
|
│ ├── favicon.svg
|
|
│ └── default-og.jpg
|
|
├── src/
|
|
│ ├── assets/
|
|
│ │ ├── icons/
|
|
│ │ └── images/
|
|
│ ├── components/
|
|
│ ├── content/
|
|
│ │ ├── pages/
|
|
│ │ │ └── about.md
|
|
│ │ └── posts/
|
|
│ │ └── some-blog-posts.md
|
|
│ ├── i18n/
|
|
│ ├── layouts/
|
|
│ ├── pages/
|
|
│ ├── scripts/
|
|
│ ├── styles/
|
|
│ ├── types/
|
|
│ ├── utils/
|
|
│ ├── config.ts
|
|
│ └── content.config.ts
|
|
├── astro-paper.config.ts # user-defined configurations
|
|
└── astro.config.ts
|
|
```
|
|
|
|
All blog posts are stored in the `src/content/posts/` directory. You can organise posts into subdirectories — the subdirectory name becomes part of the post URL.
|
|
|
|
## 📖 Documentation
|
|
|
|
Documentation can be read in two formats\_ _markdown_ & _blog post_.
|
|
|
|
- Configuration - [markdown](src/content/posts/how-to-configure-astropaper-theme.md) | [blog post](https://astro-paper.pages.dev/posts/how-to-configure-astropaper-theme/)
|
|
- Add Posts - [markdown](src/content/posts/adding-new-post.md) | [blog post](https://astro-paper.pages.dev/posts/adding-new-posts-in-astropaper-theme/)
|
|
- Customize Color Schemes - [markdown](src/content/posts/customizing-astropaper-theme-color-schemes.md) | [blog post](https://astro-paper.pages.dev/posts/customizing-astropaper-theme-color-schemes/)
|
|
- Predefined Color Schemes - [markdown](src/content/posts/predefined-color-schemes.md) | [blog post](https://astro-paper.pages.dev/posts/predefined-color-schemes/)
|
|
|
|
## 💻 Tech Stack
|
|
|
|
**Main Framework** - [Astro](https://astro.build/)
|
|
**Type Checking** - [TypeScript](https://www.typescriptlang.org/)
|
|
**Styling** - [TailwindCSS](https://tailwindcss.com/)
|
|
**UI/UX** - [Figma Design File](https://www.figma.com/community/file/1356898632249991861)
|
|
**Static Search** - [Pagefind](https://pagefind.app/)
|
|
**Icons** - [Tablers](https://tabler-icons.io/)
|
|
**Code Formatting** - [Prettier](https://prettier.io/)
|
|
**Deployment** - [Cloudflare Pages](https://pages.cloudflare.com/)
|
|
**Linting** - [ESLint](https://eslint.org)
|
|
**Dynamic OG images** - [Satori](https://github.com/vercel/satori) + [Sharp](https://sharp.pixelplumbing.com/) + [Astro Fonts](https://docs.astro.build/en/guides/fonts/)
|
|
|
|
## 👨🏻💻 Running Locally
|
|
|
|
You can start using this project locally by running the following command in your desired directory:
|
|
|
|
```bash
|
|
# pnpm
|
|
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
|
|
```
|
|
|
|
Then start the project by running the following commands:
|
|
|
|
```bash
|
|
# install dependencies if you haven't done so in the previous step.
|
|
pnpm install
|
|
|
|
# start running the project
|
|
pnpm dev
|
|
```
|
|
|
|
## Google Site Verification (optional)
|
|
|
|
You can add your [Google Site Verification HTML tag](https://support.google.com/webmasters/answer/9008080#meta_tag_verification&zippy=%2Chtml-tag) by setting `site.googleVerification` in `astro-paper.config.ts`:
|
|
|
|
```ts file="astro-paper.config.ts"
|
|
export default defineAstroPaperConfig({
|
|
site: {
|
|
// ...
|
|
googleVerification: "your-google-site-verification-value",
|
|
},
|
|
// ...
|
|
});
|
|
```
|
|
|
|
> See [this discussion](https://github.com/satnaing/astro-paper/discussions/334#discussioncomment-10139247) for adding AstroPaper to the Google Search Console.
|
|
|
|
## 🧞 Commands
|
|
|
|
All commands are run from the root of the project, from a terminal:
|
|
|
|
| Command | Action |
|
|
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `pnpm install` | Installs dependencies |
|
|
| `pnpm dev` | Starts local dev server at `localhost:4321` |
|
|
| `pnpm build` | Type-checks, builds the site, runs Pagefind indexing, and copies the index to `public/pagefind/` |
|
|
| `pnpm preview` | Preview your build locally, before deploying |
|
|
| `pnpm sync` | Generates TypeScript types for all Astro modules. [Learn more](https://docs.astro.build/en/reference/cli-reference/#astro-sync). |
|
|
| `pnpm astro ...` | Run CLI commands like `astro add`, `astro check` |
|
|
|
|
## ✨ Feedback & Suggestions
|
|
|
|
If you have any suggestions/feedback, you can contact me via [my email](mailto:satnaingdev+astropaper@gmail.com). Alternatively, feel free to open an issue if you find bugs or want to request new features.
|
|
|
|
## 📜 License
|
|
|
|
Licensed under the MIT License, Copyright © 2026
|
|
|
|
---
|
|
|
|
Made with 🤍 by [Sat Naing](https://satnaing.dev) 👨🏻💻 and [contributors](https://github.com/satnaing/astro-paper/graphs/contributors).
|