Beginner's Guide to Blog Usage

May 10, 2025

Preparation

Before using this personal blog system, there are some preparations you need to make. Below are the files you need to modify, which I have highlighted, with relevant notes added:

astro.config.mjs
Directorysrc/
- Directorycomponents/
  - Footer.astro
- Directorycontent/
  - Directorydocs/
    index.mdx

1
export default defineConfig({
2
  site: 'https://canjie.org',
3
//Blog system URL, check whether it is an external link by modifying site: 'https://your-domain',
4
...
5
starlightGiscus({
6
          repo: 'tgimgcdn/blog',
7
//GitHub username/repo, required for comment system, modify it to your GitHub username/repo
8
          repoId: 'R_kgDOOjxhOw',
9
//GitHub repository ID, modify it to your GitHub repository ID
10
          category: 'General',
11
          categoryId: 'DIC_kwDOOjxhO84Cp6EN',
12
//Discussion category ID, modify it to your discussion category ID
13
          mapping: 'pathname',
14
          strict: '0',
15
          reactionsEnabled: '1',
16
          emitMetadata: '0',
17
          inputPosition: 'bottom',
18
          theme: 'preferred_color_scheme',
19
          lang: 'zh-CN',
20
          loading: 'lazy',
21
          crossorigin: 'anonymous'
22
        }),
23
...
24
authors: {
25
            cmssky: {
26
              name: 'cmssky',
27
//Author name, modify it to your author name
28
              picture: 'https://img20.360buyimg.com/openfeedback/jfs/t1/297564/4/2943/9987/6816f2f6Ff7a97a86/37decef475f8f719.jpg',
29
//Author picture, modify it to your author picture
30
              url: 'https://canjie.org',
31
//Author website, modify it to your website
32
            },
33
...
34
title: '参界说',
35
//Website title, modify it to your website title
36
      components: {

1
<span class="copyright">©2023 - 2025 By 参界说</span>
2
//Footer title, modify it to your footer title
3
...
4
function updateRunDays() {
5
        const startDate = new Date('2023-01-01T00:00:00+08:00'); // Use Beijing time
6
//Displays the website runtime in the footer, modify it to your website's actual start date
7
        const now = getBeijingTime();

1
---
2
title: 分享技术，记录生活!
3
//Change the text displayed on the homepage to whatever you want to show.
4
description: 欢迎来到我的博客
5
template: splash

For modifying the comment system parameters, refer to Blog Usage - Set Up Comment System Writing Blog Posts Blog posts are located in the blog directory. You can upload your mdx or md files to this directory.

If you need to create categories, create new folders under the blog directory. For example, I created a “tech” folder under the blog directory and placed all technology-related articles in it.

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryblog/
    Directorytech/
    …

Friendly Reminder

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryblog/
    Directorytech/
    …
    Directorycategories/
    index.mdx
    tech.mdx

The content of tech.mdx is as follows. If you create other categories, modify the content accordingly, and I’ve marked the necessary changes.

1
---
2
title: 技术文章
3
description: 查看所有技术相关文章
4
template: splash
5
---
6

7
import CategoryList from '../../../components/CategoryList.astro';
8

9
<CategoryList category="tech" />

Once you have completed the above tasks, congratulations! You can now start writing your first blog post. For example, if you created a “life” category, you can create an mdx file in that folder, such as My-first-blog.mdx (you can also name it My first blog.mdx) as your first blog post.

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryblog/
    Directorylife/
    My-first-blog.mdx
    Directorycategories/
    index.mdx
    life.mdx

The content of My-first-blog.mdx is as follows. I’ve highlighted the required fields and added relevant notes:

1
---
2
title: "My First Blog"
3
//Required field, blog title
4
excerpt: "This is my first blog, welcome!"
5
//Optional field, blog excerpt, introducing the blog's general content, supports basic Markdown formatting, delete if not needed
6
giscus: true
7
//Optional field, enable comments, by default all pages have comments disabled, retain if you want to enable comments
8
date: 2025-05-09
9
//Required field, blog publish date
10
lastUpdated: 2025-05-10
11
//Optional field, blog update date, delete if no update date
12
category: life
13
//Optional field, blog category, if the blog is in /src/content/docs/blog, the blog will automatically be categorized under "life". If it is in /src/content/docs/blog/life, it will automatically be categorized under "life"
14
thumbnail: https://cdn.canjie.org/AgAD4BgAAmga2VQ.webp
15
//Optional field, thumbnail, can be a URL or image address, place the file in the /public folder if using an image, for example, /public/images/My first blog.jpg. If not provided, the default /public/social-card.webp will be used
16
tags:
17
  - "Blog"
18
  - "Blog"
19
//Optional field, tags, one per line
20
---
21
This is my first blog, welcome!
22
这是我的第一篇博客，欢迎您的到来！
23
//Blog content