Customization

Customization

Table of Contents

• Color schemes
• Light and dark mode
• Fonts
• Logo
• Layout width
• Social links
• OG images

Color Schemes

Both the light and dark color schemes are defined as CSS custom properties in src/styles/theme.css.

/* Light theme */
:root,
[data-theme="light"] {
  --background: #fdfdfd;
  --foreground: #282728;
  --accent: #006cac;
  --accent-foreground: #ffffff;
  --muted: #e6e6e6;
  --muted-foreground: #6b7280;
  --border: #ece9e9;
}

/* Dark theme */
[data-theme="dark"] {
  --background: #212737;
  --foreground: #eaedf3;
  --accent: #ff6b01;
  --accent-foreground: #ffffff;
  --muted: #343f60;
  --muted-foreground: #afb9ca;
  --border: #ab4b08;
}

Color property reference

Property	Usage
--background	Main page background
--foreground	Primary text color
--accent	Links, hover states, interactive elements
--accent-foreground	Text on top of accent-colored backgrounds
--muted	Cards, tags, subtle backgrounds
--muted-foreground	Text on top of muted backgrounds
--border	Dividers and borders

To create a custom scheme, replace the hex values in :root, [data-theme="light"] and [data-theme="dark"].

Example: warm light theme

:root,
[data-theme="light"] {
  --background: #f6eee1;
  --foreground: #012c56;
  --accent: #e14a39;
  --accent-foreground: #ffffff;
  --muted: #efd8b0;
  --muted-foreground: #6b7280;
  --border: #dc9891;
}

These CSS variables are mapped to Tailwind v4 design tokens in the @theme block at the top of theme.css, so they work with all Tailwind color utilities like bg-background, text-foreground, text-accent, etc.

Light and Dark Mode

Light/dark mode is enabled by default. To disable it:

// astro-paper.config.ts
features: {
  lightAndDarkMode: false,
},

When disabled, only the light color scheme from theme.css is applied. The theme toggle button is hidden.

Fonts

AstroPaper uses Google Sans Code via Astro's Fonts API.

Changing the font

Three files must be updated:

1. astro.config.ts — change the font name and CSS variable:

fonts: [
  {
    name: "Inter",
    cssVariable: "--font-inter",
    provider: fontProviders.google(),
    fallbacks: ["sans-serif"],
    weights: [300, 400, 500, 600, 700],
    styles: ["normal", "italic"],
  },
],

2. src/layouts/Layout.astro — update the cssVariable prop:

<Font
  cssVariable="--font-inter"
  preload={[{ subset: "latin", weight: 400, style: "normal" }]}
/>

3. src/styles/theme.css — point --font-app to the new variable:

@theme inline {
  --font-app: var(--font-inter);
  /* ... other tokens */
}

The --font-app variable drives the font-app Tailwind utility class used throughout the theme. Updating this single variable applies your custom font everywhere.

For non-Latin scripts (Japanese, Arabic, Chinese, etc.), choose a Google Font that covers those characters. Include both 400 and 700 weights, as Satori (used for dynamic OG images) requires separate buffers for each.

Logo

There are three ways to set up your site logo/name in the header.

Option 1: Text title

Update site.title in astro-paper.config.ts. The title text is displayed in the header automatically.

Option 2: SVG logo

1. Add your SVG to src/assets/ (e.g. src/assets/my-logo.svg)

2. Import it in src/components/Header.astro:

   ---
   import MyLogo from "@/assets/my-logo.svg";
   ---

3. Replace {config.site.title} with the SVG component:

   <a href="/" class="...">
     <MyLogo class="scale-75 dark:invert" />
   </a>

SVG logos can be styled with CSS classes. The dark:invert class inverts the logo in dark mode.

Option 3: Image logo

1. Add your image to src/assets/ (e.g. src/assets/my-logo.png)

2. Import Image and your logo in src/components/Header.astro:

   ---
   import { Image } from "astro:assets";
   import myLogo from "@/assets/my-logo.png";
   ---

3. Replace {config.site.title}:

   <a href="/" class="...">
     <image src="{myLogo}" alt="My Blog" class="dark:invert" />
   </a>

For separate light and dark logos, look at how the theme toggle icons are handled inside Header.astro to see the pattern.

Layout Width

The default maximum content width is 768px (max-w-3xl). To change it, update the max-w-app utility in src/styles/global.css:

@utility max-w-app {
  @apply max-w-3xl; /* change to max-w-4xl, max-w-5xl, etc. */
}

Available Tailwind width values: max-w-sm (384px), max-w-md (448px), max-w-lg (512px), max-w-xl (576px), max-w-2xl (672px), max-w-3xl (768px, default), max-w-4xl (896px), max-w-5xl (1024px).

Social Links

Configure social profile links in the socials array in astro-paper.config.ts. See Configuration → Socials for full details.

OG Images

Default (static) OG image

Place an image in public/ and set its filename in astro-paper.config.ts:

site: {
  ogImage: "default-og.jpg",
},

This image is used as a fallback for posts that don't specify their own ogImage.

Dynamic OG images

When features.dynamicOgImage is true (the default), AstroPaper automatically generates a unique OG image for each published post that lacks an ogImage in frontmatter. The image includes the post title, author name, and site title.

Dynamic images are generated at build time using Satori and Sharp.

To disable dynamic generation (e.g. for large sites with slow builds):

features: {
  dynamicOgImage: false,
},

When disabled, public/{site.ogImage} is required or the build will fail.

Per-post OG image

Add ogImage to a post's frontmatter:

ogImage: ../../assets/images/my-post-cover.jpg  # processed by Astro
# or
ogImage: "https://example.com/remote-image.png"  # remote URL

The recommended OG image size is 1200×640 px.