Astro-Yi Theme Configuration and Writing Tips

Introduction#

This is an open-source blog theme called Astro-Yi that I developed. If you like it, please give it a star. Thank you for your attention and welcome to contribute!

Configuring Astro-Yi#

Essential Configuration (Required)#

The configuration file for the Astro project is located at /astro.config.mjs, and there are some essential configurations:

export default defineConfig({
    site: "https://cirry.cn", // Please modify it to your own website address here
})

Blog Information Configuration#

In the configuration file of the Astro-Yi theme src/consts.ts, there are some important configurations:

// ...
export const site = {
  title: "Cirry's Blog",  // required
  favicon: '/favicon.svg', // required
  author: "Cirry", // required
  avatar: '/avatar.png', // required
  description: '', 
  motto: '', 
  url: 'https://cirry.cn', // required
  recentBlogSize: 5, // required
  archivePageSize: 25, // required
  postPageSize: 10, // required
  indexPageSize: 10, // required
  beian: '', 
}
// ...

favicon is the location of the website icon. The file is located at /public/favicon.svg. Please replace it with your own website icon.

avatar is the location of the website avatar. The file is located at /public/avatar.png. Please replace it with your own website avatar.

Comment System Configuration#

/**
 * enable: Whether to enable the comment function. Set to true to enable and false to disable.
 * serverUrl: The server address of Waline.
 * pageSize: The desired number of comments shown in each page.
 * wordLimit: The word limit for comments. Set to a single number for maximum word limit. Set to 0 or leave it unset for unlimited.
 * requiredMeta: The required information for comments, which can be nick, mail, or link.
 * count: The number of recent comments displayed in the sidebar.
 * pageview: Enable article pageviews statistics.
 * reaction: Enable article reaction interaction.
 * whiteList: Article reaction whitelist.
 */
export const comment = {
    enable: true, // Required, set to enable the comment system
    serverUrl: "https://xxx.xx.app", // Required, modify it to your own Waline server address
    pageSize: 20, //
    wordLimit: '', 
    requiredMeta: ["nick", "mail"], // Required
    count: 5,
    pageview: true,
    reaction: false, 
    whiteList: ['/message/', '/friends/', '/donate/'],
}

reaction does not have to be set to true/false only. You can also pass an array of image addresses to achieve custom reactions. For more details, please refer to Article Reaction.

/**
 * Sponsor System
 * enable: Set to true to enable, false to disable.
 * tip: Sponsorship prompt.
 * wechatQRCode: WeChat QR code address. The image should be placed in the public directory.
 * alipayQRCode: Alipay QR code address. The image should be placed in the public directory.
 * paypalUrl: Paypal QR code address.
 * @type {{paypalUrl: string, alipayQRCode: string, enable: boolean, wechatQRCode: string, tip: string}}
 */
export const donate = {
  enable: true,
  tip: "Thank you for the coffee☕",
  wechatQRCode: "/WeChatQR.png",
  alipayQRCode: "/AliPayQR.png", 
  paypalUrl: "https://paypal.me/cirry0?country.x=C2&locale.x=zh_XC",
}

Friendly Links Configuration#

/**
 * Friendly Links
 * name: Blog name
 * url: Blog URL
 * avatar: Blog avatar
 * descript: Blog description
 * @type {[{name: string, description: string, avatar: string, url: string}]}
 */
export const friendlyLinks = [
    {
      name: "Cirry's Blog",
      url: 'https://cirry.cn',
      avatar: "https://cirry.cn/avatar.png",
      description: 'Daily life of front-end development'
    },
]

Recommended Configuration#

Astro-Yi provides many configurations to enrich our page functionality. Here are my suggestions:

It is recommended to enable the Waline comment system. If you don't know how to install the Waline system, you can refer to the Waline official website or Install Waline Comment Function.
If you are a user from mainland China, it is recommended to add the record number.
Personal links to let more people know about you and your website.

Writing Tips#

Markdown Document Specification#

If you use Astro as your blog, you will need to use Markdown, and you can refer to the basic writing and formatting syntax on GitHub for the basic specifications Basic Writing and Formatting Syntax.

Automatically Generate Frontmatter in Vscode#

When writing each article, if you need to manually copy information and fill in the date, it can be a complicated task. Therefore, I provide a method to automatically generate frontmatter when writing blogs in Vscode. You can refer to this Vscode Add Markdown-Frontmatter Code Snippet for more details.

Writing Blog Pages#

Under the Yi theme, you only need to create an md document in src/content/blog to start writing your blog.

According to the Markdown document standard of Astro, each document should have its own frontmatter information, and the frontmatter is marked with --- at the beginning and end of the md document to indicate the frontmatter. This brings us a lot of convenience:

For example, if we want to add tags and categories to a document or stick certain documents, we can add some attributes to the frontmatter, such as tags, sticky, and so on.
For example, to avoid using Chinese as the blog path and file name, we can set the title of the md document to the Chinese title and use English as the file name with - as the word connector.

In Astro-Yi, you only need to set the document title title and creation date date tags, and the following is the simplest frontmatter setting for an md document:

---
title: 菩萨蛮·花明月暗笼轻雾 // File name
date: 2024-03-05
---

If you feel that these document attributes are not enough, Yi also provides more attributes for you to use. Here is an example of a complete attribute configuration:

---
title: 菩萨蛮·花明月暗笼轻雾 // File name
description: 此词当是李煜描写自己与小周后幽会之情景，创作于北宋乾德二年（公元964年）前后。 // Document description
date: "2023-01-25T10:23:31.210Z" // Publication date
tags:   // Document tags support arrays and strings
  - 诗词
category: 诗词  // Document categories support arrays and strings
sticky: 100  // Document sticky weight, the larger the number, the higher the weight
slug: poem/ci // Permanent link of the document
mathjax: false // Whether to enable formula display
draft: false    // Whether it is a draft
toc: true   // Whether the article needs a table of contents
donate: false   // Whether to enable sponsorship function
comment: false  // Whether to enable comment function
---

Except for title and date, the rest of the attributes are optional or have default values. You can modify their optionality or default values in src/content/config.js.

Writing Dynamic Pages#

Under the Yi theme, you only need to create an md document in src/content/feed to start writing your dynamic content.

A dynamic page should be similar to a social media feed, where you can temporarily express or comment on something.

Therefore, it does not have many frontmatter restrictions. You don't even need to set a title for it (of course, this kind of content doesn't need a title), but we know that the most important attribute for publishing a message is the publication time, so you need to set date.

So the basic frontmatter setting for an md document of a dynamic page should be like this:

---
date: 2023-01-25 10:23:31
---

Loading Local Images#

Put your image files in the /public/images directory. If there is no images folder, create one. Then, use the absolute path /images/xx.png to reference the image in Markdown.

For example, if you have an image named xxx.png and move it to the /public/images/2024/ folder, you only need to use the following format in the md file to use it normally: ![](/images/2024/xxx.png).

Modifying Icons#

All icons in the blog use the open-source icon library remixicon, and you can replace them with your favorite icons.