FAQs and Known Issues

FAQs#

Lighthouse Scores#

The accessibility score is not perfect due to “Background and foreground colors do not have a sufficient contrast ratio”, which is a result of the theme’s styling. If you don’t mind this, the theme performs very well in Lighthouse. A high-contrast version is planned.

You can also check the live demo’s performance on PageSpeed Insights: https://pagespeed.web.dev/

About SEO and Accessibility#

The SEO functionality of the theme is enhanced by integrating the official @astrojs/sitemap and the third-party astro-robots-txt, which automatically generate sitemap.xml and robots.txt files, respectively. Additionally, the theme can generate and configure Google JSON-LD Structured Data in the page headers for different types of content, helping search engines better understand and display your site’s information accurately.

As for accessibility, the theme is tested using the Sa11y tool, making it easy for you to check your content --- a simple yet effective assistant.

Revert from pnpm to npm or yarn#

• Delete the node_modules directory and pnpm_lock.yaml from the project root.
• Replace pnpm with npm/yarn in package.json (this step isn’t needed for this project).
• Run npm install or yarn install.

Path Aliases#

Path alias configuration:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

Aliases work in files processed by Vite and TypeScript under src/, but not in files like plugins/remark-generate-og-image.ts or unocss.config.ts unless you use tsconfig-paths.

Example:

import { formatDate } from '~/utils/helpers';

function MyComponent() {
  return <div>{formatDate(new Date())}</div>;
}

export default MyComponent;

Icon Usage#

This theme has @unocss/preset-icons and @iconify-json pre-installed and configured, allowing the use of icons wherever needed. According to UnoCSS specs, icons must follow the format i-<collection>-<icon> or i-<collection>:<icon>. Examples include:

• "i-ri:twitter-x-fill"
• "i-ri-twitter-x-fill"
• "i-mdi:github"
• "i-mdi-github"

You can explore more available icon sets on icon-sets.iconify.design. Once you’ve found the desired icon, select it, then copy the UnoCSS icon name from the “Icon” dropdown.

For more details on usage, please refer to the UnoCSS - Icons preset.

Post Date Format#

The default date format is MMM D, YYYY, handled by formatDate in src/utils/index.ts. Adjust as needed using day.js format list.

Page Backgrounds#

Backgrounds, except Rose.astro, use custom elements with animations that stop to prevent memory leaks. There’s no performance issue, but report any if you encounter any performance problems.

Currently, backgrounds are not supported for pages at the /blog/[...slug] path. If you wish to add one, you can modify the src/pages/blog/[...slug].astro file like this:

...
<BaseLayout
  title={frontmatter.title}
  description={frontmatter.description}
  ogImage={frontmatter.ogImage}
  {pubDate}
  {lastModDate}
  bgType='plum'  // 'dot', 'rose', 'particle'
>
  ...
</BaseLayout>

Additionally, you can directly modify the constants in each background component (/src/components/backgrounds/) to customize the animation effects.

Search Functionality#

The theme utilizes Pagefind to enable search functionality.

You can control the search index dynamically in src/layouts/StandardLayout.astro. By default, only blog posts are searchable (set in src/pages/blog/[...slug].astro with isSearchable={true}). You can adjust this by passing the isSearchable prop to the StandardLayout component, or for more custom search options, check out Configuring what content is indexed.

Search for data-pagefind- in the editor to see the current setup.

Image Zoom#

The theme uses medium-zoom to zoom images that match the .prose img:not(.no-zoom) selector. To disable zoom for a specific image, add the no-zoom class.

Configuration can be done in src/layouts/BaseLayout.astro.

RSS Subscription Scope#

Currently, the theme’s RSS configuration (see src/pages/rss.xml.js) only allows visitors to subscribe to posts under src/content/blog/.

If you want to further customize which content on the site can be subscribed to, refer to the theme’s integrated @astrojs/rss documentation and Astro’s official guide.

If the official integration doesn’t meet your needs, you may consider using jpmonette/feed. Additionally, community-provided RSS Recipes are also worth checking out.

Language-specific Build#

Localization support will be added soon. For now, manual changes are required.

Known Issues#

Here are some unresolved issues found during theme development. If you have a solution, feel free to submit a PR --- much appreciated!

1. No hints or error warnings when passing props in MDX components.

2. Even if bgType is not set to 'dot' or 'particle', the JS for these backgrounds and p5.js is still bundled in the Astro build. However, it’s not loaded by the browser unless used, so it generally doesn’t affect performance. (Attempts to load p5.js from a CDN instead of importing it as a module caused errors: “p5 is not defined”).

3. Automatically generated OG Images don’t support emojis, and titles may occasionally overflow the image boundary, making them partially invisible, despite margins and padding being set in the template.

Thank you for taking the time to explore and use the Astro AntfuStyle Theme. Let’s keep pushing forward and making great things happen --- your input is always welcome! 🙌