Skip to content

Configuration

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

Configuration

All site-wide configuration lives in astro-paper.config.ts at the project root. Use defineAstroPaperConfig() to get full TypeScript IntelliSense.

Table of Contents

Full example

// astro-paper.config.ts
import { defineAstroPaperConfig } from "./src/types/config";

export default defineAstroPaperConfig({
  site: {
    url: "https://your-site.com/",
    title: "My Blog",
    description: "A blog about things I find interesting.",
    author: "Your Name",
    profile: "https://yourportfolio.com",
    ogImage: "default-og.jpg",
    lang: "en",
    timezone: "America/New_York",
    dir: "ltr",
  },
  posts: {
    perPage: 4,
    perIndex: 4,
    scheduledPostMargin: 15 * 60 * 1000,
  },
  features: {
    lightAndDarkMode: true,
    dynamicOgImage: true,
    showArchives: true,
    showBackButton: true,
    editPost: {
      enabled: true,
      url: "https://github.com/your-username/your-repo/edit/main/",
    },
    search: "pagefind",
  },
  socials: [
    { name: "github", url: "https://github.com/your-username" },
    { name: "x", url: "https://x.com/your-handle" },
    { name: "linkedin", url: "https://www.linkedin.com/in/your-profile/" },
    { name: "mail", url: "mailto:you@example.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

These fields go inside the site object.

Option Type Required Description
url string Yes Deployed URL of the site (e.g. "https://example.com/"). Used for canonical URLs, OG image URLs, RSS feed, and sitemap. Must be set correctly for production.
title string Yes Blog title shown in the header and meta tags.
description string Yes Short description used in SEO meta tags and the RSS feed.
author string Yes Default post author name. Can be overridden per post in frontmatter.
profile string No Author profile/portfolio URL. Used in structured data (JSON-LD).
ogImage string No Filename of the fallback OG image in /public (e.g. "default-og.jpg"). Used when no post-specific OG image is set and dynamicOgImage is disabled.
lang string No HTML lang attribute value (e.g. "en", "ja"). Defaults to "en".
timezone string No IANA timezone for post dates (e.g. "Asia/Bangkok", "America/New_York"). Ensures consistent timestamps between localhost and your deployed site.
dir "ltr" | "rtl" | "auto" No Text direction for <html dir="...">. Defaults to "ltr".
googleVerification string No Google Search Console verification meta tag value. Also settable via PUBLIC_GOOGLE_SITE_VERIFICATION environment variable; config value takes precedence.

Posts options

These fields go inside the posts object.

Option Type Default Description
perPage number 4 Posts shown per page on paginated listing pages (/posts/, tag pages).
perIndex number 4 Posts shown in the "Recent Posts" section on the home page.
scheduledPostMargin number (ms) 900000 (15 min) Posts with a pubDatetime in the future, but within this window, are treated as published. Useful for deployments that happen slightly before the post's publish time.

Features options

These fields go inside the features object.

Option Type Default Description
lightAndDarkMode boolean true Enable the light/dark mode toggle. When false, only the light color scheme from theme.css is used.
dynamicOgImage boolean true Generate a dynamic OG image for each post that doesn't have an ogImage in frontmatter. Disable on very large sites to speed up builds.
showArchives boolean true Show the /archives page and its link in the nav.
showBackButton boolean true Show a "Go back" button at the top of each post page.
editPost object | {enabled: false} — Show an "Edit page" link on post pages. Set enabled: true and provide url (the base URL for your repository's edit endpoint). Can be hidden per post using the hideEditPost frontmatter field.
search "pagefind" | false "pagefind" Search provider. "pagefind" uses the Pagefind static search index built during pnpm build. Set to false to disable search entirely.

Edit post URL example

For a GitHub repository, the edit URL would look like:

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

AstroPaper appends the post file path (e.g. src/content/posts/my-post.md) to this base URL.

Socials

The socials array configures the social profile links shown in the header and footer.

Each entry requires:

  • name — must match an SVG filename (without .svg) in src/assets/icons/socials/
  • url — the full URL to your profile

Optional:

  • linkTitle — custom accessible label (aria-label / title). Auto-generated if omitted (e.g. "My Blog on GitHub", "Send an email to My Blog").

Built-in icons available: github, x, linkedin, facebook, whatsapp, telegram, pinterest, mail.

To add a custom social network, place an SVG in src/assets/icons/socials/ and add the entry.

socials: [
  { name: "github", url: "https://github.com/your-username" },
  { name: "mail",   url: "mailto:you@example.com" },
],

Share Links

The shareLinks array configures the share buttons shown on post detail pages.

Each entry requires:

  • name — must match an SVG filename in src/assets/icons/socials/
  • url — the base share URL. The current post URL is appended to it.

Optional:

  • linkTitle — custom accessible label. Auto-generated if omitted.
shareLinks: [
  { name: "x",        url: "https://x.com/intent/post?url=" },
  { name: "telegram", url: "https://t.me/share/url?url=" },
],

Google Site Verification

Set the site.googleVerification field in astro-paper.config.ts:

site: {
  // ...
  googleVerification: "your-verification-token",
},

Alternatively, set the PUBLIC_GOOGLE_SITE_VERIFICATION environment variable. The config value takes precedence if both are set.

AstroPaper

Getting Started

Writing Content

Features & Reference

Deployment

Links

Clone this wiki locally