Migrating the Blog Site Again

Why Rewrite Again

If you’ve read the previous blog post about migrating the site, you’ll find that the last rewrite was just one Kun year actually over two years ago.

To be serious, there are many reasons. Let me list a few:

• The previous site used VuePress. While powerful, its complex system made configuration and customization costly. I couldn't be bothered to learn I couldn't be bothered to learn
• The template was good, but still not flexible enough. Encountering bugs meant waiting for the author to fix them Mr. Hope is an excellent and trustworthy author. Mr. Hope is an excellent and trustworthy author..
• The build time was still too long. Even though I often write Rust, I hoped for something faster, especially since my little blog doesn’t have much content.

Of course, there are also some personal reasons:

• After using Nuxt Content as the main framework for the lab’s static site, I gained a deeper understanding of the static site build process.
• I learned about some new features of Astro, especially its support for multiple frontend frameworks and fast builds, which seemed perfect for my customized site needs.
• Inspired by some excellent blogs (like Pak and Cruz Godar), I wanted to try a minimalist design style.
• I had the itch to code and wanted to tackle a big project to torment myself.

What’s Different

Thanks to the excellent AstroPaper template, getting started with development was relatively smooth. However, from the initial idea to rewrite to the final launch, it took nearly a month. This time was mainly spent polishing and optimizing details, along with various scattered changes. I won’t list them all, but let me briefly cover the main modifications.

Redesigning OG Images

The OG images included with the template weren’t bad, but not redesigning them felt like a lack of personal style.

In AstroPaper, OG images are divided into two templates: site and post. Both rely on Satori (悟り?) for generation, which can render React components into SVG images. These are then processed by resvg and converted to PNG format. This means you can fully leverage React to flexibly design the style and content of OG images.

Thanks to this, I redesigned the style and content of the OG images. Although the styles between the two aren’t perfectly unified yet, I’m quite satisfied with each individually.

• Site:
• Post:

Adding i18n Support

Since AstroPaper doesn’t have built-in i18n support, I needed to manually integrate the relevant functionality. After some research, I chose the most lightweight solution.

For UI Interface

Since the UI content is relatively fixed and doesn’t require much dynamic change, translation texts can be hardcoded directly. The implementation is as follows:

1. 1

   Create multilingual files under the src/i18n directory to store translation texts for different languages

   1
   export const ui = {
   2
     en: {
   5 collapsed lines
   3
       // Footer
   4
       "footer.copyright": "© {year} {author}",
   5
       "footer.license": "Licensed under {license}",
   6
   
   7
       // ...
   8
     },
   9
     zh: {
   5 collapsed lines
   10
       // Footer
   11
       "footer.copyright": "© {year} {author}",
   12
       "footer.license": "采用 {license}",
   13
   
   14
       // ...
   15
     },
   16
   } as const;

   And helper functions

   1
   import { SITE } from "@/config";
   2
   
   3
   import { ui } from "./ui";
   4
   
   5
   export const getLangFromUrl = (url: URL) => {
   6
     const [, lang] = url.pathname.split("/");
   7
     if (lang in ui) return lang as keyof typeof ui;
   8
     return SITE.defaultLocale;
   9
   };
   10
   
   11
   export const useTranslations = (lang: keyof typeof ui) => {
   12
     return (
   13
       key: keyof (typeof ui)[typeof SITE.defaultLocale],
   14
       replacements?: Record<string, string>
   15
     ) => {
   16
       const string = ui[lang][key] || ui[SITE.defaultLocale][key];
   17
       if (!replacements) return string;
   18
   
   19
       return Object.entries(replacements).reduce(
   20
         ([str, _], [key, value]) => [str.replace(`{${key}}`, value), _],
   21
         [string, ""]
   22
       )[0];
   23
     };
   24
   };

2. 2

   Integrate i18n functionality into various components to replace text content.

   1
   ---
   2
   import { getLangFromUrl, useTranslations } from "@/i18n/utils";
   10 collapsed lines
   3
   import Hr from "./Hr.astro";
   4
   import Socials from "./Socials.astro";
   5
   
   6
   const currentYear = new Date().getFullYear();
   7
   
   8
   export interface Props {
   9
     noMarginTop?: boolean;
   10
   }
   11
   
   12
   const { noMarginTop = false } = Astro.props;
   13
   const locale = getLangFromUrl(Astro.url);
   14
   const localeString = useTranslations(locale);
   15
   const license = "CC BY-NC-SA 4.0";
   16
   ---
   17
   
   7 collapsed lines
   18
   <footer class:list={["w-full", { "mt-auto": !noMarginTop }]}>
   19
     <Hr noPadding />
   20
     <div
   21
       class="flex flex-col justify-between items-center py-6 sm:flex-row-reverse sm:py-4"
   22
     >
   23
       <Socials centered />
   24
       <div class="flex flex-col items-center my-2 whitespace-nowrap sm:flex-row">
   25
         <span>
   26
           {
   27
             localeString("footer.copyright", {
   28
               year: currentYear.toString(),
   29
               author: localeString("site.author"),
   30
             })
   31
           }
   32
         </span>
   33
         <span class="hidden sm:inline">&nbsp;|&nbsp;</span>
   34
         <span>
   35
           {localeString("footer.license", { license })}
   36
         </span>
   3 collapsed lines
   37
       </div>
   38
     </div>
   39
   </footer>

For Blog Post Content

In the previous site, we needed to place posts of different languages into separate folders. While this structure was clearer, I found it difficult to quickly see which posts lacked translations. Also, some methods based on setting the language in frontmatter required manual maintenance and still had filename conflicts.

After some research, I decided to use astro-loader-i18n. Its biggest advantage is that it can automatically load posts in the corresponding language based on filenames, simplifying the implementation of multilingual support.

1. 1

   Change the method for loading post content

   1
   import { defineCollection, z } from "astro:content";
   2
   import { glob } from 'astro/loaders';
   3
   import { extendI18nLoaderSchema, i18nLoader } from "astro-loader-i18n";
   4
   import { SITE } from "@/config";
   5
   
   6
   export const BLOG_PATH = "content/posts";
   7
   export const ABOUT_PATH = "content/about";
   8
   
   9
   const blog = defineCollection({
   10
     loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: `./${BLOG_PATH}` }),
   11
     loader: i18nLoader({ pattern: "**/[^_]*.{md,mdx}", base: `./${BLOG_PATH}` }),
   12
     schema: ({ image }) =>
   13
       extendI18nLoaderSchema(
   14
         z.object({
   12 collapsed lines
   15
           title: z.string(),
   16
           author: z.string().default(SITE.author),
   17
           pubDatetime: z.date(),
   18
           modDatetime: z.date().optional().nullable(),
   19
           featured: z.boolean().optional(),
   20
           draft: z.boolean().optional(),
   21
           tags: z.array(z.string()).default(["others"]),
   22
           ogImage: image().or(z.string()).optional(),
   23
           description: z.string(),
   24
           canonicalURL: z.string().optional(),
   25
           hideEditPost: z.boolean().optional(),
   26
           timezone: z.string().optional(),
   27
         })
   28
       ),
   29
   });
   12 collapsed lines
   30
   
   31
   const about = defineCollection({
   32
     loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: `./${ABOUT_PATH}` }),
   33
     loader: i18nLoader({ pattern: "**/[^_]*.{md,mdx}", base: `./${ABOUT_PATH}` }),
   34
     schema: ({ image }) =>
   35
       extendI18nLoaderSchema(
   36
         z.object({
   37
           title: z.string(),
   38
           ogImage: image().or(z.string()).optional(),
   39
         })
   40
       ),
   41
   });
   42
   
   43
   export const collections = { blog, about };

2. 2

   Rename existing post files

   After using i18nLoader, we need to rename existing post files to follow the i18n naming convention. Specifically, we need to add the language identifier to the filename. For example, rename the Chinese hello.md to hello.zh.md, and the corresponding English file to hello.en.md. The extra suffix does not appear in the link path.

   Note that the suffix used must match the site’s language settings. If set to zh-CN, then name the file hello.zh-CN.md.

Site Configuration

In addition to the above, we need to add i18n-related settings to the site configuration to ensure multilingual functionality works properly. Specifically, we need to make the following modifications:

1. 1

   Add language configuration

   1
   export const SITE = {
   2
     // ...
   3
     locales: {
   4
       en: { label: "English", codes: ["en", "en-US"] },
   5
       zh: { label: "中文", codes: ["zh", "zh-CN"] },
   6
     }, // supported locales
   7
     defaultLocale: "en", // default locale
   8
   } as const;

2. 2

   Modify Astro i18n configuration

   1
   // ...
   2
   import { SITE } from "./src/config";
   3
   
   4
   // https://astro.build/config
   5
   export default defineConfig({
   6
     site: SITE.website,
   7
     i18n: {
   8
       locales: Object.entries(SITE.locales).map(([lang, { codes }]) => {
   9
         return {
   10
           path: lang,
   11
           codes: [...codes],
   12
         };
   13
       }),
   14
       defaultLocale: SITE.defaultLocale,
   15
       routing: {
   16
         prefixDefaultLocale: true,
   17
         redirectToDefaultLocale: true,
   18
         fallbackType: "rewrite",
   19
       },
   20
     },
   21
     // ...
   22
   });

3. 3

   Insert [locale] into the src/pages path

   For example, src/pages/index.astro needs to be changed to src/pages/[locale]/index.astro. Ensure all pages follow this structure.

   Also, create an empty src/pages/index.astro file for redirecting when accessing the root path.

   Additionally, the 404 page does not need to be placed under the [locale] directory.

4. 4

   Update all page routes

   We need to create corresponding routes for each page under src/pages/[locale]/, telling Astro which pages to render.

   Take src/pages/[locale]/about.astro as an example:

   1
   ---
   2
   import { type CollectionEntry, getCollection, render } from "astro:content";
   3
   import type { GetStaticPaths } from "astro";
   4
   import Breadcrumb from "@/components/Breadcrumb.astro";
   5
   import Footer from "@/components/Footer.astro";
   6
   import Header from "@/components/Header.astro";
   7
   import { SITE } from "@/config";
   8
   import { useTranslations } from "@/i18n/utils";
   9
   import Layout from "@/layouts/Layout.astro";
   10
   
   11
   export interface Props {
   12
     post: CollectionEntry<"about">;
   13
   }
   14
   
   15
   export const getStaticPaths = (async () => {
   16
     return Object.keys(SITE.locales).map((lang) => ({
   17
       params: { locale: lang as keyof typeof SITE.locales },
   18
     }));
   19
   }) satisfies GetStaticPaths;
   20
   
   21
   const { locale } = Astro.params;
   22
   
   23
   const localeString = useTranslations(locale);
   24
   
   25
   const about = await getCollection(
   26
     "about",
   27
     ({ data }) => data.locale === locale
   28
   );
   29
   if (!about || about.length === 0) {
   30
     return Astro.redirect(getRelativeLocaleUrl(locale, "/404"));
   31
   }
   32
   const aboutPage = about[0];
   33
   const { Content } = await render(aboutPage);
   34
   ---
   35
   
   13 collapsed lines
   36
   <Layout title={`${aboutPage?.data.title} | ${localeString("site.title")}`}>
   37
     <Header />
   38
     <Breadcrumb />
   39
     <main id="main-content">
   40
       <section id="about" class="mb-28 app-prose max-w-app prose-img:border-0">
   41
         <h1 class="text-2xl tracking-wider sm:text-3xl">
   42
           {aboutPage.data.title}
   43
         </h1>
   44
         <Content />
   45
       </section>
   46
     </main>
   47
     <Footer />
   48
   </Layout>

   GetStaticPaths is used to generate paths for static pages. You can do more customization within the function, such as filtering the visible post list based on the current path’s language.

   All parameter combinations that appear in GetStaticPaths will become valid paths, so you can force Astro to generate pages for specific languages.

Added/Replaced Components

Expressive Code

Expressive Code is a tool for code highlighting, supporting multiple programming languages and themes with rich features. As seen in the code blocks above, it supports content markers, block highlighting, line numbers, folding, code copying, and more.

MDX

MDX is a format that combines Markdown and JSX, allowing you to use components within Markdown. If you want to use custom components in Markdown, you can use the MDX format. The Astro framework provides official MDX support, so it only requires adding the relevant dependencies and simple configuration.

Table of Contents

AstroPaper uses the remark-toc plugin to automatically generate a table of contents, but it requires manually inserting a specific second-level heading within the post. Not only is it difficult to adjust the style, but it’s also inconvenient to support multiple languages.

Fortunately, the render function from Astro content returns a list of all headings, including their level, link, and text. Therefore, we can manually create a table of contents directly in the post template. This eliminates the need for manual heading insertion and easily supports multiple languages.

Existing Solutions

AstroPaper implements many features from scratch, including pagefind for page search, icon components, theme switching, and post-processing compression. These features actually have existing solutions available, such as:

• Astro Pagefind
• Astro Icon
• Astro Theme Toggle
• Playform Compress

I prefer to use these existing Astro integration packages directly, as they greatly simplify development and reduce maintenance workload.

Summary

After all this tinkering, what you see now is a highly customized version of AstroPaper. Some features are still missing, but that can be left as a weekend project for my future self. Previously written posts will also be gradually migrated and adapted.

Finally, the classic question: what’s the cost? Clearly, compared to the previous version, although the build time has seen real improvement, the current Astro-based site is a system several times more complex. Compatibility with multiple frameworks means more choices, and it means there might not be a single, universal optimal solution. Lastly, although Astro’s ecosystem is also developing, writing blog sites To be blunt, writing content-driven static sites To be blunt, writing content-driven static sites is a relatively niche need after all. Therefore, future requirements will likely still need to be implemented ourselves.

But I had fun coding, so who cares about the rest? Thank you for taking the time to read my ramblings.