Advanced Configuration

This post is an advanced guide on customizing the Astro AntfuStyle Theme. If you have not yet configured the src/config.ts file, it is recommended to first review Basic Configuration.

Customizing Logo#

Designing Your Own Logo

Generate a text-based logo using Google Font to Svg Path or create one with AI tools. If proficient, you could use Adobe Illustrator for more professional designs.

Once your logo’s SVG file is ready, you’ll need to update the LogoButton component and the template for the autogenerated OG Images to include your new logo.

Modifying the LogoButton Component

Open src/components/widgets/LogoButton.astro. This file contains both an ICON SVG and a TEXT SVG, which are currently commented. You can uncomment and switch between them to see different effects.

Replace the existing SVG with your logo’s SVG in this component. Ensure to keep the aria-hidden="true" attribute within the <svg> tag for accessibility purposes.

If your logo includes black and white, you may need to adjust for theme changes between light and dark modes:

// Method 1: Specify colors for dark mode
<path class="dark:fill-[#fff] dark:stroke-[#000]" fill="#fff" stroke="#000" ...></path>

// Method 2: Use color inversion for dark mode
// (not suitable for non-black and white colors, check before applying!)
<path class="dark:filter-invert-100" ...></path>

Further customize your logo using CSS in the <style> block or remove it and apply UnoCSS utilities directly—for opacity, scaling, or animations (see Animated SVG Logo).

Modifying the Autogenerated OG Images Template

Open the src/utils/og-image/template/markup.ts file and replace the SVG section entirely.

You may need to adjust the SVG element’s width, height, and viewBox attributes to fit properly. It’s recommended to paste the code below into the Satori: OG Image Playground under the Tailwind (experimental) tab for testing.

<div tw="flex items-center justify-start w-full px-18" style="gap: 20px">
  <div tw="self-start flex justify-center items-center">
    <!-- Replace Your SVG Logo Here -->
  </div>
  <div tw="flex flex-col" style="gap: 10px">
    <div tw="text-[#858585] text-2.1rem">${authorOrBrand}</div>
    <div tw="text-white text-3.1rem leading-relaxed mr-18">${title}</div>
  </div>
</div>

Replacing the Website Icon#

Once you’ve customized the logo and have the SVG file, it’s time to generate the necessary icons to replace the website’s favicon. You’ll need to generate the following Ultimate Favicon Setup:

• favicon.ico: For legacy browsers.
• favicon.svg: A single SVG icon with light/dark modes for modern browsers.
• apple-touch-icon.png: A 180×180 PNG for Apple devices.
• icon-192.png, icon-512.png, icon-mask.png: Icons for the web app manifest, including a 192×192 icon for home screens, a 512×512 maskable icon for different Android launchers, and a 512×512 icon for splash screens when the PWA (Progressive Web App) is loading.

First, open the favicon.svg file in a text editor. Add <style> to adjust the fill color based on the theme:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 500">
  <style>
    .path { fill: #17191e }
    @media (prefers-color-scheme: dark) {
      .path { fill: #f0f0f0 }
    }
  </style>
  <path d="…"></path>
</svg>

<!-- Icon -->
<link rel="icon" type="image/svg+xml" href={withBasePath('/favicon-light.svg')} media="(prefers-color-scheme: light)">
<link rel="icon" type="image/svg+xml" href={withBasePath('/favicon-dark.svg')}  media="(prefers-color-scheme: dark)">
<link rel="icon" type="image/svg+xml" href={withBasePath('/favicon.svg')} />
<link rel="icon" sizes="32x32" href={withBasePath('/favicon.ico')} />
<link rel="apple-touch-icon" href={withBasePath('/apple-touch-icon.png')} />

Next, use the steps in How to Favicon in 2024 or Real Favicon Generator to generate the icons. Rename the files as mentioned above and copy them to the public directory to replace the existing ones.

Lastly, update src/pages/app.webmanifest.js with the following:

import { withBasePath } from '~/utils/path'

export async function GET() {
  // https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest
  const manifest = {
    id: withBasePath('/'),
    name: 'Astro AntfuStyle Theme',
    short_name: 'AntfuStyle',
    description:
      'A customizable, feature-rich Astro theme for blog and portfolio',
    icons: [
      {
        src: withBasePath('icon-192.png'),
        type: 'image/png',
        sizes: '192x192',
      },
      {
        src: withBasePath('icon-512.png'),
        type: 'image/png',
        sizes: '512x512',
      },
      {
        src: withBasePath('icon-mask.png'),
        type: 'image/png',
        sizes: '512x512',
        purpose: 'maskable',
      },
    ],
    scope: withBasePath('/'),
    start_url: withBasePath('/'),
    display: 'standalone',
    theme_color: '#fff',
    background_color: '#fff',
  }

  return new Response(JSON.stringify(manifest), {
    headers: {
      'Content-Type': 'application/manifest+json; charset=utf-8',
    },
  })
}

If you don’t need PWA support, you can delete app.webmanifest.js, icon-192.png, icon-512.png, and icon-mask.png.

Customizing Website Styles#

While the theme offers some quick UI configuration options in the src/config.ts, these are limited. If you’re familiar with CSS, you can fully customize the website styles, but it’s recommended to follow the methods outlined below.

Styling approaches

• UnoCSS utility classes using the Wind3 preset (ua compact preset compatible with Tailwind CSS 3 and Windi CSS)
• Custom CSS utility classes (in unocss.config.ts under rules and shortcuts)
• Native CSS (in CSS files and component <style> tags)

Where styles are defined

• styles/main.css: Global styles.
• styles/prose.css: Prose-related styles.
• styles/markdown.css: Plugin- and integration-related styles.
• src/components/: Component-specific styles.

// Original styles, do not modify directly!
.prose {
  max-width: 65ch;
  font-size: 1rem;
  line-height: 1.75;
}

// Create a new `.css` file in the `src/styles` directory
// Use the same selector with updated properties
.prose {
  max-width: 70ch;
}

import '~/styles/main.css'
import '~/styles/prose.css'
import '~/styles/markdown.css'

// Import your custom file after the others
import '~/styles/your.css'

...

<div ...
>
  {
    !wide ? (
      ...
    ) : (
      <span
        // Add a custom class
        class={`custom-class absolute top-0 op-35 dark:op-20 ...`}
      >
        {text}
      </span>
    )
  }
</div>

// Create a new `.css` file in the `src/styles` directory
// Write styles using the class selector
.custom-class {
  font-family: 'Gill Sans', 'Gill Sans MT', Calibri, 'Trebuchet MS', sans-serif;
}

Customizing Fonts#

Before changing font settings, read Font Setup & Usage for the current font families, where they are used, and how they are loaded.

The theme uses Astro Fonts as the source of truth. A complete font configuration has three parts:

• Register the font in astro.config.ts with name, cssVariable, provider options, and fallbacks.
• Render that CSS variable with <Font /> in src/components/base/Head.astro.
• Use the variable directly in CSS, or map it to a UnoCSS utility in unocss.config.ts.

In the examples below, replace customFontName with the real font family name supported by the provider you choose.

To change the font behind an existing variable, keep cssVariable unchanged and update that entry in astro.config.ts. For example, this replaces the font used by --font-sans, so existing font-sans utilities and var(--font-sans) styles keep working:

import { defineConfig, fontProviders } from 'astro/config'

const sansFallbacks = [
  'ui-sans-serif',
  ...
]

export default defineConfig({
  ...
  fonts: [
    {
      provider: fontProviders.fontsource(),
      name: 'Inter',
      name: 'customFontName',
      cssVariable: '--font-sans',
      weights: ['100 900'],
      styles: ['normal'],
      subsets: ['latin'],
      formats: ['woff2'],
      fallbacks: sansFallbacks,
    },
  ],
  ...
})

To add a new CSS font variable, add another entry instead:

export default defineConfig({
  ...
  fonts: [
    ...
    {
      provider: fontProviders.fontsource(),
      name: 'customFontName',
      cssVariable: '--font-custom',
      weights: [400],
      styles: ['normal'],
      subsets: ['latin'],
      formats: ['woff2'],
      fallbacks: customFallbacks,
    },
  ],
})

Then render the new variable in the shared head component:

<Font cssVariable="--font-sans" preload />
<Font cssVariable="--font-mono" />
<Font cssVariable="--font-condensed" />
<Font cssVariable="--font-custom" />

Only add preload to fonts needed for the first visible content; unnecessary preloads can slow down other critical resources.

After that, use it directly in CSS:

.custom-heading {
  font-family: var(--font-custom);
}

Or map it to a UnoCSS utility:

export default defineConfig({
  ...
  extendTheme: (theme) => {
    return {
      ...theme,
      fontFamily: {
        ...theme.fontFamily,
        sans: 'var(--font-sans)',
        mono: 'var(--font-mono)',
        condensed: 'var(--font-condensed)',
        custom: 'var(--font-custom)',
      },
    }
  },
})

<h2 class="font-custom">Custom font heading</h2>

Customizing Footer#

You can directly modify the src/components/base/Footer.astro file. For instance, if you want to apply the CC BY-NC-SA 4.0 license, you can update the code as follows:

8 collapsed lines
---
import Link from '~/components/base/Link.astro'
import { SITE } from '~/config'

const currentYear = new Date().getFullYear()
const copyrightText = `© ${currentYear} ${SITE.author}`
---

<footer class="slide-enter animate-delay-1600! px-7 mt-auto mb-8">
  <div class="prose mx-auto op-50">
    <div class="flex lt-sm:flex-col items-center text-sm whitespace-nowrap">
      <span>
        <Link
          class="op-100! color-[--fg]!"
          href="https://creativecommons.org/licenses/by-nc-sa/4.0/"
          title="CC BY-NC-SA 4.0"
          external={true}
        >
          CC BY-NC-SA 4.0
        </Link>
        {' '}
        {copyrightText}
12 collapsed lines
      </span>
      <span class="lt-sm:hidden">&nbsp;|&nbsp;</span>
      <span>
        Powered by
        {' '}
        <Link
          class="op-100! color-[--fg]!"
          href="https://github.com/lin-stephanie/astro-antfustyle-theme"
          external={true}
        >
          Astro AntfuStyle Theme
        </Link>
      </span>
    </div>
  </div>
</footer>

Of course, it would be greatly appreciated if you could also keep the Powered by Astro AntfuStyle Theme part to help more people discover it. 😊

Configure Giscus Comments#

This theme integrates the Giscus comments. By default, users can comment on posts under blog/ after logging in with GitHub.

Follow the setup guide to make your GitHub repo public, install the Giscus app, enable Discussions, and obtain the config needed for the FEATURES.giscus option in src/config.ts. This is used in Giscus.astro. You can also tweak it per the Giscus docs.

For styling, the theme serves custom CSS from /giscus/light.css and /giscus/dark.css, based on modified styles of the ‘noborder_light’ and ‘noborder_dark’ themes. These routes are generated by one dynamic Astro CSS endpoint (src/pages/giscus/[theme].css.ts) that injects the self-hosted normal Inter @font-face rule generated by Astro Fonts.

Because Giscus runs inside an iframe, it cannot inherit the parent page’s CSS variables or @font-face rules. To allow https://giscus.app to load the theme CSS and font files, the local dev server and the production host both need to allow that cross-origin request:

• Development: The theme already configures two settings in astro.config.ts: security.allowedDomains lets Astro’s dev request filter accept https://giscus.app, and vite.server.headers adds the CORS response header that lets the Giscus iframe load /giscus/*.css and /_astro/fonts/* locally:

export default defineConfig({
  ...
  security: {
    allowedDomains: [
      {
        hostname: 'giscus.app',
        protocol: 'https',
      },
    ],
  },
  vite: {
    server: {
      headers: {
        'Access-Control-Allow-Origin': 'https://giscus.app',
      },
    },
  },
})

• Production: Ensure your host serves both the custom CSS and Astro font files with proper CORS headers. If you’re on Vercel, the theme’s vercel.json already includes this setup. But if you use another platform, you’ll need to manually configure it. For example, on Netlify, create a _headers file:

/giscus/*
  Access-Control-Allow-Origin: https://giscus.app
/_astro/fonts/*
  Access-Control-Allow-Origin: https://giscus.app

If you prefer to use Giscus’s built-in themes directly, update Giscus.astro, ThemeSwitch.astro, and astro.config.ts as shown below, and remove the unused [theme].css.ts endpoints, src/styles/giscus/, and related CORS config.

<script>
  import { FEATURES } from '~/config'

  const giscusThemeLight = withClientBasePath('giscus/light.css')
  const giscusThemeDark = withClientBasePath('giscus/dark.css')
  const giscusThemeLight = 'noborder_light'
  const giscusThemeDark = 'noborder_dark'
  ...
</script>

<script>
  const changeGiscusTheme = (isDark: boolean) => {
    const newTheme = isDark
      ? withClientBasePath('giscus/dark.css')
      : withClientBasePath('giscus/light.css')
      ? 'noborder_dark'
      : 'noborder_light'
    ...
  }
</script>

Final Cleanup#

Finally, you may want to:

• Remove the .github directory (mainly for workflows and templates, but the scheduled-vercel-deploy.yml file may be useful for Customizing GitHub Activity Pages).
• Clean up the src/content/, src/assets/, and other directories.
• Review .vscode/settings.json for adjustments.
• Rewrite README.md.
• Delete anything you don’t need and know is safe.

Wrapping Up#

This is a general overview of what you can customize in the project. If you’re proficient with code, there’s even more you can personalize!

Next, check out Authoring Content to learn how to tailor each page to your liking.

If you encounter any issues, find errors, or see opportunities for improvement, feel free to join the discussion or submit an issue or pull request. Your feedback is highly appreciated! ❤️