mirror of
https://github.com/ChenQihan666/MyBlog-Next.git
synced 2026-08-14 19:41:02 +08:00
feat!: AstroPaper v6 (#631)
* 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
This commit is contained in:
Sat Naing
@@ -0,0 +1,304 @@
|
||||
---
|
||||
author: Sat Naing
|
||||
pubDatetime: 2022-09-23T04:58:53Z
|
||||
modDatetime: 2026-05-17T05:50:08.212Z
|
||||
title: How to configure AstroPaper theme
|
||||
slug: how-to-configure-astropaper-theme
|
||||
featured: true
|
||||
draft: false
|
||||
tags:
|
||||
- configuration
|
||||
- docs
|
||||
description: How you can make AstroPaper theme absolutely yours.
|
||||
---
|
||||
import ResponsiveTable from '@/components/ResponsiveTable.astro';
|
||||
|
||||
This guide covers the available configuration options in AstroPaper — from site metadata and feature flags to fonts, social links, and layout settings.
|
||||
|
||||
## Table of contents
|
||||
|
||||
## Configuring astro-paper.config.ts
|
||||
|
||||
All site-wide configuration lives in `astro-paper.config.ts` at the root of the project. Use `defineAstroPaperConfig()` to get full IntelliSense support:
|
||||
|
||||
```ts file="astro-paper.config.ts"
|
||||
import { defineAstroPaperConfig } from "./src/types/config";
|
||||
|
||||
export default defineAstroPaperConfig({
|
||||
site: {
|
||||
url: "https://your-site.com/", // replace with your deployed URL
|
||||
title: "AstroPaper",
|
||||
description: "A minimal, responsive and SEO-friendly Astro blog theme.",
|
||||
author: "Sat Naing",
|
||||
profile: "https://satnaing.dev",
|
||||
ogImage: "default-og.jpg",
|
||||
lang: "en",
|
||||
timezone: "Asia/Bangkok",
|
||||
dir: "ltr",
|
||||
},
|
||||
posts: {
|
||||
perPage: 4,
|
||||
perIndex: 4,
|
||||
scheduledPostMargin: 15 * 60 * 1000, // 15 minutes
|
||||
},
|
||||
features: {
|
||||
lightAndDarkMode: true,
|
||||
dynamicOgImage: true,
|
||||
showArchives: true,
|
||||
showBackButton: true,
|
||||
editPost: {
|
||||
enabled: true,
|
||||
url: "https://github.com/satnaing/astro-paper/edit/main/",
|
||||
},
|
||||
search: "pagefind",
|
||||
},
|
||||
socials: [
|
||||
{ name: "github", url: "https://github.com/satnaing/astro-paper" },
|
||||
{ name: "x", url: "https://x.com/username" },
|
||||
{ name: "linkedin", url: "https://www.linkedin.com/in/username/" },
|
||||
{ name: "mail", url: "mailto:yourmail@gmail.com" },
|
||||
],
|
||||
shareLinks: [
|
||||
{ name: "whatsapp", url: "https://wa.me/?text=" },
|
||||
{ name: "facebook", url: "https://www.facebook.com/sharer.php?u=" },
|
||||
{ name: "x", url: "https://x.com/intent/post?url=" },
|
||||
{ name: "telegram", url: "https://t.me/share/url?url=" },
|
||||
{ name: "mail", url: "mailto:?subject=See%20this%20post&body=" },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### `site` options
|
||||
|
||||
<ResponsiveTable>
|
||||
|
||||
| Option | Description |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `url` | Your deployed website URL. Used for canonical URLs, OG image URLs, RSS feed, and sitemap. In production this must be set correctly. |
|
||||
| `title` | Your site name. |
|
||||
| `description` | Your site description. Useful for SEO and social media sharing. |
|
||||
| `author` | Your name. Used as the default post author. |
|
||||
| `profile` | Your personal/portfolio website URL, used for structured data. Set to `undefined` if you don't have one. |
|
||||
| `ogImage` | Default OG image filename in `/public` (e.g. `"default-og.jpg"`). Used when no post-specific OG image is set and `dynamicOgImage` is disabled. |
|
||||
| `lang` | HTML ISO language code for `<html lang="...">`. Defaults to `"en"`. |
|
||||
| `timezone` | IANA timezone for post dates (e.g. `"Asia/Bangkok"`). Ensures consistent timestamps across localhost and your deployed site. |
|
||||
| `dir` | Text direction for `<html dir="...">`. Supports `"ltr"` \| `"rtl"` \| `"auto"`. |
|
||||
| `googleVerification` | Google Search Console verification meta tag value. Optional. Takes precedence over the `PUBLIC_GOOGLE_SITE_VERIFICATION` environment variable. |
|
||||
|
||||
</ResponsiveTable>
|
||||
|
||||
### `posts` options
|
||||
|
||||
<ResponsiveTable>
|
||||
|
||||
| Option | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `perPage` | Number of posts shown per page on paginated listing pages. Defaults to `4`. |
|
||||
| `perIndex` | Number of posts shown in the Recent section on the home page. Defaults to `4`. |
|
||||
| `scheduledPostMargin` | Posts with a future `pubDatetime` within this window (in ms) are treated as published. Defaults to 15 minutes (`15 * 60 * 1000`). |
|
||||
|
||||
</ResponsiveTable>
|
||||
|
||||
### `features` options
|
||||
|
||||
<ResponsiveTable>
|
||||
|
||||
| Option | Description |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `lightAndDarkMode` | Enable or disable the light/dark mode toggle. Defaults to `true`. |
|
||||
| `dynamicOgImage` | Generate a dynamic OG image per post when no `ogImage` is specified in frontmatter. Defaults to `true`. See the [trade-off](https://astro-paper.pages.dev/posts/dynamic-og-image-generation-in-astropaper-blog-posts/#trade-off) for details. |
|
||||
| `showArchives` | Show the `/archives` page and its header link. Defaults to `true`. |
|
||||
| `showBackButton` | Show the "Go back" button on post pages. Defaults to `true`. |
|
||||
| `editPost` | An "Edit page" link shown under post titles. Set `enabled: true` and provide the base `url` for your repository's edit URL. Per-post override via `hideEditPost` frontmatter. |
|
||||
| `search` | Search provider. `"pagefind"` is the default. Set to `false` to disable search entirely. |
|
||||
|
||||
</ResponsiveTable>
|
||||
|
||||
## Update layout width
|
||||
|
||||
The default `max-width` for the entire blog is `768px` (`max-w-3xl`). If you'd like to change it, update the `max-w-app` utility in `src/styles/global.css`:
|
||||
|
||||
```css file="src/styles/global.css"
|
||||
@utility max-w-app {
|
||||
/* [!code --:1] */
|
||||
@apply max-w-3xl;
|
||||
/* [!code ++:1] */
|
||||
@apply max-w-4xl xl:max-w-5xl;
|
||||
}
|
||||
```
|
||||
|
||||
You can explore more `max-width` values in the [Tailwind CSS docs](https://tailwindcss.com/docs/max-width).
|
||||
|
||||
## Configuring logo or title
|
||||
|
||||
|
||||
|
||||
There are 3 options you can do:
|
||||
|
||||
### Option 1: Site title text
|
||||
|
||||
This is the easiest option. Update `site.title` in `astro-paper.config.ts`.
|
||||
|
||||
### Option 2: Astro's SVG component
|
||||
|
||||
You might want to use this option if you want to use an SVG logo.
|
||||
|
||||
- First add an SVG inside `src/assets/` directory. (e.g. `src/assets/dummy-logo.svg`)
|
||||
- Then import that SVG inside `Header.astro`
|
||||
|
||||
```astro file="src/components/Header.astro"
|
||||
---
|
||||
// ...
|
||||
import DummyLogo from "@/assets/dummy-logo.svg";
|
||||
---
|
||||
```
|
||||
|
||||
- Finally, replace `{config.site.title}` with imported logo.
|
||||
|
||||
```html
|
||||
<a
|
||||
href="/"
|
||||
class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
|
||||
>
|
||||
<DummyLogo class="scale-75 dark:invert" />
|
||||
<!-- {config.site.title} -->
|
||||
</a>
|
||||
```
|
||||
|
||||
The best part of this approach is that you can customize your SVG styles as needed. In the example above, you can see how the SVG logo color can be inverted in dark mode.
|
||||
|
||||
### Option 3: Astro's Image component
|
||||
|
||||
If your logo is an image but not SVG, you can use Astro's Image component.
|
||||
|
||||
- Add your logo inside `src/assets/` directory. (e.g. `src/assets/dummy-logo.png`)
|
||||
- Import `Image` and your logo in `Header.astro`
|
||||
|
||||
```astro file="src/components/Header.astro"
|
||||
---
|
||||
// ...
|
||||
import { Image } from "astro:assets";
|
||||
import dummyLogo from "@/assets/dummy-logo.png";
|
||||
---
|
||||
```
|
||||
|
||||
- Then, replace `{config.site.title}` with imported logo.
|
||||
|
||||
```html
|
||||
<a
|
||||
href="/"
|
||||
class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
|
||||
>
|
||||
<image src="{dummyLogo}" alt="My Blog" class="dark:invert" />
|
||||
<!-- {config.site.title} -->
|
||||
</a>
|
||||
```
|
||||
|
||||
With this approach, you can still adjust your image's appearance using CSS classes. However, this might not always fit what you want. If you need to display different logo images based on light or dark mode, check how light/dark icons are handled inside the `Header.astro` component.
|
||||
|
||||
## Configuring social links
|
||||
|
||||
|
||||
|
||||
Social links are configured in the `socials` array inside `astro-paper.config.ts`. Each entry requires a `name` matching an SVG filename in `src/assets/icons/socials/` and a `url`:
|
||||
|
||||
```ts file="astro-paper.config.ts"
|
||||
export default defineAstroPaperConfig({
|
||||
// ...
|
||||
socials: [
|
||||
{ name: "github", url: "https://github.com/satnaing/astro-paper" },
|
||||
{ name: "x", url: "https://x.com/username" },
|
||||
{ name: "linkedin", url: "https://www.linkedin.com/in/username/" },
|
||||
{ name: "mail", url: "mailto:yourmail@gmail.com" },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
To add a social not in the defaults, add its SVG icon to `src/assets/icons/socials/` and add an entry to the array. The `name` must match the SVG filename without the `.svg` extension.
|
||||
|
||||
## Configuring share links
|
||||
|
||||
|
||||
|
||||
Share links are configured in the `shareLinks` array. Each entry requires a `name` (matching an SVG in `src/assets/icons/socials/`) and a base `url` to which the post URL is appended:
|
||||
|
||||
```ts file="astro-paper.config.ts"
|
||||
export default defineAstroPaperConfig({
|
||||
// ...
|
||||
shareLinks: [
|
||||
{ name: "whatsapp", url: "https://wa.me/?text=" },
|
||||
{ name: "facebook", url: "https://www.facebook.com/sharer.php?u=" },
|
||||
{ name: "x", url: "https://x.com/intent/post?url=" },
|
||||
{ name: "telegram", url: "https://t.me/share/url?url=" },
|
||||
{ name: "mail", url: "mailto:?subject=See%20this%20post&body=" },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Configuring fonts
|
||||
|
||||
AstroPaper uses Astro's [fonts API](https://docs.astro.build/en/guides/fonts/) with [Google Sans Code](https://fonts.google.com/specimen/Google+Sans+Code) as the default font. This provides consistent typography across all platforms with automatic font optimizations including preloading and caching.
|
||||
|
||||
### Using the default font
|
||||
|
||||
The font is automatically configured in `astro.config.ts` and loaded in `Layout.astro`. No additional configuration is needed to use the default Google Sans Code font.
|
||||
|
||||
### Customizing the font
|
||||
|
||||
To use a different font, update three places:
|
||||
|
||||
1. **Update the font configuration in `astro.config.ts`:**
|
||||
|
||||
```ts file="astro.config.ts"
|
||||
import { defineConfig, fontProviders } from "astro/config";
|
||||
|
||||
export default defineConfig({
|
||||
// ...
|
||||
fonts: [
|
||||
{
|
||||
name: "Your Font Name", // [!code highlight]
|
||||
cssVariable: "--font-your-font", // [!code highlight]
|
||||
provider: fontProviders.google(),
|
||||
fallbacks: ["monospace"],
|
||||
weights: [300, 400, 500, 600, 700],
|
||||
styles: ["normal", "italic"],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
2. **Update the Font component in `Layout.astro`:**
|
||||
|
||||
```astro file="src/layouts/Layout.astro"
|
||||
---
|
||||
import { Font } from "astro:assets";
|
||||
// ...
|
||||
---
|
||||
|
||||
<head>
|
||||
<!-- ... -->
|
||||
<Font
|
||||
cssVariable="--font-your-font"
|
||||
preload={[{ subset: "latin", weight: 400, style: "normal" }]}
|
||||
/>
|
||||
<!-- ... -->
|
||||
</head>
|
||||
```
|
||||
|
||||
3. **Update the CSS variable mapping in `src/styles/theme.css`:**
|
||||
|
||||
```css file="src/styles/theme.css"
|
||||
@theme inline {
|
||||
--font-app: var(--font-your-font); /* [!code highlight] */
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
The `--font-app` variable is used throughout the theme via the `font-app` Tailwind utility class, so updating this single variable applies your custom font everywhere.
|
||||
|
||||
> **Note**: Make sure the font name matches exactly as it appears on [Google Fonts](https://fonts.google.com). For other font providers or local fonts, refer to the [Astro Fonts documentation](https://docs.astro.build/en/guides/fonts/).
|
||||
|
||||
## See also
|
||||
|
||||
- [Customizing AstroPaper theme color schemes](https://astro-paper.pages.dev/posts/customizing-astropaper-theme-color-schemes/) — change or add color schemes via `src/styles/theme.css`.
|
||||
- [Adding new posts](https://astro-paper.pages.dev/posts/adding-new-posts-in-astropaper-theme/) — frontmatter reference and file conventions.
|
||||
Reference in New Issue
Block a user