Upgrading

Upgrading

Table of Contents

• Updating npm dependencies
• Updating the AstroPaper template
• Version history

Updating npm Dependencies

Use npm-check-updates for a controlled upgrade process.

1. Install globally:

npm install -g npm-check-updates

2. Check available updates:

ncu

3. Apply patch updates (safest):

ncu -u --target patch
pnpm install

4. Apply minor updates (usually safe — check release notes):

ncu -i --target minor
pnpm install

5. Check remaining major updates:

ncu -i

Major version updates (e.g. Astro v5 → v6) are likely to include breaking changes. Read the release notes for each package before upgrading. After each batch of updates, run pnpm build to verify nothing broke.

Updating the AstroPaper Template

When AstroPaper releases a new version, you may want to pull in the upstream changes. There are two approaches:

Option A: Manual file replacement

Compare the release diff on GitHub and manually copy changed files into your project. Skip files you've customized:

• src/content/posts/ — your blog posts
• astro-paper.config.ts — your site config
• src/content/pages/about.md — your About page
• src/styles/theme.css — if you've customized colors
• public/ — your assets

This is tedious but safe if you have many customizations.

Option B: Git merge from upstream

Only do this if you are comfortable resolving merge conflicts.

1. Add AstroPaper as a remote:

git remote add astro-paper https://github.com/satnaing/astro-paper.git

2. Create a branch for the update:

git checkout -b update/astro-paper-vX

3. Pull the latest changes:

git pull astro-paper main

If you see fatal: refusing to merge unrelated histories:

git pull astro-paper main --allow-unrelated-histories

4. Resolve conflicts — keep your content, config, and styles; accept upstream changes for components, layouts, and utilities.

5. Test thoroughly:

pnpm build && pnpm preview

6. Merge to main once satisfied.

Version History

v6.1.0 (2026-06-06)

• Added callout support (Obsidian-style, via rehype-callouts)
• Added accessible image lightbox for post images
• Fixed post title sanitization for view transition names
• Fixed RSS link
• Various bug fixes

v6.0.0 (2026-05-17) — Breaking changes

Breaking changes:

• User configuration moved to astro-paper.config.ts; src/config.ts is now internal only
• Blog content moved from src/data/blog/ to src/content/posts/
• Pages content moved to src/content/pages/

New features:

• Typed user-facing configuration with defineAstroPaperConfig()
• MDX support
• Pagefind static full-text search
• Archives page
• Table of contents (collapsible)
• Share links on post pages
• "Edit page" link
• "Back" button on posts
• Per-post timezone support
• RTL language direction support
• Shiki code transformers (diff, highlight, word highlight, filename)
• Astro Fonts API integration (Google Sans Code)
• Base path support
• Upgraded to Astro v6

v5.x (2025)

• Added Shiki transformers for enhanced code blocks
• Added sitemap and RSS improvements
• Various accessibility and style fixes

v4.x (2024)

• Added MDX support (v4.0)
• Dynamic OG image generation
• VS Code snippets
• GitHub Actions for date automation

v3.x (2023)

• Added search (fuzzy search with Fuse.js, later replaced by Pagefind in v6)
• Added sitemap integration
• Performance improvements

v2.x (2023)

• Draft post support
• Pagination
• Tag system improvements

v1.x (2022)

• Initial release with core blog functionality
• Light/dark mode
• RSS feed
• Dynamic OG image generation (v1.4.0)