Skip to content

Features

Jump to bottom
satnaing edited this page Jun 6, 2026 · 1 revision

Features

An overview of all built-in features in AstroPaper.

Table of Contents

Light and Dark Mode

AstroPaper ships with both light and dark color schemes. The active theme is determined by:

  1. The user's last-saved preference (stored in localStorage)
  2. The system preference (prefers-color-scheme media query) if no saved preference exists

A toggle button in the header lets users switch between themes. The switch is animated and ARIA-labelled for screen readers.

To disable the toggle and force the light theme only, set features.lightAndDarkMode: false in astro-paper.config.ts.

Static Search

Full-text search is powered by Pagefind, a fully static search library with no server required.

  • The search index is built during pnpm build and placed in public/pagefind/
  • The search UI is accessible at /search
  • The search bar in the header navigates to the search page
  • Results include post titles, descriptions, and content excerpts

Search is automatically focused when the search page loads. To disable search entirely, set features.search: false.

SEO

AstroPaper is optimized for search engines out of the box:

  • Title tags — <title> uses post.title | site.title format
  • Meta description — from post.description or site.description
  • Canonical URLs — auto-generated from site.url + path; can be overridden per post via canonicalURL frontmatter
  • Open Graph — og:title, og:description, og:image, og:url, og:type
  • Twitter cards — twitter:card, twitter:title, twitter:description, twitter:image
  • JSON-LD structured data — BlogPosting schema on post pages
  • Sitemap — auto-generated at /sitemap-index.xml
  • robots.txt — permissive by default, auto-generated at /robots.txt

Dynamic OG Images

When features.dynamicOgImage is enabled, AstroPaper generates a unique OG image for each published post that has no ogImage in frontmatter.

The generated image includes:

  • Post title
  • Author name (from site.author)
  • Site title (from site.title)

Images are generated at build time using Satori + Sharp. The font is sourced from Astro's Fonts configuration, matching the site's typeface.

Caveats:

  • Build time increases with content volume (one PNG per eligible post)
  • RTL languages are not yet supported in generated images
  • Non-Latin characters require a Google Font with coverage for those scripts

See Customization → OG images for full details.

RSS Feed

An RSS feed is auto-generated at /rss.xml. It includes all published, non-draft posts sorted by publication date descending.

The feed uses site.title, site.description, and site.url from astro-paper.config.ts. No additional configuration is required.

Sitemap

A sitemap is auto-generated at build time via @astrojs/sitemap. It is available at /sitemap-index.xml.

The archives page is excluded from the sitemap when features.showArchives is false.

Reading Time

AstroPaper does not include a built-in reading time display. The theme focuses on clean, minimal output and omits it by default. You can add reading time estimation via a remark plugin if desired.

Tag System

Each post can have one or more tags defined in the tags frontmatter array. Tags are used to:

  • Display tag badges on post cards and post headers
  • Generate a tags index page at /tags/
  • Generate individual tag pages at /tags/[tag]/ with paginated post listings

If a post has no tags field, it is assigned the default tag "others". The default tag name can be changed in src/content.config.ts.

Archives Page

An archives page at /archives/ lists all posts grouped by year. It can be enabled or disabled via features.showArchives in astro-paper.config.ts. The archives link also appears in the site navigation when enabled.

Pagination

Post listing pages use pagination controlled by posts.perPage in astro-paper.config.ts (default: 4 posts per page). The home page uses posts.perIndex for the Recent Posts section.

Paginated pages include accessible Previous / Next navigation with proper ARIA labels.

Table of Contents

Posts can include a collapsible table of contents. To add one, include a level-2 heading ## Table of contents in the post body:

## Table of contents

## Section One

Content...

The TOC is generated from all headings in the post and rendered as a collapsible section above the content where the heading is placed.

Callouts

AstroPaper v6.1+ supports callouts using blockquote syntax (Obsidian-style via rehype-callouts):

> [!NOTE]
> Supplementary information.

> [!TIP]+ Expandable tip
> Starts open but can be collapsed.

Supported types: NOTE, TIP, INFO, WARNING, DANGER, SUCCESS, BUG, EXAMPLE, QUOTE, and more. See Writing Posts → Callouts for full details.

Image Lightbox

AstroPaper v6.1+ includes an accessible image lightbox for post images. Clicking any image in a post opens it in a full-screen overlay with keyboard navigation support (Escape to close, arrow keys if applicable).

The lightbox is implemented without any third-party JavaScript library.

Draft Posts

Set draft: true in a post's frontmatter to exclude it from the build. Draft posts are not rendered, not indexed by Pagefind, and not included in the RSS feed or sitemap.

Draft posts are visible in development (pnpm dev) so you can preview them locally.

Scheduled Posts

Posts with a pubDatetime in the future are treated as unpublished and excluded from listings and feeds. However, posts with a pubDatetime within the posts.scheduledPostMargin window (default: 15 minutes before pubDatetime) are shown as published.

This helps with deployments triggered slightly before a post's intended publish time.

Share Links

Post detail pages include share buttons configured via the shareLinks array in astro-paper.config.ts. The post URL is appended to each share URL.

Built-in share targets: X (Twitter), Facebook, WhatsApp, Telegram, Pinterest, email. Custom targets can be added by placing an SVG in src/assets/icons/socials/.

Edit Page Link

An "Edit page" link can be shown below the post title, linking to the post's source file in your repository. Configure it in astro-paper.config.ts:

features: {
  editPost: {
    enabled: true,
    url: "https://github.com/your-username/your-repo/edit/main/",
  },
},

Individual posts can hide the link by setting hideEditPost: true in frontmatter.

Breadcrumbs

Post pages show a breadcrumb trail (e.g. Home > Posts > Post Title) for orientation and navigation. This is rendered automatically and requires no configuration.

View Transitions

AstroPaper uses Astro's <ClientRouter /> for page transitions. Navigation between pages is animated smoothly. Post cards have view transition names tied to the post slug for a coordinated transition effect.

Accessibility

AstroPaper follows WCAG guidelines:

  • Semantic HTML throughout
  • Skip-to-content link for keyboard users
  • ARIA labels on all interactive elements (theme toggle, search, menu, pagination, share buttons)
  • Keyboard-navigable mobile menu
  • Sufficient color contrast in both light and dark themes
  • Screen reader support tested with VoiceOver (macOS) and TalkBack (Android)

robots.txt

A robots.txt is auto-generated at build time. The default allows all crawlers on all pages. It is defined in src/pages/robots.txt.ts and can be customized there.

AstroPaper

Getting Started

Writing Content

Features & Reference

Deployment

Links

Clone this wiki locally