Clina 的笔记本

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

对 GPCL 项目的锐评

2026-10-14T00:00:00.000Z

本文是对 GPCL 项目的锐评。

如果你感觉不适，请离开这里。

首先，我们打开 GPCL 项目的 GitHub 仓库首页。

一进来就看笑了，GoodPlanCraftLaunCher 是什么东西？“好计划启动器”？

提醒一下，PCL 全称叫 Plain Craft Launcher。

接下来，我们看看项目的 README。

‘轻量’

‘将启动器自身的资源占用控制在极低水平’

Electron 写的项目你给我谈轻量，占用低？？？

Chrome 可是吃内存大户，轻量到哪里去了？

‘Java 自动补全’

Java 自动补全 是哪里来的说法？不应该叫 Java 下载 / Java 运行环境补全 吗？

然后就是 Releases 的命名问题。

这 Releases 都是什么逆天名字啊！

我还去看了一下开发者的 “Wiki” 页面（其实是他自己的 Wiki）

看完后，我只想说：

这一堆奖项有什么含金量？

一堆县级和校级的奖项，加起来含金量怕不是还没我 CSP J 第一轮二等奖的含金量高

然后就是提交记录的问题

这一堆提交记录毫无规范可言

基本就是想到什么写什么

评价未完待续

博客作者 9 问答卷

2026-06-20T00:00:00.000Z

这篇是给 Another Dayu 那份博客作者问卷的答案

原问卷在这里：博客作者呀，我想采访你这 9 个问题！

1.我是谁，以及这个博客是什么#

我是 Clina_sama。

这个博客名叫 Clina_sama Blog ，主要就是我的一些想法，教程类的文章，偶尔看见什么好的资源也会分享在上面，就当是我在互联网上的一个窗户吧。

2.为什么开始写博客#

一开始是感觉有趣，后来就把自己想写的写上去了

3.我怎么完成一篇文章#

这个吗，我一般是自己先写文章，写完再让 AI 去总结

对的，就这

4. 有没有失去过动力#

有的，在今年 3 月后短暂失去了动力，现在已经恢复了

恢复的原因其实就是我又想写博客了:(

5. 搭建方式和成本#

目前大概是：

1
VSCodium/NeoVim --> 编写文章
2
Astro/Fuwari --> 博客构建
3
GitHub && Codeberg --> 版本记录和远端同步
4
Cloudflare Workers && Codeberg Pages --> 静态部署

成本的话，主要就是域名和时间

域名吗，clina.top 一年大概 30￥，150191.xyz 一年大概 5￥

就这么简单

6. 推荐自己一篇文章，也推荐一个喜欢的博客#

我的话，会推荐这篇：

cotalk-comments

原因很简单，因为这篇算是我最用心的一篇文章了，同时也花费了我很长的时间

喜欢的博客吗，我推荐这个：

Rebel Zhang’s Blog

7. 最近喜欢的东西#

这个吗，也不好说，无非就是玩玩游戏，写点文章之类的

8. 想做但还没做的事#

那可就多了，把 C++ 学会，学点 Python , Rust 和 PHP ，哦对了，还有学会一点法语

9. 写到最后#

写到最后，这篇问卷也就回答完了，我的博客又多了一篇可以展示的文章；而你，也收获了一份真诚的答卷。（双赢啦，嘿嘿！）

也感谢看到这里的你了！如果你对我感兴趣，欢迎来认识我，可以在 NodeLoc 上向我私信或者尝试直接加我的 XMPP/Matrix 账号哦！

在你的 Fuwari 博客中添加 Cotalk 评论系统

2026-06-18T00:00:00.000Z

Cotalk 是一个基于 Codeberg Issues 与 Gitalk 的评论系统，本文旨在介绍如何在 Fuwari 博客中添加这个评论系统。

准备工作#

你需要：

一个 Cloudflare 账户
一个 Codeberg 账户
一个正常运行的 Fuwari 博客
一个聪明的脑子

配置#

准备 Codeberg 仓库#

首先，我们需要在 Codeberg 上创建一个专门用于存储评论的仓库。这个仓库必须是公开的，因为 Cotalk 需要通过访问 Codeberg 仓库来加载和提交评论。

创建新仓库

登录 Codeberg , 点击右上角 ”+” 按钮
选择 “创建仓库”
填写仓库名称（如 fuwari-comments）和其他必要信息
确保仓库可见性设置为 Public

配置 Cotalk#

接下来，我们需要配置 Cotalk 以将评论与我们的仓库关联起来。

创建 Workers

打开 Cloudflare 控制面板，并使用你的 Cloudflare 账户登录。

点击 “计算”。

alt text

点击 “Workers 和 Pages”。

alt text

点击 “创建应用程序”。

alt text

点击 “从 Hello World! 开始”。

alt text

点击 “部署”。

alt text

点击 “编辑代码”。

alt text

在打开的 Code Server 编辑器中填入以下代码。

1
// Cloudflare Worker：CoTalk OAuth 安全代理
2
export default {
3
    async fetch(request, env) {
4
        const url = new URL(request.url);
5
        const blogOrigin = 'yourblogdomain'; // 你的博客域名
6

7
        // 封装 CORS 头部设置，避免遗漏
8
        const corsHeaders = {
9
            'Access-Control-Allow-Origin': blogOrigin,
10
            'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
11
            'Access-Control-Allow-Headers': 'Content-Type',
12
        };
13

14
        // CORS 预检
15
        if (request.method === 'OPTIONS') {
16
            return new Response(null, { headers: corsHeaders });
17
        }
18

19
        // ---------- 1. 授权请求：GET /authorize ----------
20
        if (request.method === 'GET' && url.pathname === '/authorize') {
21
            const clientId = url.searchParams.get('client_id');
22
            const redirectUri = url.searchParams.get('redirect_uri') || blogOrigin;
23
            const state = url.searchParams.get('state') || '';
24

25
            // 将前端回调地址和状态编码进 state
26
            const codebergState = JSON.stringify({
27
                redirect_uri: redirectUri,
28
                frontend_state: state,
29
            });
30

31
            const codebergAuthUrl = new URL('https://codeberg.org/login/oauth/authorize');
32
            codebergAuthUrl.searchParams.set('client_id', env.CLIENT_ID);
33
            codebergAuthUrl.searchParams.set('redirect_uri', `${url.origin}/callback`);
34
            codebergAuthUrl.searchParams.set('response_type', 'code');
35
            codebergAuthUrl.searchParams.set('state', codebergState);
36

37
            // ✅ 302 重定向务必带上 CORS 头
38
            return new Response(null, {
39
                status: 302,
40
                headers: {
41
                    ...corsHeaders,               // CORS 头
42
                    'Location': codebergAuthUrl.toString(),
43
                },
44
            });
45
        }
46

47
        // ---------- 2. 回调处理：GET /callback ----------
48
        if (request.method === 'GET' && url.pathname === '/callback') {
49
            const code = url.searchParams.get('code');
50
            const stateParam = url.searchParams.get('state');
51

52
            if (!code || !stateParam) {
53
                return new Response('Missing code or state', { status: 400, headers: corsHeaders });
54
            }
55

56
            let parsedState;
57
            try {
58
                parsedState = JSON.parse(stateParam);
59
            } catch {
60
                return new Response('Invalid state parameter', { status: 400, headers: corsHeaders });
61
            }
62

63
            const redirectUri = parsedState.redirect_uri || blogOrigin;
64
            const frontendState = parsedState.frontend_state || '';
65

66
            try {
67
                const tokenResponse = await fetch('https://codeberg.org/login/oauth/access_token', {
68
                    method: 'POST',
69
                    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
70
                    body: JSON.stringify({
71
                        client_id: env.CLIENT_ID,
72
                        client_secret: env.CLIENT_SECRET,
73
                        code,
74
                        grant_type: 'authorization_code',
75
                        redirect_uri: `${url.origin}/callback`,
76
                    }),
77
                });
78

79
                const tokenData = await tokenResponse.json().catch(() => null);
80

81
                if (!tokenData || tokenData.error) {
82
                    const errorRedirect = new URL(redirectUri);
83
                    errorRedirect.hash = `error=${tokenData?.error || 'unknown'}&error_description=${encodeURIComponent(tokenData?.error_description || 'Token exchange failed')}`;
84
                    return new Response(null, {
85
                        status: 302,
86
                        headers: { ...corsHeaders, 'Location': errorRedirect.toString() },
87
                    });
88
                }
89

90
                if (!tokenData.access_token) {
91
                    throw new Error('No access_token in response');
92
                }
93

94
                const frontendRedirect = new URL(redirectUri);
95
                const hashParams = new URLSearchParams();
96
                hashParams.set('access_token', tokenData.access_token);
97
                hashParams.set('token_type', tokenData.token_type || 'bearer');
98
                if (frontendState) hashParams.set('state', frontendState);
99
                frontendRedirect.hash = hashParams.toString();
100

101
                return new Response(null, {
102
                    status: 302,
103
                    headers: { ...corsHeaders, 'Location': frontendRedirect.toString() },
104
                });
105
            } catch (err) {
106
                const errorRedirect = new URL(redirectUri);
107
                errorRedirect.hash = `error=server_error&error_description=${encodeURIComponent(err.message)}`;
108
                return new Response(null, {
109
                    status: 302,
110
                    headers: { ...corsHeaders, 'Location': errorRedirect.toString() },
111
                });
112
            }
113
        }
114

115
        // ---------- 3. Token 交换：POST /access_token ----------
116
        if (request.method === 'POST' && url.pathname === '/access_token') {
117
            try {
118
                const { code } = await request.json();
119
                if (!code) {
120
                    return new Response(JSON.stringify({ error: 'Code missing' }), {
121
                        status: 400,
122
                        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
123
                    });
124
                }
125

126
                const tokenResponse = await fetch('https://codeberg.org/login/oauth/access_token', {
127
                    method: 'POST',
128
                    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
129
                    body: JSON.stringify({
130
                        client_id: env.CLIENT_ID,
131
                        client_secret: env.CLIENT_SECRET,
132
                        code,
133
                        grant_type: 'authorization_code',
134
                        redirect_uri: `${url.origin}/callback`,
135
                    }),
136
                });
137

138
                const data = await tokenResponse.json().catch(() => ({ error: 'Invalid JSON' }));
139
                return new Response(JSON.stringify(data), {
140
                    status: data.error ? 400 : 200,
141
                    headers: { ...corsHeaders, 'Content-Type': 'application/json' },
142
                });
143
            } catch (err) {
144
                return new Response(JSON.stringify({ error: 'server_error' }), {
145
                    status: 500,
146
                    headers: { ...corsHeaders, 'Content-Type': 'application/json' },
147
                });
148
            }
149
        }
150

151
        return new Response('Not Found', { status: 404, headers: corsHeaders });
152
    },
153
};

展开收起

将 yourblogdomain 字段替换为你的博客域名。

更改后，点击 “部署”。

配置 OAuth

打开 Codeberg OAuth 应用程序创建界面，创建一个 OAuth 应用，并记下 客户端 ID 与 客户端密钥。

回到 Cloudflare 控制面板，进入你刚刚创建的 Workers 应用。

点击 “设置”。

alt text

点击 “添加”。

添加一条密钥，名称为 CLIENT_ID ，内容为你刚刚创建的 OAuth 应用的 客户端 ID。

再添加一条密钥，名称为 CLIENT_SECRET ，内容为你刚刚创建的 OAuth 应用的 客户端密钥。

创建好后，长这样：

alt text

然后，点击 “域”。

alt text

记住下面的 “Worker URL”。

回到 Codeberg OAuth 应用程序创建界面，点击你刚才创建的 OAuth 应用，在 “重定向 URI” 一栏填入 刚才的 Worker URL/callback ，点击保存。

获取配置信息

完成以上步骤后，记录以下配置信息，稍后将在 Fuwari 中使用：

仓库名称
客户端 ID
Workers URL

添加到 Fuwari#

创建 Cotalk 组件

为了实现在亮色/暗色下都能使 Cotalk 完美显示,我们需要在 src/components/misc/ 目录下创建 Cotalk.astro 文件，内容如下：

src/components/misc/Cotalk.astro展开收起

1
---
2
// src/components/comment/Cotalk.astro
3
export interface Props {
4
  clientID: string;
5
  proxy: string;
6
  repo: string;
7
  owner: string;
8
  admin: string[];
9
  id?: string;
10
  number?: number;
11
  labels?: string[];
12
  title?: string;
13
  language?: string;
14
  perPage?: number;
15
  distractionFreeMode?: boolean;
16
  pagerDirection?: 'last' | 'first';
17
  createIssueManually?: boolean;
18
  enableHotKey?: boolean;
19
}
20

21
const {
22
  clientID,
23
  proxy,
24
  repo,
25
  owner,
26
  admin,
27
  id,
28
  number = -1,
29
  labels = ['Cotalk'],
30
  title = '',
31
  language = 'zh-CN',
32
  perPage = 10,
33
  distractionFreeMode = false,
34
  pagerDirection = 'last',
35
  createIssueManually = false,
36
  enableHotKey = true,
37
} = Astro.props;
38

39
// 提前构建配置对象，确保所有解构变量都被使用
40
const config = {
41
  clientID,
42
  proxy,
43
  repo,
44
  owner,
45
  admin,
46
  id: id || null,
47
  number,
48
  labels,
49
  title: title || null,
50
  language,
51
  perPage,
52
  distractionFreeMode,
53
  pagerDirection,
54
  createIssueManually,
55
  enableHotKey,
56
};
57

58
// 序列化一次，供模板使用
59
const configJSON = JSON.stringify(config);
60
---
61

62
<div id="cotalk-container" class="cotalk-root">div>
63

64
65
<script type="application/json" id="cotalk-config" set:html={configJSON}>script>
66

67
68
<script>
69
  if (!document.querySelector('link[href*="cotalk.css"]')) {
70
    const link = document.createElement('link');
71
    link.rel = 'stylesheet';
72
    link.href = 'https://unpkg.com/@clina_z/cotalk@latest/dist/cotalk.css';
73
    document.head.appendChild(link);
74
  }
75
script>
76

77
78
<script>
79
  // 声明全局变量 Cotalk，避免 TypeScript 报错
80
  declare var Cotalk: any;
81

82
  (function () {
83
    function getConfig() {
84
      const configEl = document.getElementById('cotalk-config');
85
      if (!configEl) return null;
86
      try {
87
        return JSON.parse(configEl.textContent);
88
      } catch (e) {
89
        console.error('解析 CoTalk 配置失败', e);
90
        return null;
91
      }
92
    }
93

94
    function loadCotalkScript(): Promise<void> {
95
      return new Promise<void>((resolve, reject) => {
96
        if ((window as any).Cotalk) return resolve();
97
        const script = document.createElement('script');
98
        script.src = 'https://unpkg.com/@clina_z/cotalk@latest/dist/cotalk.min.js';
99
        script.onload = () => {
100
          if ((window as any).Cotalk) resolve();
101
          else reject(new Error('Cotalk 全局变量未暴露'));
102
        };
103
        script.onerror = () => reject(new Error('Cotalk 脚本加载失败'));
104
        document.head.appendChild(script);
105
      });
106
    }
107

108
    async function initCotalk(): Promise<void> {
109
      try {
110
        const config = getConfig();
111
        if (!config) return;
112

113
        await loadCotalkScript();
114
        const container = document.getElementById('cotalk-container');
115
        if (!container) return;
116

117
        // 清空容器（为 SWUP 切换页面做准备）
118
        container.innerHTML = '';
119

120
        const finalId = config.id || window.location.pathname;
121
        const finalTitle = config.title || document.title;
122

123
        const cotalk = new Cotalk({
124
          clientID: config.clientID,
125
          proxy: config.proxy,
126
          repo: config.repo,
127
          owner: config.owner,
128
          admin: config.admin,
129
          id: finalId,
130
          number: config.number,
131
          labels: config.labels,
132
          title: finalTitle,
133
          language: config.language,
134
          perPage: config.perPage,
135
          distractionFreeMode: config.distractionFreeMode,
136
          pagerDirection: config.pagerDirection,
137
          createIssueManually: config.createIssueManually,
138
          enableHotKey: config.enableHotKey,
139
        });
140

141
        cotalk.render(container);
142
      } catch (e) {
143
        console.error('CoTalk 初始化失败:', e);
144
      }
145
    }
146

147
    // 首次加载
148
    initCotalk();
149

150
    // SWUP 无刷新页面切换
151
    if (window.swup) {
152
      window.swup.hooks.on('page:view', initCotalk);
153
      document.addEventListener('swup:contentReplaced', initCotalk);
154
    }
155

156
    // 主题切换时重新渲染
157
    const observer = new MutationObserver((mutations) => {
158
      for (const mutation of mutations) {
159
        if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
160
          initCotalk();
161
          break;
162
        }
163
      }
164
    });
165
    observer.observe(document.documentElement, {
166
      attributes: true,
167
      attributeFilter: ['class'],
168
    });
169
  })();
170
script>
171

172
<style is:global>
173
  #cotalk-container {
174
    width: 100%;
175
    margin-top: 2rem;
176
  }
177
style>

展开收起

接下来，在 src/pages/posts/[...slug].astro 中引入 Cotalk：

src/pages/posts/[...slug].astro

1
---
2
import path from "node:path";
3
import { render } from "astro:content";
4
import License from "@components/misc/License.astro";
5
import Markdown from "@components/misc/Markdown.astro";
6
import Cotalk from "../../components/misc/Cotalk.astro";
7
import BlogInvitationCard from '@components/BlogInvitationCard.astro';
8
import I18nKey from "@i18n/i18nKey";

然后在许可证组件之后添加 Cotalk 组件：

src/pages/posts/[...slug].astro展开收起

1
  {licenseConfig.enable && <License title={entry.data.title} slug={entry.id} pubDate={entry.data.published} class="mb-6 rounded-xl license-container onload-animation">License>}
2

3

4
   <Cotalk
5
    clientID="yourclientid"
6
    proxy="yourworkerurl"
7
    repo="repo"
8
    owner="yourusername"
9
    admin={['yourusername']}
10
    id={Astro.url.pathname}
11
    language="zh-CN"
12
    />
13
  div>
14
 div>
15

16
<div class="flex flex-col md:flex-row justify-between mb-4 gap-4 overflow-hidden w-full">
17
 <a href={entry.data.nextSlug ? getPostUrlBySlug(entry.data.nextSlug) : "#"}
18
  class:list={["w-full font-bold overflow-hidden active:scale-95", {"pointer-events-none": !entry.data.nextSlug}]}>
19
  {entry.data.nextSlug && <div class="btn-card rounded-2xl w-full h-[3.75rem] max-w-full px-4 flex items-center !justify-start gap-4" >
20
   <Icon name="material-symbols:chevron-left-rounded" class="text-[2rem] text-[var(--primary)]" />
21
   <div class="overflow-hidden transition overflow-ellipsis whitespace-nowrap max-w-[calc(100%_-_3rem)] text-black/75 dark:text-white/75">
22
    {entry.data.nextTitle}
23
   div>
24
  div>}
25
 a>

展开收起

保存文件后重新构建项目即可看到评论区。

通过以上步骤，你就成功为 Fuwari 添加了功能完善的评论系统！

啥是 CC 协议？

2026-03-26T00:00:00.000Z

当你看到这个博客的文章结尾都写着 许可协议 CC BY-SA 4.0 时，你可能会疑惑：CC 协议是什么？

这篇文章就简单的来说一下 CC 协议。

首先，我们要知道 CC 协议是一种公共版权许可。

这是他们的官网：https://creativecommons.org/

CC 协议拥有多种授权要素，这里介绍一下几种常用的。

BY(Attribution): 要求在他人在使用某作品时，须注明原作者。

NC(Non Commercial): 要求在他人在使用某作品时，禁止用于商业用途。

ND(No Derivatives): 要求在他人在使用某作品时，禁止修改。

SA(ShareAlike): 要求在他人在使用某作品时，须使用相同协议发布。

注：SA 与 ND 互斥，无法同时使用。

这些授权要素可以相互组合。

比如，我的博客使用 CC BY-A 协议，而自由软件中文网则使用 CC BY-SA 协议，所以，自由软件中文网的文章可以商用，我的博客上面的文章也可以。

还有一种特殊的 CC 协议：CC0 , 它要求原作者放弃在作品上的全部著作权和邻接权，使作品进入公共领域，成为人类共同的知识财产，之后任何⼈都可以在不标示作者和来源的情况下⽆条件地将作品⽤于商业⽤途，⽆需经过任何申请，权利⼈或所有⼈也⽆权再追究责任。

这就是 CC 协议。

对 Fuwari 进行亿些改动（已存档）

2026-03-20T00:00:00.000Z

1. 增加评论#

参考这篇文章

2. 增加友链#

参考这篇文章

3. 增加访问统计卡片#

参考这篇文章

4. 图片标题#

参考这个 PR

5. 音乐播放器#

参考这篇文章

6. Codeberg 仓库卡片#

在 src/plugins 新建 rehype-component-codeberg-card.mjs 文件，并写入以下内容：

rehype-component-codeberg-card.mjs展开收起

1
/// <reference types="mdast" />
2
import { h } from "hastscript";
3

4
/**
5
 * Creates a Codeberg Card component.
6
 *
7
 * @param {Object} properties - The properties of the component.
8
 * @param {string} properties.repo - The Codeberg repository in the format "owner/repo".
9
 * @param {import('mdast').RootContent[]} children - The children elements of the component.
10
 * @returns {import('mdast').Parent} The created Codeberg Card component.
11
 */
12
export function CodebergCardComponent(properties, children) {
13
 if (Array.isArray(children) && children.length !== 0)
14
  return h("div", { class: "hidden" }, [
15
   'Invalid directive. ("codeberg" directive must be leaf type "::codeberg{repo="owner/repo"}")',
16
  ]);
17

18
 if (!properties.repo || !properties.repo.includes("/"))
19
  return h(
20
   "div",
21
   { class: "hidden" },
22
   'Invalid repository. ("repo" attributte must be in the format "owner/repo")',
23
  );
24

25
 const repo = properties.repo;
26
 const cardUuid = `GC${Math.random().toString(36).slice(-6)}`; // Collisions are not important
27

28
 const nAvatar = h(`div#${cardUuid}-avatar`, { class: "gc-avatar" });
29
 const nLanguage = h(
30
  `span#${cardUuid}-language`,
31
  { class: "gc-language" },
32
  "Waiting...",
33
 );
34

35
 const nTitle = h("div", { class: "gc-titlebar" }, [
36
  h("div", { class: "gc-titlebar-left" }, [
37
   h("div", { class: "gc-owner" }, [
38
    nAvatar,
39
    h("div", { class: "gc-user" }, repo.split("/")[0]),
40
   ]),
41
   h("div", { class: "gc-divider" }, "/"),
42
   h("div", { class: "gc-repo" }, repo.split("/")[1]),
43
  ]),
44
  h("div", { class: "codeberg-logo" }),
45
 ]);
46

47
 const nDescription = h(
48
  `div#${cardUuid}-description`,
49
  { class: "gc-description" },
50
  "Waiting for codeberg.org/api/v1...",
51
 );
52

53
 const nStars = h(`div#${cardUuid}-stars`, { class: "gc-stars" }, "00K");
54
 const nForks = h(`div#${cardUuid}-forks`, { class: "gc-forks" }, "0K");
55
 const nLicense = h(`div#${cardUuid}-license`, { class: "gc-license" }, "0K");
56

57
 const nScript = h(
58
  `script#${cardUuid}-script`,
59
  { type: "text/javascript", defer: true },
60
  `
61
      fetch('https://codeberg.org/api/v1/repos/${repo}', { referrerPolicy: "no-referrer" }).then(response => response.json()).then(data => {
62
        document.getElementById('${cardUuid}-description').innerText = data.description?.replace(/:[a-zA-Z0-9_]+:/g, '') || "Description not set";
63
        document.getElementById('${cardUuid}-language').innerText = data.language;
64
        document.getElementById('${cardUuid}-forks').innerText = Intl.NumberFormat('en-us', { notation: "compact", maximumFractionDigits: 1 }).format(data.forks_count).replaceAll("\u202f", '');
65
        document.getElementById('${cardUuid}-stars').innerText = Intl.NumberFormat('en-us', { notation: "compact", maximumFractionDigits: 1 }).format(data.stars_count).replaceAll("\u202f", '');
66
        const avatarEl = document.getElementById('${cardUuid}-avatar');
67
        avatarEl.style.backgroundImage = 'url(' + data.owner.avatar_url + ')';
68
        avatarEl.style.backgroundColor = 'transparent';
69
        // Codeberg API does not provide license information, hiding the license field
70
        document.getElementById('${cardUuid}-license').style.display = 'none';
71
        document.getElementById('${cardUuid}-card').classList.remove("fetch-waiting");
72
        console.log("[CODEBERG-CARD] Loaded card for ${repo} | ${cardUuid}.")
73
      }).catch(err => {
74
        const c = document.getElementById('${cardUuid}-card');
75
        c?.classList.add("fetch-error");
76
        console.warn("[CODEBERG-CARD] (Error) Loading card for ${repo} | ${cardUuid}.")
77
      })
78
    `,
79
 );
80

81
 return h(
82
  `a#${cardUuid}-card`,
83
  {
84
   class: "card-codeberg fetch-waiting no-styling",
85
   href: `https://codeberg.org/${repo}`,
86
   target: "_blank",
87
   repo,
88
  },
89
  [
90
   nTitle,
91
   nDescription,
92
   h("div", { class: "gc-infobar" }, [nStars, nForks, nLicense, nLanguage]),
93
   nScript,
94
  ],
95
 );
96
}

展开收起

然后，在 astro.config.mjs 中添加以下内容：

astro.config.mjs展开收起


20 collapsed lines
1
import sitemap from "@astrojs/sitemap";
2
import svelte from "@astrojs/svelte";
3
import tailwind from "@astrojs/tailwind";
4
import mdx from '@astrojs/mdx';
5
import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";
6
import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
7
import swup from "@swup/astro";
8
import expressiveCode from "astro-expressive-code";
9
import icon from "astro-icon";
10
import { defineConfig } from "astro/config";
11
import rehypeAutolinkHeadings from "rehype-autolink-headings";
12
import rehypeComponents from "rehype-components"; /* Render the custom directive content */
13
import rehypeKatex from "rehype-katex";
14
import rehypeSlug from "rehype-slug";
15
import remarkDirective from "remark-directive"; /* Handle directives */
16
import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives";
17
import remarkMath from "remark-math";
18
import remarkSectionize from "remark-sectionize";
19
import { expressiveCodeConfig } from "./src/config.ts";
20
import { pluginLanguageBadge } from "./src/plugins/expressive-code/language-badge.ts";
21
import { AdmonitionComponent } from "./src/plugins/rehype-component-admonition.mjs";
22
import { CodebergCardComponent } from "./src/plugins/rehype-component-codeberg-card.mjs";
23
import { GithubCardComponent } from "./src/plugins/rehype-component-github-card.mjs";
110 collapsed lines
24
import { parseDirectiveNode } from "./src/plugins/remark-directive-rehype.js";
25
import { remarkExcerpt } from "./src/plugins/remark-excerpt.js";
26
import { remarkReadingTime } from "./src/plugins/remark-reading-time.mjs";
27
import { pluginCustomCopyButton } from "./src/plugins/expressive-code/custom-copy-button.js";
28

29
// https://astro.build/config
30
export default defineConfig({
31
 site: "https://cli.loc.cc",
32
 base: "/",
33
 trailingSlash: "always",
34
 image: {
35
  // 全局响应式布局
36
  layout: "constrained",
37
 },
38
 experimental: {
39
  // Rust 编译器以提升构建性能（实验性）
40
  // 队列渲染以优化性能（实验性）
41
  queuedRendering: { enabled: true },
42
 },
43
 integrations: [
44
  tailwind({
45
   nesting: true,
46
  }),
47
  swup({
48
   theme: false,
49
   animationClass: "transition-swup-", // see https://swup.js.org/options/#animationselector
50
   // the default value `transition-` cause transition delay
51
   // when the Tailwind class `transition-all` is used
52
   containers: ["main", "#toc"],
53
   smoothScrolling: true,
54
   cache: true,
55
   preload: true,
56
   accessibility: true,
57
   updateHead: true,
58
   updateBodyClass: false,
59
   globalInstance: true,
60
  }),
61
  icon({
62
   include: {
63
    "preprocess: vitePreprocess(),": ["*"],
64
    "fa6-brands": ["*"],
65
    "fa6-regular": ["*"],
66
    "fa6-solid": ["*"],
67
   },
68
  }),
69
  expressiveCode({
70
   themes: [expressiveCodeConfig.darkTheme, expressiveCodeConfig.lightTheme],
71
   useDarkModeMediaQuery: false,
72
   plugins: [
73
    pluginCollapsibleSections(),
74
    pluginLineNumbers(),
75
    pluginLanguageBadge(),
76
    pluginCustomCopyButton()
77
   ],
78
   defaultProps: {
79
    wrap: true,
80
    overridesByLang: {
81
     shellsession: {
82
      showLineNumbers: false,
83
     },
84
    },
85
   },
86
   styleOverrides: {
87
    codeBackground: "var(--codeblock-bg)",
88
    borderRadius: "0.75rem",
89
    borderColor: "none",
90
    codeFontSize: "0.875rem",
91
    codeFontFamily: "'JetBrains Mono Variable', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
92
    codeLineHeight: "1.5rem",
93
    frames: {
94
     editorBackground: "var(--codeblock-bg)",
95
     terminalBackground: "var(--codeblock-bg)",
96
     terminalTitlebarBackground: "var(--codeblock-topbar-bg)",
97
     editorTabBarBackground: "var(--codeblock-topbar-bg)",
98
     editorActiveTabBackground: "none",
99
     editorActiveTabIndicatorBottomColor: "var(--primary)",
100
     editorActiveTabIndicatorTopColor: "none",
101
     editorTabBarBorderBottomColor: "var(--codeblock-topbar-bg)",
102
     terminalTitlebarBorderBottomColor: "none"
103
    },
104
    textMarkers: {
105
     delHue: 0,
106
     insHue: 180,
107
     markHue: 250
108
    }
109
   },
110
   frames: {
111
    showCopyToClipboardButton: false,
112
   }
113
  }),
114
        svelte(),
115
  sitemap(),
116
  mdx(),
117
 ],
118
 markdown: {
119
  remarkPlugins: [
120
   remarkMath,
121
   remarkReadingTime,
122
   remarkExcerpt,
123
   remarkGithubAdmonitionsToDirectives,
124
   remarkDirective,
125
   remarkSectionize,
126
   parseDirectiveNode,
127
  ],
128
  rehypePlugins: [
129
   rehypeKatex,
130
   rehypeSlug,
131
   [
132
    rehypeComponents,
133
    {
134
     components: {
135
      codeberg: CodebergCardComponent,
136
      github: GithubCardComponent,
50 collapsed lines
137
      note: (x, y) => AdmonitionComponent(x, y, "note"),
138
      tip: (x, y) => AdmonitionComponent(x, y, "tip"),
139
      important: (x, y) => AdmonitionComponent(x, y, "important"),
140
      caution: (x, y) => AdmonitionComponent(x, y, "caution"),
141
      warning: (x, y) => AdmonitionComponent(x, y, "warning"),
142
     },
143
    },
144
   ],
145
   [
146
    rehypeAutolinkHeadings,
147
    {
148
     behavior: "append",
149
     properties: {
150
      className: ["anchor"],
151
     },
152
     content: {
153
      type: "element",
154
      tagName: "span",
155
      properties: {
156
       className: ["anchor-icon"],
157
       "data-pagefind-ignore": true,
158
      },
159
      children: [
160
       {
161
        type: "text",
162
        value: "#",
163
       },
164
      ],
165
     },
166
    },
167
   ],
168
  ],
169
 },
170
 vite: {
171
  build: {
172
   rollupOptions: {
173
    onwarn(warning, warn) {
174
     // temporarily suppress this warning
175
     if (
176
      warning.message.includes("is dynamically imported by") &&
177
      warning.message.includes("but also statically imported by")
178
     ) {
179
      return;
180
     }
181
     warn(warning);
182
    },
183
   },
184
  },
185
 },
186
});

展开收起

然后，在 markdown-extend.styl 添加以下内容：

markdown-extend.styl展开收起


227 collapsed lines
1
.custom-md
2

3
  blockquote.admonition
4
    .bdm-title
5
      display: flex
6
      align-items: center
7
      margin-bottom: -.9rem
8
      font-weight: bold
9

10
      &:before
11
        content: ' '
12
        display: inline-block
13
        font-size: inherit
14
        overflow: visible
15
        margin-right: .6rem
16
        height: 1em
17
        width: 1em
18
        vertical-align: -.126em
19
        mask-size: contain
20
        mask-position: center
21
        mask-repeat: no-repeat
22
        transform: translateY(-0.0625rem)
23
    &.bdm-tip
24
      .bdm-title
25
        color: var(--admonitions-color-tip)
26

27
        &:before
28
          background: var(--admonitions-color-tip)
29
          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath d='M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z'%3E%3C/path%3E%3C/svg%3E")
30

31
      &:before
32
        background: var(--admonitions-color-tip)
33
    &.bdm-note
34
      .bdm-title
35
        color: var(--admonitions-color-note)
36

37
        &:before
38
          background: var(--admonitions-color-note)
39
          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath fill='var(--admonitions-color-tip)' d='M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z'%3E%3C/path%3E%3C/svg%3E")
40

41
      &:before
42
        background: var(--admonitions-color-note)
43
    &.bdm-important
44
      .bdm-title
45
        color: var(--admonitions-color-important)
46

47
        &:before
48
          background: var(--admonitions-color-important)
49
          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath d='M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z'%3E%3C/path%3E%3C/svg%3E")
50

51
      &:before
52
        background: var(--admonitions-color-important)
53
    &.bdm-warning
54
      .bdm-title
55
        color: var(--admonitions-color-warning)
56

57
        &:before
58
          background: var(--admonitions-color-warning)
59
          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath d='M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z'%3E%3C/path%3E%3C/svg%3E")
60

61
      &:before
62
        background: var(--admonitions-color-warning)
63
    &.bdm-caution
64
      .bdm-title
65
        color: var(--admonitions-color-caution)
66

67
        &:before
68
          background: var(--admonitions-color-caution)
69
          mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath d='M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z'%3E%3C/path%3E%3C/svg%3E")
70

71
      &:before
72
        background: var(--admonitions-color-caution)
73

74
  img
75
    border-radius: 0.75rem
76

77
  hr
78
    border-color: var(--line-divider)
79
    border-style: dashed
80

81
  iframe
82
    border-radius: 0.75rem
83
    margin-left: auto
84
    margin-right: auto
85
    max-width: 100%
86

87
a.card-github
88
  display: block
89
  background: var(--license-block-bg)
90
  position: relative
91
  margin: 0.5rem 0
92
  padding: 1.1rem 1.5rem 1.1rem 1.5rem
93
  color: var(--tw-prose-body)
94
  border-radius: var(--radius-large)
95
  text-decoration-thickness: 0px
96
  text-decoration-line: none
97

98
  &:hover
99
    background-color: var(--btn-regular-bg-hover)
100

101
    .gc-titlebar
102
      color: var(--btn-content)
103

104
    .gc-stars, .gc-forks, .gc-license, .gc-description
105
      color: var(--tw-prose-headings)
106

107
      &:before
108
        background-color: var(--tw-prose-headings)
109

110
  &:active
111
    scale: .98
112
    background-color: var(--btn-regular-bg-active);
113

114
  .gc-titlebar
115
    display: flex
116
    align-items: center
117
    justify-content: space-between
118
    margin-bottom: 0.5rem
119
    color: var(--tw-prose-headings)
120
    font-size: 1.25rem
121
    font-weight: 500
122

123
    .gc-titlebar-left
124
      display: flex
125
      flex-flow: row nowrap
126
      gap: 0.5rem
127

128
    .gc-repo
129
      font-weight: bold
130

131
    .gc-owner
132
      font-weight: 300
133
      position: relative
134
      display: flex
135
      flex-flow: row nowrap
136
      gap: 0.5rem
137
      align-items: center
138

139
    .gc-avatar
140
      display: block
141
      overflow: hidden
142
      width: 1.5rem
143
      height: 1.5rem
144
      margin-top: -0.1rem
145
      background-color: var(--primary)
146
      background-size: cover
147
      border-radius: 50%
148

149
  .gc-description
150
    margin-bottom: 0.7rem
151
    font-size: 1rem
152
    font-weight: 300
153
    line-height: 1.5rem
154
    color: var(--tw-prose-body)
155

156
  .gc-infobar
157
    display: flex
158
    flex-flow: row nowrap
159
    gap: 1.5rem
160
    color: var(--tw-prose-body)
161
    width: fit-content
162

163
  .gc-language
164
    display: none
165

166
  .gc-stars, .gc-forks, .gc-license, .github-logo
167
    font-weight: 500
168
    font-size: 0.875rem
169
    opacity: 0.9;
170

171
    &:before
172
      content: ' '
173
      display: inline-block
174
      height: 1.3em
175
      width: 1.3em
176
      margin-right: .4rem
177
      vertical-align: -.24em
178
      font-size: inherit
179
      background-color: var(--tw-prose-body)
180
      overflow: visible
181
      mask-size: contain
182
      mask-position: center
183
      mask-repeat: no-repeat
184
      transition-property: background-color, background;
185
      transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)
186
      transition-duration: 0.15s
187

188
  .gc-stars
189
    &:before
190
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' aria-hidden='true' height='16' viewBox='0 0 16 16' version='1.1' width='16'%3E%3Cpath d='M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Zm0 2.445L6.615 5.5a.75.75 0 0 1-.564.41l-3.097.45 2.24 2.184a.75.75 0 0 1 .216.664l-.528 3.084 2.769-1.456a.75.75 0 0 1 .698 0l2.77 1.456-.53-3.084a.75.75 0 0 1 .216-.664l2.24-2.183-3.096-.45a.75.75 0 0 1-.564-.41L8 2.694Z'%3E%3C/path%3E%3C/svg%3E")
191

192
  .gc-license
193
    &:before
194
      margin-right: .5rem
195
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' aria-hidden='true' height='16' viewBox='0 0 16 16' version='1.1' width='16'%3E%3Cpath d='M8.75.75V2h.985c.304 0 .603.08.867.231l1.29.736c.038.022.08.033.124.033h2.234a.75.75 0 0 1 0 1.5h-.427l2.111 4.692a.75.75 0 0 1-.154.838l-.53-.53.529.531-.001.002-.002.002-.006.006-.006.005-.01.01-.045.04c-.21.176-.441.327-.686.45C14.556 10.78 13.88 11 13 11a4.498 4.498 0 0 1-2.023-.454 3.544 3.544 0 0 1-.686-.45l-.045-.04-.016-.015-.006-.006-.004-.004v-.001a.75.75 0 0 1-.154-.838L12.178 4.5h-.162c-.305 0-.604-.079-.868-.231l-1.29-.736a.245.245 0 0 0-.124-.033H8.75V13h2.5a.75.75 0 0 1 0 1.5h-6.5a.75.75 0 0 1 0-1.5h2.5V3.5h-.984a.245.245 0 0 0-.124.033l-1.289.737c-.265.15-.564.23-.869.23h-.162l2.112 4.692a.75.75 0 0 1-.154.838l-.53-.53.529.531-.001.002-.002.002-.006.006-.016.015-.045.04c-.21.176-.441.327-.686.45C4.556 10.78 3.88 11 3 11a4.498 4.498 0 0 1-2.023-.454 3.544 3.544 0 0 1-.686-.45l-.045-.04-.016-.015-.006-.006-.004-.004v-.001a.75.75 0 0 1-.154-.838L2.178 4.5H1.75a.75.75 0 0 1 0-1.5h2.234a.249.249 0 0 0 .125-.033l1.288-.737c.265-.15.564-.23.869-.23h.984V.75a.75.75 0 0 1 1.5 0Zm2.945 8.477c.285.135.718.273 1.305.273s1.02-.138 1.305-.273L13 6.327Zm-10 0c.285.135.718.273 1.305.273s1.02-.138 1.305-.273L3 6.327Z'%3E%3C/path%3E%3C/svg%3E")
196

197
  .gc-forks
198
    &:before
199
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' aria-hidden='true' height='16' viewBox='0 0 16 16' version='1.1' width='16'%3E%3Cpath d='M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.878a2.25 2.25 0 1 1 1.5 0v.878a2.25 2.25 0 0 1-2.25 2.25h-1.5v2.128a2.251 2.251 0 1 1-1.5 0V8.5h-1.5A2.25 2.25 0 0 1 3.5 6.25v-.878a2.25 2.25 0 1 1 1.5 0ZM5 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Zm6.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm-3 8.75a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z'%3E%3C/path%3E%3C/svg%3E")
200

201
  .github-logo
202
    font-size: 1.25rem
203

204
    &:before
205
      background-color: var(--tw-prose-headings)
206
      margin-right: 0
207
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='31' height='32' viewBox='0 0 496 512'%3E%3Cpath fill='%23a1f7cb' d='M165.9 397.4c0 2-2.3 3.6-5.2 3.6c-3.3.3-5.6-1.3-5.6-3.6c0-2 2.3-3.6 5.2-3.6c3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9c2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9c.3 2 2.9 3.3 5.9 2.6c2.9-.7 4.9-2.6 4.6-4.6c-.3-1.9-3-3.2-5.9-2.9M244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2c12.8 2.3 17.3-5.6 17.3-12.1c0-6.2-.3-40.4-.3-61.4c0 0-70 15-84.7-29.8c0 0-11.4-29.1-27.8-36.6c0 0-22.9-15.7 1.6-15.4c0 0 24.9 2 38.6 25.8c21.9 38.6 58.6 27.5 72.9 20.9c2.3-16 8.8-27.1 16-33.7c-55.9-6.2-112.3-14.3-112.3-110.5c0-27.5 7.6-41.3 23.6-58.9c-2.6-6.5-11.1-33.3 2.6-67.9c20.9-6.5 69 27 69 27c20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27c13.7 34.7 5.2 61.4 2.6 67.9c16 17.7 25.8 31.5 25.8 58.9c0 96.5-58.9 104.2-114.8 110.5c9.2 7.9 17 22.9 17 46.4c0 33.7-.3 75.4-.3 83.6c0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252C496 113.3 383.5 8 244.8 8M97.2 352.9c-1.3 1-1 3.3.7 5.2c1.6 1.6 3.9 2.3 5.2 1c1.3-1 1-3.3-.7-5.2c-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9c1.6 1 3.6.7 4.3-.7c.7-1.3-.3-2.9-2.3-3.9c-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2c2.3 2.3 5.2 2.6 6.5 1c1.3-1.3.7-4.3-1.3-6.2c-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9c1.6 2.3 4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2c-1.4-2.3-4-3.3-5.6-2'/%3E%3C/svg%3E")
208

209
a.card-github.fetch-waiting
210
  pointer-events: none
211
  opacity: 0.7
212
  transition: opacity 0.15s ease-in-out
213

214
  .gc-description, .gc-infobar, .gc-avatar
215
    background-color: var(--tw-prose-body)
216
    color: transparent
217
    opacity: 0.5;
218
    animation: pulsate 2s infinite linear
219
    user-select: none
220

221
    &:before
222
      background-color: transparent
223

224
  .gc-repo
225
    margin-left: -0.1rem
226

227
  .gc-description, .gc-infobar
228
    border-radius: 0.5rem
229

230
a.card-codeberg
231
  display: block
232
  background: var(--license-block-bg)
233
  position: relative
234
  margin: 0.5rem 0
235
  padding: 1.1rem 1.5rem 1.1rem 1.5rem
236
  color: var(--tw-prose-body)
237
  border-radius: var(--radius-large)
238
  text-decoration-thickness: 0px
239
  text-decoration-line: none
240

241
  &:hover
242
    background-color: var(--btn-regular-bg-hover)
243

244
    .gc-titlebar
245
      color: var(--btn-content)
246

247
    .gc-stars, .gc-forks, .gc-license, .gc-description
248
      color: var(--tw-prose-headings)
249

250
      &:before
251
        background-color: var(--tw-prose-headings)
252

253
  &:active
254
    scale: .98
255
    background-color: var(--btn-regular-bg-active);
256

257
  .gc-titlebar
258
    display: flex
259
    align-items: center
260
    justify-content: space-between
261
    margin-bottom: 0.5rem
262
    color: var(--tw-prose-headings)
263
    font-size: 1.25rem
264
    font-weight: 500
265

266
    .gc-titlebar-left
267
      display: flex
268
      flex-flow: row nowrap
269
      gap: 0.5rem
270

271
    .gc-repo
272
      font-weight: bold
273

274
    .gc-owner
275
      font-weight: 300
276
      position: relative
277
      display: flex
278
      flex-flow: row nowrap
279
      gap: 0.5rem
280
      align-items: center
281

282
    .gc-avatar
283
      display: block
284
      overflow: hidden
285
      width: 1.5rem
286
      height: 1.5rem
287
      margin-top: -0.1rem
288
      background-color: var(--primary)
289
      background-size: cover
290
      border-radius: 50%
291

292
  .gc-description
293
    margin-bottom: 0.7rem
294
    font-size: 1rem
295
    font-weight: 300
296
    line-height: 1.5rem
297
    color: var(--tw-prose-body)
298

299
  .gc-infobar
300
    display: flex
301
    flex-flow: row nowrap
302
    gap: 1.5rem
303
    color: var(--tw-prose-body)
304
    width: fit-content
305

306
  .gc-language
307
    display: none
308

309
  .gc-stars, .gc-forks, .gc-license, .codeberg-logo
310
    font-weight: 500
311
    font-size: 0.875rem
312
    opacity: 0.9;
313

314
    &:before
315
      content: ' '
316
      display: inline-block
317
      height: 1.3em
318
      width: 1.3em
319
      margin-right: .4rem
320
      vertical-align: -.24em
321
      font-size: inherit
322
      background-color: var(--tw-prose-body)
323
      overflow: visible
324
      mask-size: contain
325
      mask-position: center
326
      mask-repeat: no-repeat
327
      transition-property: background-color, background;
328
      transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)
329
      transition-duration: 0.15s
330

331
  .gc-stars
332
    &:before
333
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' aria-hidden='true' height='16' viewBox='0 0 16 16' version='1.1' width='16'%3E%3Cpath d='M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Zm0 2.445L6.615 5.5a.75.75 0 0 1-.564.41l-3.097.45 2.24 2.184a.75.75 0 0 1 .216.664l-.528 3.084 2.769-1.456a.75.75 0 0 1 .698 0l2.77 1.456-.53-3.084a.75.75 0 0 1 .216-.664l2.24-2.183-3.096-.45a.75.75 0 0 1-.564-.41L8 2.694Z'%3E%3C/path%3E%3C/svg%3E")
334

335
  .gc-license
336
    display: none
337

338
  .gc-forks
339
    &:before
340
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' aria-hidden='true' height='16' viewBox='0 0 16 16' version='1.1' width='16'%3E%3Cpath d='M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.878a2.25 2.25 0 1 1 1.5 0v.878a2.25 2.25 0 0 1-2.25 2.25h-1.5v2.128a2.251 2.251 0 1 1-1.5 0V8.5h-1.5A2.25 2.25 0 0 1 3.5 6.25v-.878a2.25 2.25 0 1 1 1.5 0ZM5 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Zm6.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm-3 8.75a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z'%3E%3C/path%3E%3C/svg%3E")
341

342
  .codeberg-logo
343
    font-size: 1.25rem
344

345
    &:before
346
      background-color: var(--tw-prose-headings)
347
      margin-right: 0
348
      mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 128 128'%3E%3C!-- Icon from Devicon by konpa - https://github.com/devicons/devicon/blob/master/LICENSE --%3E%3Cdefs%3E%3ClinearGradient id='SVG5hsFW4SY' x1='42519.285' x2='42575.336' y1='-7078.789' y2='-6966.931' gradientTransform='translate(-31147.619 5228.94)scale(.73409)' gradientUnits='userSpaceOnUse' href='%23SVGB17cveaH'/%3E%3ClinearGradient id='SVGB17cveaH'%3E%3Cstop offset='0' stop-color='%232185d0' stop-opacity='0'/%3E%3Cstop offset='.495' stop-color='%232185d0' stop-opacity='.3'/%3E%3Cstop offset='1' stop-color='%232185d0' stop-opacity='.3'/%3E%3C/linearGradient%3E%3C/defs%3E%3Cpath fill='url(%23SVG5hsFW4SY)' d='M65.38 32.468a.558.417 0 0 0-.541.496l24.655 92.413a64 64 0 0 0 28.91-24.785L65.867 32.674a.558.417 0 0 0-.487-.206'/%3E%3Cpath fill='%232185d0' d='M63.998 2.623C28.652 2.623 0 31.28 0 66.625a64.03 64.03 0 0 0 9.77 33.993L63.133 31.63c.378-.495 1.345-.495 1.73 0l53.36 68.987A64 64 0 0 0 128 66.625c0-35.346-28.652-64.002-64.002-64.002'/%3E%3C/svg%3E")
349

350
a.card-codeberg.fetch-waiting
351
  pointer-events: none
352
  opacity: 0.7
353
  transition: opacity 0.15s ease-in-out
354

355
  .gc-description, .gc-infobar, .gc-avatar
356
    background-color: var(--tw-prose-body)
357
    color: transparent
358
    opacity: 0.5;
359
    animation: pulsate 2s infinite linear
360
    user-select: none
361

362
    &:before
363
      background-color: transparent
364

365
  .gc-repo
366
    margin-left: -0.1rem
367

368
  .gc-description, .gc-infobar
369
    border-radius: 0.5rem
370

371
a.card-codeberg.fetch-error
372
  pointer-events: all
373
  opacity: 1
374

375
@keyframes pulsate
11 collapsed lines
376
  0%
377
    opacity: 0.15
378
  50%
379
    opacity: 0.25
380
  100%
381
    opacity: 0.15
382

383
.card-codeberg, .card-github, .gc-description, .gc-titlebar, .gc-stars, .gc-forks, .gc-license, .gc-avatar, .codeberg-logo, .github-logo
384
  transition-property: all
385
  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)
386
  transition-duration: 0.15s

展开收起

效果：

7. 增加图片标题#

参考这个 PR

8. 更改字体#

参考这篇文章

9. 亮色代码块#

参考这个 PR

10. GitHub 文件卡片#

参考这个 PR

未完待续…

自由软件之输入法————手机篇

2026-03-07T00:00:00.000Z

本篇文章将介绍几款自由的手机输入法。

Android#

同文输入法 (Trime)#

osfans

trime

同文安卓輸入法平臺3.x/Android-rime/Rime Input Method Engine for Android

—

GPL-3.0

Kotlin

下载链接：

小企鹅输入法 (Fcitx 5 For Android)#

fcitx5-android

Fcitx5 input method framework and engines ported to Android

—

LGPL-2.1

Kotlin

最新稳定版下载链接：

最新构建版下载链接：

build status

语燕输入法 (YuyanIME)#

gurecn

YuyanIme

语燕输入法-一款基于Rime定制开发的九键、全拼、双拼、手写、火星文等方案、支持悬浮、单手、数字行等键盘模式的中文输入法

—

BSD-3-Clause

Kotlin

下载链接：

iOS#

Fcitx 5 For iOS#

fcitx-contrib

fcitx5-ios

Fcitx5 iOS edition, currently developer beta. 小企鹅输入法 iOS 开发者公测 https://t.me/fcitx5macos/16126

—

GPL-3.0

Swift

需要侧载安装。

Harmony OS#

小企鹅输入法鸿蒙版 (Fcitx 5 For Harmony OS)#

fcitx-contrib

fcitx5-harmony

Fcitx5 Harmony edition, currently not launched. 小企鹅输入法鸿蒙版还没上架 https://t.me/fcitx5harmony

—

GPL-3.0

下载链接：

同样需要侧载安装。

postmarket OS / Ubuntu Touch / Mobian / Pure OS#

输入法安装方式与 GNU/Linux 相同，这里不再详细讲解。

为自己的脚本语言编写VSCode支持扩展：从零到发布完整指南

2026-01-02T00:00:00.000Z

为自己的脚本语言编写VSCode支持扩展：从零到发布完整指南#

作者：colaSensei | 发布时间：2026年1月

最近我为自己设计的游戏脚本语言PGNCode开发了VSCode扩展，过程中积累了不少经验。如果你也有自己的DSL（领域特定语言）或脚本语言，这篇文章将带你完整走过为它创建VSCode扩展的每一个步骤。

为什么需要为自定义语言开发VSCode扩展？#

在我开发PaperVisualNovel引擎时，设计了PGNCode脚本语言。编写游戏需要编辑.pgn文件，但遇到了一些问题：

没有语法高亮：所有文本都是同一个颜色，难以区分命令、变量和注释
没有代码提示：需要记忆所有命令和参数格式
没有错误检查：语法错误只能在运行时发现
开发体验差：缺少现代IDE应有的功能

这些问题严重影响了开发效率。于是，我决定为PGNCode创建VSCode扩展。

准备工作#

技术栈需求#

Node.js (>= 14.x)（这个应该都有吧）
Visual Studio Code (用于开发和测试，这个不可能没有吧)
基础的前端知识 (JSON, 正则表达式)

开发工具#

Terminal window

1
# 安装VSCode扩展开发工具
2
npm install -g yo generator-code

第一步：创建扩展项目#

使用官方生成器创建基础项目：

Terminal window

1
# 创建项目目录
2
mkdir my-language-extension
3
cd my-language-extension
4

5
# 运行生成器
6
yo code

在交互式界面中选择：

New Language Support (新语言支持)
输入扩展名称、描述
指定语言ID、文件扩展名

这会生成一个基础的项目结构。

第二步：理解项目结构#

生成的项目包含以下核心文件：

1
my-language-extension/
2
├── package.json              # 扩展清单
3
├── syntaxes/
4
│   └── language.tmLanguage.json # 语法定义
5
├── language-configuration.json  # 语言配置
6
└── README.md                 # 说明文档

1. package.json - 扩展清单#

这是扩展的”身份证”，定义了扩展的基本信息和功能。

1
{
2
    "name": "my-language-support",
3
    "displayName": "My Language Support",
4
    "description": "Syntax highlighting for My Language",
5
    "version": "1.0.0",
6
    "publisher": "your-name",
7
    "engines": { "vscode": "^1.75.0" },
8
    "categories": ["Programming Languages"],
9
    "contributes": {
10
        "languages": [{
11
            "id": "mylang",
12
            "aliases": ["My Language", "mylang"],
13
            "extensions": [".mylang", ".ml"],
14
            "configuration": "./language-configuration.json"
15
        }],
16
        "grammars": [{
17
            "language": "mylang",
18
            "scopeName": "source.mylang",
19
            "path": "./syntaxes/mylang.tmLanguage.json"
20
        }]
21
    }
22
}

展开收起

2. 语法定义文件 (TextMate语法)#

这是最核心的部分，定义了如何高亮代码。VSCode使用TextMate语法系统。

1
{
2
    "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
3
    "scopeName": "source.mylang",
4
    "patterns": [
5
        {
6
            "name": "comment.line.mylang",
7
            "match": "//.*"
8
        },
9
        {
10
            "name": "keyword.control.mylang",
11
            "match": "\\b(if|else|while|for|return)\\b"
12
        },
13
        {
14
            "name": "constant.numeric.mylang",
15
            "match": "\\b\\d+(\\.\\d+)?\\b"
16
        }
17
    ]
18
}

展开收起

关键概念：

scopeName: 语法的根作用域
patterns: 匹配规则数组
name: 作用域名称，决定高亮颜色
match: 正则表达式匹配模式

3. 语言配置文件#

定义语言的编辑特性：

1
{
2
    "comments": {
3
        "lineComment": "//",
4
        "blockComment": ["/*", "*/"]
5
    },
6
    "brackets": [
7
        ["{", "}"],
8
        ["[", "]"],
9
        ["(", ")"]
10
    ],
11
    "autoClosingPairs": [
12
        { "open": "{", "close": "}" },
13
        { "open": "[", "close": "]" },
14
        { "open": "(", "close": ")" },
15
        { "open": "\"", "close": "\"" }
16
    ],
17
    "indentationRules": {
18
        "increaseIndentPattern": "^.*\\{[^}\"]*$|^.*\\([^)\"]*$",
19
        "decreaseIndentPattern": "^\\s*\\}|^\\s*\\)"
20
    }
21
}

展开收起

第三步：设计语法高亮规则#

分析语言特性#

以我的PGNCode为例，我需要识别：

注释：// 这是注释
命令：say, wait, set, if 等
变量：${variable} 格式
数字：整数和小数
字符串：引号内的文本
标签：LABEL_NAME: 格式

编写匹配规则#

1
{
2
    "scopeName": "source.pgn",
3
    "patterns": [
4
        // 注释
5
        {
6
            "name": "comment.line.double-slash.pgn",
7
            "match": "//.*"
8
        },
9

10
        // 命令（小心处理边界）
11
        {
12
            "name": "keyword.control.pgn",
13
            "match": "(?\\$\\{)\\b(say|wait|set|if|choose)\\b(?!\\})"
14
        },
15

16
        // 变量引用
17
        {
18
            "name": "variable.parameter.pgn",
19
            "begin": "\\$\\{",
20
            "end": "\\}",
21
            "patterns": [
22
                {
23
                    "name": "variable.other.pgn",
24
                    "match": "[a-zA-Z_][a-zA-Z0-9_]*"
25
                }
26
            ]
27
        },
28

29
        // 标签定义（行首的单词后跟冒号）
30
        {
31
            "name": "entity.name.tag.pgn",
32
            "match": "^\\s*[A-Za-z_][A-Za-z0-9_]*:"
33
        }
34
    ]
35
}

展开收起

技巧：

使用begin/end处理嵌套结构
使用负向零宽断言避免错误匹配
从简单规则开始，逐步完善

第四步：添加代码片段#

代码片段可以极大提高编码效率：

1
{
2
    "If Command": {
3
        "prefix": ["if", "IF"],
4
        "body": [
5
            "if ${1:variable} ${2|==,!=,>,<,>=,<=|} ${3:value} ${4:LABEL_NAME}"
6
        ],
7
        "description": "Conditional jump"
8
    },
9
    "Say Command": {
10
        "prefix": "say",
11
        "body": [
12
            "say ${1:text} ${2:0.5} ${3|white,black,blue,green,red,yellow|}"
13
        ],
14
        "description": "Display text with typing effect"
15
    }
16
}

展开收起

特性：

prefix: 触发补全的文本
body: 插入的代码，支持占位符${n:default}
选择列表：${1|option1,option2|}
变量：${TM_FILENAME}等内置变量

第五步：本地测试#

启动调试#

在VSCode中打开扩展项目
按 F5 启动扩展开发主机
在新窗口中创建测试文件
验证语法高亮和代码片段

常见问题调试#

问题1：语法高亮不工作

检查.tmLanguage.json格式
验证正则表达式是否正确
检查文件扩展名关联

问题2：代码片段不出现

检查snippets/*.json文件格式
确认snippet的language字段正确
重启扩展主机

问题3：扩展无法激活

检查package.json中的activationEvents
查看”输出”面板的”扩展主机”日志

第六步：高级功能#

1. 添加命令和配置#

1
{
2
    "contributes": {
3
        "commands": [{
4
            "command": "mylang.formatDocument",
5
            "title": "Format MyLang Document"
6
        }],
7
        "configuration": {
8
            "title": "My Language",
9
            "properties": {
10
                "mylang.enableSyntaxHighlighting": {
11
                    "type": "boolean",
12
                    "default": true,
13
                    "description": "Enable syntax highlighting"
14
                }
15
            }
16
        }
17
    },
18
    "activationEvents": [
19
        "onLanguage:mylang",
20
        "onCommand:mylang.formatDocument"
21
    ]
22
}

展开收起

2. 创建语言服务器（可选）#

对于复杂的语言功能（代码补全、诊断、跳转定义），可以考虑实现Language Server：

1
// 创建Language Server
2
import * as vscode from 'vscode';
3
import * as lsp from 'vscode-languageclient';
4

5
export function activate(context: vscode.ExtensionContext) {
6
    const serverOptions: lsp.ServerOptions = {
7
        command: 'node',
8
        args: [context.asAbsolutePath('server/server.js')]
9
    };
10

11
    const clientOptions: lsp.LanguageClientOptions = {
12
        documentSelector: [{ scheme: 'file', language: 'mylang' }]
13
    };
14

15
    const client = new lsp.LanguageClient(
16
        'mylangServer',
17
        'My Language Server',
18
        serverOptions,
19
        clientOptions
20
    );
21

22
    client.start();
23
}

展开收起

第七步：打包和发布#

1. 安装打包工具#

Terminal window

1
npm install -g @vscode/vsce

2. 准备发布#

Terminal window

1
# 更新版本号
2
# 完善README.md
3
# 添加LICENSE
4
# 更新CHANGELOG.md

3. 打包#

Terminal window

1
vsce package
2
# 生成: my-language-support-1.0.0.vsix

4. 发布到市场#

方法A：直接发布

Terminal window

1
vsce publish
2
# 需要发布者令牌

方法B：手动上传

访问 VS Code Marketplace
点击”上传扩展”
选择生成的.vsix文件

第八步：持续维护#

监控反馈#

关注GitHub Issues
查看市场评价
收集用户需求

版本更新流程#

修改代码
更新版本号
更新CHANGELOG
测试
打包
发布

最佳实践#

渐进增强：先实现语法高亮，再逐步添加高级功能
测试驱动：为每个功能创建测试用例
文档完善：清晰的README和注释
性能优化：避免复杂的正则表达式
向后兼容：谨慎修改现有功能

实战经验分享#

踩过的坑#

正则表达式性能问题

1
// 错误：过于复杂的正则
2
"match": "\\b(say|wait|show|end|set|random|jump|if|choose|endname|SAY|WAIT|SHOW|END|SET|RANDOM|JUMP|IF|CHOOSE|ENDNAME)\\b"
3

4
// 优化：使用忽略大小写标志
5
"match": "(?i)\\b(say|wait|show|end|set|random|jump|if|choose|endname)\\b"

作用域冲突

1
// 变量引用内部的文本不应该被当作命令高亮
2
// 错误：${say} 中的 "say" 被高亮为命令
3
// 解决：在命令匹配中使用负向零宽断言
4
"match": "(?\\$\\{)\\b(say|wait|set)\\b(?!\\})"

效率技巧#

使用开发工具：
- TextMate Grammar Tester
- Scope Inspector

模板化开发：

1
// 自动生成代码片段的脚本
2
const commands = [
3
    { name: 'say', desc: 'Display text' },
4
    { name: 'set', desc: 'Set variable' }
5
];
6

7
const snippets = {};
8
commands.forEach(cmd => {
9
    snippets[cmd.name] = {
10
        prefix: cmd.name,
11
        body: [`${cmd.name} \${1:placeholder}`],
12
        description: cmd.desc
13
    };
14
});

测试用例：创建测试文件覆盖所有语法特性：

1
test-cases.mylang
2
├── 注释测试
3
├── 命令测试
4
├── 变量测试
5
└── 边界情况测试

成果展示#

完成扩展后，我的PGNCode开发体验得到了极大改善：

之前：

纯文本编辑
需要查手册
运行时才发现错误

之后：

彩色语法高亮
智能代码补全
实时错误提示
开发效率提升300%（哈哈）

资源推荐#

官方文档：VSCode Extension API
示例项目：VSCode Extension Samples
语法参考：TextMate Language Grammars
正则测试：Regex101

结语#

为自己的脚本语言开发VSCode扩展是一项很有价值的工作。它不仅提升了开发体验，也让你的语言看起来更加”专业”。整个过程虽然有些技术细节需要处理，但收获的成就感是巨大的。

关键点回顾：

从简单的语法高亮开始
逐步添加代码片段、配置等高级功能
充分测试，特别关注边界情况
文档完善，便于他人使用
持续维护，响应用户反馈

希望这篇文章能帮助你也为自己的语言创建出色的开发工具。

如何将你的Fuwari博客部署到Codeberg Pages (Forgejo Actions版)

2025-12-28T00:00:00.000Z

Codeberg Pages 是 Codeberg 官方提供的一个静态网站托管平台，类似于 Github Pages.

今天我们就要将Fuwari博客部署到Codeberg Pages , 使用 Forgejo Actions。

首先，在仓库中点击设置，点击仓库功能 / 概览，打开 Actions，保存设置。

接下来，回到仓库，在仓库根目录新建.forgejo/workflows文件夹.

在文件夹中添加 astro.yml 文件，内容如下：

1
name: Deploy Astro site to Pages
2

3
on:
4
  # Runs on pushes targeting the default branch
5
  push:
6
    branches:
7
      # If you want to build from a different branch, change it here.
8
      - main
9
  # Allows you to run this workflow manually from the Actions tab
10
  workflow_dispatch:
11

12
jobs:
13
  build:
14
    # You can find the list of available runners on https://codeberg.org/actions/meta, or run one yourself.
15
    runs-on: codeberg-medium-lazy
16
    steps:
17
      - name: Clone the repository
18
        uses: https://code.forgejo.org/actions/checkout@v4
19
        with:
20
          submodules: recursive
21
          fetch-depth: 0
22
      - name: check .domains files
23
        run: |
24
          git ls-files public/.domains
25
          ls -la public/
26
          ls -la public/.domains || echo ".domains not found"
27
      - name: Setup pnpm
28
        uses: pnpm/action-setup@v2
29
        with:
30
          version: 10
31
      - name: Setup Node.js
32
        uses: https://code.forgejo.org/actions/setup-node@v4
33
        with:
34
          node-version: 22
35
          cache: 'pnpm'
36
      - name: Install dependencies
37
        run: |
38
          pnpm install
39
          pnpm install @astrojs/sitemap
40
      - name: Build Astro site
41
        run: pnpm run build
42

43
      - name: Upload generated files
44
        uses: https://code.forgejo.org/actions/upload-artifact@v3
45
        with:
46
          name: Generated files
47
          path: dist/
48
          include-hidden-files: true
49

50
  deploy:
51
    needs: [ build ]
52
    runs-on: codeberg-tiny-lazy
53
    steps:
54
      - name: Clone the repository
55
        uses: https://code.forgejo.org/actions/checkout@v4
56
        with:
57
          submodules: recursive
58
          fetch-depth: 0
59

60
      - name: Checkout the target branch and clean it up
61
        run: |
62
          git checkout pages || git switch --orphan pages
63
          rm -Rfv $(ls -A | egrep -v '^(\.git|LICENSE)$')
64

65
      - name: Download generated files
66
        uses: https://code.forgejo.org/actions/download-artifact@v3
67
        with:
68
          name: Generated files
69

70
      - name: Publish the website
71
        run: |
72
          git config user.email codeberg-ci
73
          git config user.name "Codeberg CI"
74
          echo "=== Files being committed ==="
75
          ls -la
76
          git add .
77
          git commit --allow-empty --message "Codeberg build for ${GITHUB_SHA}"
78
          git push origin pages

展开收起

然后，就可以愉快的在Codeberg Pages上部署Fuwari博客了！

FreeDomainOne 域名注册教程

2025-11-14T00:00:00.000Z

今天推荐的是 FreeDomainOne 的免费域名，他们提供了publicvm.com,run.place,linkpc.net和work.gd后缀的域名.

首先，进入他们的官网：https://freedomain.one/;

接下来，注册一个账户,并点击发过来的验证邮件里的链接;

然后，回到他们的官网，输入你想要的域名前缀并选择域名后缀，完成后点击Check Availability,检查域名是否可用；

如果可用,点击Claim This Name >>按钮,进入付款页面;

进入付款页面后,保持默认设置,点击SUBMIT >>按钮,注册完成.注意,要记住 Free renew after 后面的日期,以后有用.

注意：注册的域名必须在 Free renew after 后面的日期以后一个月内续期，否则域名会被删除#

教程至此结束.

补充：推荐使用https://www.emailtick.com/ 的临时邮箱注册,因为当你输错用户名和密码时，这个网站会把使用这个用户名的用户注册时用的邮箱直接显示出来,有安全风险.

osfc.org.cn && osfs.top域名注册教程

2025-11-14T00:00:00.000Z

如题，今天讲的是这两个域名的注册教程，暂时都无法托管到Cloudflare.
官网地址：https://registry.osfc.org.cn
我的邀请链接：https://registry.osfc.org.cn/register?invite=286
推荐使用邀请链接，因为那样你可以拿到20Points奖励
第一步，使用上面两个链接的其中一个，进入官网.
第二步，在右上角找到Sign up按钮，并点击，注册一个账号.
第三步，进入仪表板，点+号添加一个域名.
注意，创建一个域名需花费50Points,而注册时会送100Points，也就是可以注册2个域名
这个域名无法修改NS服务器（也许吧），暂时不推荐用作主力域名，只推荐玩一玩.

ZoneABC域名注册教程

2025-11-14T00:00:00.000Z

如题，今天讲一下ZoneABC域名的注册教程.

ZoneABC提供了webn.cc,zabc.net,sylu.cc,sylu.net,acg.rest,vvvv.ee和ctrl.li后缀的域名.

官网：https://zoneabc.net/

邀请链接：https://zoneabc.net/register?invite=cd9373abf598410ea2294f47a1db8d6d

第一步，点击上面两个链接中的其中一个，进入注册界面，推荐使用邀请链接注册，那样你可以获得额外的10积分.

第二步，注册好账户后，进入面板，注册一个域名.注意，一些前缀比较短的域名会需要积分，经过测试，前缀长度为7及以上的域名无需积分，如果有错误请指正

这个域名比osfc.org.cn良心一点，但DNS记录只可添加20条，适合做备用.

PublicFreeSuffix域名申请教程

2025-10-01T00:00:00.000Z

如题，此帖讲的是PublicFreeSuffix免费域名的申请教程.

首先，打开他们的GitHub仓库地址： https://github.com/PublicFreeSuffix/PublicFreeSuffix

他们提供了pfsdns.org,nastu.net,tun.re,6ti.net和no.kg后缀的免费域名,都无法托管到Cloudflare.

注册域名步骤：

第一步，fork他们的GitHub仓库.

第二步，打开你fork的仓库，在whois文件夹里新建一个json文件，文件名为你想注册的域名.no.kg.json.

这里使用no.kg的域名后缀作为演示，如果想使用其他域名后缀，请把no.kg改为你想使用的域名后缀.

json文件格式：

1
{
2
  "registrant": "一个可以发邮件的邮箱",
3
  "domain": "域名名字",
4
  "sld": "域名后缀",
5
  "nameservers": [
6
    "NS服务器1",
7
    "NS服务器2",
8
    "NS服务器3",
9
    "NS服务器4"
10
  ],
11
  "agree_to_agreements": {
12
    "registration_and_use_agreement": true,
13
    "acceptable_use_policy": true,
14
    "privacy_policy": true
15
  }
16
}

展开收起

第三步，在你fork的仓库里把这个提交创建为一个新分支，名字为域名全称-request-1.

注意：第几次更改就填数字几

第四步，向官方仓库发起一个拉取请求，标题为Registration/Update/Remove: 域名名字.域名后缀

内容这样填写：

1
> All items should be completed and confirmed to trigger the automatic merge workflow.
2

3
## Operation Type
4
- [x] Registration, Register a new domain name.
5
- [ ] Update, Update NS information or registrant email for an existing domain.
6
- [ ] Remove, Cancel my domain name.
7

8
## Domain
9
- [x] 域名名字.域名后缀
10

11
## Confirmation Items
12
- [x] I confirm that I will deploy the website content for this domain name and put it into use within 30 days instead of hoarding and occupying resources.
13
- [x] I confirm that the title of this Pull Request and the submitted files are in the standard format; otherwise, it will not be processed automatically.
14
- [x] I confirmed that the name in the whois file meets the standards.
15
- [x] I confirm that the domain name is at least 3 characters.
16
- [x] I confirm that I have read and understood the [Acceptable Use Policy](https://github.com/PublicFreeSuffix/PublicFreeSuffix/blob/main/agreements/acceptable-use-policy.md).
17
- [x] I confirm that I have read and agree to the [Privacy Policy](https://github.com/PublicFreeSuffix/PublicFreeSuffix/blob/main/agreements/privacy-policy.md).
18
- [x] I confirm that I have read and agree to the [Registration And Use Agreement](https://github.com/PublicFreeSuffix/PublicFreeSuffix/blob/main/agreements/registration-and-use-agreement-sokg.md).
19
- [x] I confirm that the domain does not contain any reserved terms from the [Reserved Words List](https://github.com/PublicFreeSuffix/PublicFreeSuffix/blob/main/reserved_words.txt).
20
- [x] I confirm that I will complete the registrant's email verification according to [ARAE Instructions](https://github.com/PublicFreeSuffix/PublicFreeSuffix/blob/main/AUTHORIZATION.md) to complete the merger.

展开收起

如果是更新或删除，就把代码中Registration前面中括号里的x放在Update/Remove前面的中括号里.

第五步：当拉取请求状态为validation-passed后，用你刚才在json文件中填写的邮箱向 pr-authorization@publicfreesuffix.org发送一封邮件，标题为APPROVE_PFS_PR_你的拉取请求ID，内容随便写.

第六步，到你的DNS提供商里添加域名.

至此申请结束.

隐私政策

1999-01-01T03:20:15.000Z

All Cookies#

Strictly necessary cookies（必要的cookies）#

Umami：收集站点的基本访问情况，并对外显示浏览量，由本站直接提供
Giscus：提供评论功能，由 Github 提供

Functionality cookies（功能性cookies）#

Tracking cookies（追蹤cookies）#

latest update: 2026/09/05

Firefly 代码块示例

1970-01-03T00:00:00.000Z

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}span> : children)}
12
button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}span> : children)}
15
button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Tab 代码块#

由 rehype-code-group 提供，语法与 VitePress 代码组一致：用 ::: code-group labels=[...] 包裹多个代码块，即可合并成一组标签页。

Note

labels=[...] 中的标签按顺序对应组内的代码块，用英文逗号分隔；::: 与 code-group 之间的空格不能省略。

基本用法#

1
::: code-group labels=[code.js, code.py, code.html]
2

3
```js
4
export function greet(name) {
5
  return `Hello, ${name}!`;
6
}
7
```
8

9
```py
10
def greet(name):
11
    return f"Hello, {name}!"
12
```
13

14
```html
15
<p>Hello, world!p>
16
```
17

18
:::

展开收起

渲染效果：

code.jscode.pycode.html

1
export function greet(name) {
2
  return `Hello, ${name}!`;
3
}

1
def greet(name):
2
    return f"Hello, {name}!"

1
<p>Hello, world!p>

标签中使用 Emoji#

标签支持 emoji 短代码，构建时会自动转换成 emoji：

1
::: code-group labels=[:package: npm, :package: pnpm, :yarn: yarn]

📦 npm📦 pnpm🧶 yarn

Terminal window

1
npm create astro@latest

Terminal window

1
pnpm create astro@latest

Terminal window

1
yarn create astro

与其他代码块特性组合#

组内仍是普通的 Expressive Code 代码块，标题、行号、行标记、折叠、终端框架等特性都可以照常使用。

配置文件终端折叠

astro.config.mjs

1
export default {
2
  theme: "firefly",
3
  codeGroup: true,
4
};

部署

1
pnpm build && pnpm preview


3 collapsed lines
1
// 这三行默认折叠
2
import { a } from "a";
3
import { b } from "b";
4

5
console.log(a, b);

不止是代码块#

标签页内可以放任意内容，例如文字、列表或图片：

说明列表

这是一段普通的段落内容。

列表项一
列表项二

Tip

标签栏在构建期生成，默认展开第一项；支持鼠标点击与键盘 ← / → / Home / End 切换。

在提醒框内使用（MDX 组件）#

::: code-group 和 ::: tip 等 Docusaurus 风格提醒框都使用 ::: 容器语法，而 micromark-directive 规定父子容器的冒号数必须不同，因此 ::: code-group 无法嵌套在 ::: tip 等提醒框内（整块会失效）。

这种情况改用 MDX 组件 TabGroup：MDX 组件不经过 ::: 指令解析，在提醒框内外都能正常使用，也方便日后扩展更多 UI 组件。把文章后缀改为 .mdx，从统一入口 @/components/firefly-mdx 引入（可一次引入多个组件）：

1
import { TabGroup } from "@/components/firefly-mdx";
2

3
:::tip
4

5
<TabGroup labels={["test.js", "test.py"]} client:load>
6
  ```js
7
  console.log(1)
8
  ```
9

10
  ```py
11
  print("hello world")
12
  ```
13
TabGroup>
14

15
:::

展开收起

Tip

labels 数组给每个代码块声明标签，顺序一一对应
组件用 client:load 激活标签切换

Firefly 布局系统详解

1970-01-03T00:00:00.000Z

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

文章详情页显示哪几侧，由**各组件的 showOnPostPage（以及 hideOnNonPostPage）**决定：某一侧在当前页型下没有任何可见组件时，该列会自动收起，把空间让给内容栏。

如果想在文章页同时显示双侧边栏，把 position 设为 "both"，并给两侧组件配好 showOnPostPage 即可。

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图，可配置在左侧或右侧
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

封面位置#

列表模式的封面图默认在卡片右侧，可以通过 coverPosition 改到左侧。改到左侧后，标题前的主题色竖线会自动隐藏（它是贴着卡片左边缘的设计），腾出的间距留给正文。

网格模式的封面固定在卡片顶部，不受这项配置影响。

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list",    // 列表模式
4
    coverPosition: "right", // 封面图位置："right" 右侧，"left" 左侧
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    grid: {
5
      masonry: true,      // 开启瀑布流
6
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
7
    },
8
  },
9
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

Firefly Wiki Link 内部链接示例

1970-01-03T00:00:00.000Z

Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。

文章链接卡片#

[[slug]] 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：

1
[[firefly]]
2

3
[[guide/index]]
4

5
[[markdown-extended]]

Firefly 一款清新美观的 Astro 博客主题模板

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

1970-01-02文章示例#Markdown#Firefly#博客#主题#模板

Firefly 简单使用指南

如何使用 Firefly 博客模板。

1970-01-02博客指南#Firefly#博客#Markdown#指南

Markdown 扩展功能

了解 Firefly 中的 Markdown 功能

1970-01-01文章示例#演示#示例#Markdown#Firefly

行内链接#

[[slug]] 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题

1
请参阅 [[firefly]] 了解主题特性。

请参阅 Firefly 一款清新美观的 Astro 博客主题模板了解主题特性。

自定义显示标题#

在 | 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：

1
请参阅 [[firefly|主题介绍]] 了解主题特性。
2

3
[[firefly|Firefly 主题介绍]]

请参阅主题介绍了解主题特性。

Firefly 主题介绍

1970-01-02文章示例#Markdown#Firefly#博客#主题#模板

一个例外：如果 | 后的文字只是把链接目标又抄了一遍（[[guide/index|index]]），会被当作无效别名忽略，仍然显示文章标题。Obsidian 在插入的链接时会自动补上这样的别名，避免笔记里显示一长串路径，这个例外就是为它准备的。

链接目标的三种写法#

用 Obsidian 管理文章时，把 src/content/posts 目录本身作为 Obsidian 仓库（vault）打开。下文提到的「仓库根目录」都指这个目录，它正好也是 Firefly 解析链接路径的起点。

链接目标按以下顺序匹配：

写法	示例	在 Obsidian 中
frontmatter 的 `slug`	`[[firefly-wiki-link]]`	✗ 不支持
文件路径（相对仓库根目录）	`[[guide/firefly-layout-system]]`	✓ 需改设置（推荐）
裸文件名（仓库内唯一时）	`[[firefly-layout-system]]`	✓ 默认即是

第一种：slug#

slug 写法在 Obsidian 中不支持，slug 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 slug，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。

第二种：文件路径（推荐）#

文件路径写法需要改 Obsidian 设置，在 设置 → 文件与链接 → 链接 → 内部链接类型 中选择基于仓库根目录的绝对路径，Obsidian 插入的链接才会带上目录：

1
[[guide/firefly-layout-system|firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

1970-01-03博客指南#Firefly#布局#博客#指南

因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。

上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。

内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。

第三种：裸文件名#

「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：

1
[[firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

1970-01-03博客指南#Firefly#布局#博客#指南

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸

链接到其他文章的标题#

在文章 slug 后添加 #标题。带标题锚点的链接始终渲染为普通链接：

查看代码块语法高亮

Firefly 布局系统详解#相关链接

1
[[code-examples#语法高亮|查看代码块语法高亮]]
2

3
[[guide/firefly-layout-system#相关链接|firefly-layout-system]]

标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。

链接到本页标题#

省略文章 slug，只填写标题即可链接到当前文章：

跳转到本页目标

1
[[#本页目标|跳转到本页目标]]

本页目标#

这是本页 Wiki Link 指向的标题。

不支持附件嵌入#

附件嵌入语法目前不会被转换，会按原文显示：

![[image.png]]

行内代码和代码块中的 [[firefly]] 也不会被转换。

Firefly 文章加密

1970-01-02T00:00:00.000Z

这是一篇密码保护的示例文章，用于演示文章加密功能。

KaTeX 数学公式示例

1970-01-02T00:00:00.000Z

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)

极限与求和 (Limits and Sums)#

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2lim⁡x→0sin⁡xx=1\lim_{x \to 0} \frac{\sin x}{x} = 1x→0limxsinx=1

麦克斯韦方程组 (Maxwell’s Equations)#

∇⋅E=ρε0∇⋅B=0∇×E=−∂B∂t∇×B=μ0J+μ0ε0∂E∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

MDX 格式文章示例

1970-01-02T00:00:00.000Z

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

Firefly 内置的专属 MDX UI 组件#

这里列出 Firefly 内置的 MDX UI 组件，方便在 MDX 文章中直接使用。

Tab分组：`TabGroup`#

用于创建可切换的标签页，方便在文章中展示不同语言或不同版本的代码等等。

1
<TabGroup labels={["test.js", "test.py"]} client:load>
2
  ```js
3
  console.log(1)
4
  ```
5

6
  ```py
7
  print("hello world")
8
  ```
9
TabGroup>

test.jstest.py

1
console.log(1)

1
print("hello world")

时间线：`Timeline` / `TimelineItem`#

属性	必填	说明
`date`	否	时间标签，如 “2024-03-10”
`title`	否	条目标题
`type`	否	节点颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，显示在圆点内：star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit
正文	否	标签内的内容，支持 Markdown

1
<Timeline>
2
  <TimelineItem date="2026-08-16" title="新版本发布" icon="rocket">
3
    发布了全新版本，带来以下更新：
4

5
    - 新增时间线组件
6
    - 改进暗色主题
7

8
    正文里支持 **Markdown** 内容。
9
  TimelineItem>
10
  <TimelineItem date="2025-11-02" title="站点上线" type="tip" icon="flag">
11
    欢迎来到我的博客。
12
  TimelineItem>
13
  <TimelineItem date="2025-06-15" title="项目立项" type="note">
14
    开始规划 Firefly 主题。
15
  TimelineItem>
16
Timeline>

展开收起

2026-08-16
新版本发布
发布了全新版本，带来以下更新：
- 新增时间线组件
- 改进暗色主题
正文里支持 Markdown 内容。
2025-11-02
站点上线
欢迎来到我的博客。
2025-06-15
项目立项
开始规划 Firefly 主题。

步骤条：`Steps` / `StepItem`#

编号步骤条，适合教程、部署流程。编号自动生成，无需手动传序号。

属性	必填	说明
`title`	否	步骤标题
`type`	否	编号圆颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，有图标时显示图标而非数字（star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit）
正文	否	标签内的内容，支持 Markdown

1
<Steps>
2
  <StepItem title="安装依赖">
3
    运行 `pnpm install`。
4
  StepItem>
5
  <StepItem title="启动开发服务器" type="tip" icon="rocket">
6
    运行 `pnpm dev`，打开 `localhost:4321`。
7
  StepItem>
8
  <StepItem title="编写文章">
9
    在 `src/content/posts/` 新建 `.mdx` 文章。
10
  StepItem>
11
Steps>

安装依赖
运行 pnpm install。
启动开发服务器
运行 pnpm dev，打开 localhost:4321。
编写文章
在 src/content/posts/ 新建 .mdx 文章。

徽章：`Badge`#

内联彩色小徽章，可嵌在段落或标题里。

属性	必填	说明
`type`	否	default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）

1
<Badge type="tip">提示Badge> <Badge type="warning">注意Badge>

新功能提示笔记重要注意危险

更多信息，请查看 MDX 文档

Markdown 扩展功能

1970-01-01T00:00:00.000Z

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

🍀Firefly, fresh and aesthetic Astro blog theme template.

—

MIT

Astro

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

1970-01-01T00:00:00.000Z

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、ER 图、类图、状态图、XY 图、甘特图、思维导图等。

Mermaid 图表由 Merman 实现。Firefly 在 Astro 构建阶段生成亮色和深色两套静态 SVG，无需在浏览器中加载 Mermaid 渲染运行时。可以前往 Merman Playground 实时编辑语法并预览渲染结果。

流程图示例#

流程图非常适合表示流程或算法步骤。

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

时序图示例#

时序图显示对象之间随时间的交互。

数据库服务器网页应用用户数据库服务器网页应用用户alt[认证成功][认证失败]提交登录请求发送认证请求查询用户凭据返回用户数据返回认证结果显示欢迎页面请求用户数据获取用户偏好返回偏好设置返回用户数据加载个性化界面显示错误消息提示重新输入

ER 图示例#

ER 图（实体关系图）非常适合表示数据库结构。

writes

posts

has

belongs to

USER

int

string

username

string

datetime

created_at

ARTICLE

int

string

title

text

content

datetime

published

int

author_id

COMMENT

int

text

content

datetime

created_at

int

user_id

int

article_id

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

写作

发表

拥有

属于

User

+String username

+String password

+String email

+Boolean active

+login()

+logout()

+updateProfile()

Article

+String title

+String content

+Date publishDate

+Boolean published

+publish()

+edit()

+delete()

Comment

+String content

+Date commentDate

+addComment()

+deleteComment()

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

XY 图示例#

XY 图表非常适合展示趋势和对比数据。

月度访问量趋势1月2月3月4月5月6月5000450040003500300025002000150010005000访问量

饼图示例#

饼图适合直观展示各部分在整体中的占比。

45%30%15%10%内容类型占比技术文章 [45]项目记录 [30]生活随笔 [15]其他 [10]

甘特图示例#

甘特图可以按时间轴展示项目阶段、任务依赖和当前进度。

07/0107/0307/0507/0707/0907/1107/1307/1507/17需求整理视觉设计功能实现内容迁移构建检查正式上线准备开发发布博客版本发布计划

思维导图示例#

思维导图适合梳理主题层级和知识结构。

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

时间线示例#

时间线用于按年份或阶段呈现项目的重要事件。

2024建立博客完成基础主题2025加入搜索与图库完善内容系统2026升级 Astro 7使用 Merman 渲染图表Firefly 演进时间线

用户旅程图示例#

用户旅程图能够描述用户在不同阶段的行为和体验评分。

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

Git 图示例#

Git 图可以清晰展示分支、提交和合并历史。

mainfeatureinitadd-diagramspolish-themesmerge-featurerelease

看板示例#

看板适合展示任务在不同工作阶段之间的分布。

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

Sankey 图示例#

Sankey 图通过连线宽度展示流量在不同节点之间的流向。

Home 1650Post list 1200Search 450Post detail 1220Related posts 260External shares 180

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了流程图、时序图、ER 图、类图、状态图、XY 图、饼图、甘特图、思维导图、时间线、用户旅程图、Git 图、看板和 Sankey 图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。图表会在构建时自动渲染为 SVG，无需客户端 JavaScript 加载。

可以前往 Merman Playground 尝试更多语法，再将图表代码粘贴到文章中。

Markdown PlantUML 图表

1970-01-01T00:00:00.000Z

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

Bob: Hello Bob --> Alice: Hi @enduml" src="https://www.plantuml.com/plantuml/svg/SoWkIImgAStDuNBCoKnELT2rKt3AJx9Iy4ZDoSddSifFKj3LjLC0orafU6HoEQJcfPJcvW00" loading="lazy" />

活动图示例#

状态图示例#

草稿草稿 --> 待审核 : 提交待审核 --> 草稿 : 驳回待审核 --> 已发布 : 审核通过已发布 --> 已归档 : 到期归档已发布 --> 草稿 : 撤回修改 state 已发布 { [*] --> 可见可见 --> 隐藏 : 手动隐藏隐藏 --> 可见 : 恢复展示 } 已归档 --> [*] @enduml" src="https://www.plantuml.com/plantuml/svg/SoWkIImgAStDuOhMYbNGrRLJUD7R-Np5VYuk20qMUhglzUcwXSyMx52mKdZMF-79hYLS22647WKhXPShDp-TFGzDzkdsJK_x9pxTqQnWfG0HVjamwyN-TYw414pPtadF5Yu6AUlOy6pEV0WNJHdShcUJbZoTFU_9_dNFfkpauYekIIn9HRAgceiJvgEd_UjVB6_aueJGOA6NioQycDuFCgIp-sdN2WYNYnCgZD04Kj6uwEcItgSRfpvViekhbeiBuKoGicYjM2w7rBoKqjmS0000" loading="lazy" />

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

> -- username : varchar email : varchar created_at : datetime } entity Post { *id : uuid <> -- author_id : uuid <> title : varchar content : " src="https://www.plantuml.com/plantuml/svg/VP2x2W9134NhoLUa5lO71X51iB6niPRiJc07vY6JZ0_KVvTTKHGVRKwIavkvA1MjCG0dzNh2ZN31CvY9TsYnLkzmEbslPZCmJGEc2fT4aT7YdahNKm73aNnuBNI5ITbjIT6Y8sNraU4A3ySwY_vnKDK-b-qhN8vGlOOtSvUJSXeioaS5iwjjyDB_KIzoZCF4R_ikYtvn3y6_bDliJa_zpzpZKo-NfiddUtYBX-ALvOqyRhDuNoGmzdxGdWJcd5oDuGO0" loading="lazy" />

时序图示例（登录与刷新令牌）#

前端页面 : 输入账号密码并提交前端页面 -> 网关接口 : POST /login 网关接口 -> 认证服务 : " src="https://www.plantuml.com/plantuml/svg/bP3BJi9068NtynJ_thGIbrqqk7GbyHANPYYZ4A4bxVG1M70D5GrAn42u2CPee2HUY0BwCioql8L1t0ma1jVVEJFVVu8MnIQr4t64RMheTY9CJ8GrQfXmQ14Ji0NUrGFF3L4IcpIcnP9Oft14mdF2yextvCvQhxDwM-3RePsVvkIIfP_vUPULxaHkq-WyuFSxlflYDOSLMYY2AGvZYy0UYSIiEPwERtstxetBh7U3qC8395Nu5nJmFyiitVLVxbbfoDoCrqonzpTUkfX-T90GbLH12HG8xUuVm6RSE8tfI42IAiY10hpPcZqMMRR7dJuIcAGAfg00orHPkWicEJ695JscnXdHbpghBbZJY6Kjmh2nL1RbLZVO2WJ0guxOv9hdBbYXWP0io-AJ_bUMrneWop9QRvPVW_M6-VFObO7yIPyxxNyEn2i3uQArHk6LmNJKyV9552Hwn4x4lm40" loading="lazy" />

C4 风格容器图示例#

Markdown 教程

1970-01-01T00:00:00.000Z

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：

，

使用等号 (=) 表示

、使用短横线 (-) 表示

，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：

，

在行首使用 1-6 个井号 (#)，对应

至

。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。
代码：
1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.
预览：
This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。
代码：
1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.
预览：
This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
引用可以嵌套（引用中的引用），通过增加 > 层级实现。
代码：
1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.
预览：
This is the first level of quoting.
This is nested blockquote.
Back to the first level.
引用内可包含其他 Markdown 元素，包括标题、列表与代码块。
代码：
1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");
预览：
This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3

预览：



A list item with a code block:
1

`嵌套列表#`

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：


A

A1
A2


B
C

`代码块#`

HTML 标签：


将代码块中的每行缩进至少4 个空格或1 个制表符。
代码：
1
This is a normal paragraph:
2

3
    This is a code block.
预览：
This is a normal paragraph:
1
This is a code block.
代码块会一直持续，直到遇到未缩进的行（或文末）。
在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。
代码：
1
    
2
        © 2004 Foo Corporation
3
    
预览：
1
2
    © 2004 Foo Corporation
3
下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。
围栏代码块#
使用成对的反引号围起来（如下所示），就不需要四空格缩进了。
代码：
1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```
预览：
Here’s an example:
1
function test() {
2
  console.log("notice the blank line before this function?");
3
}
语法高亮#
在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。
代码：
1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```
预览：
1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

`分割线（水平线）#`

HTML 标签：


一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。
代码：
1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___
预览：

`表格#`

HTML 标签：

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

`内联元素#`

`链接#`

HTML 标签：

Markdown 支持两种链接样式：行内链接与引用式链接。

`行内链接#`

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

`引用式链接#`

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：


方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]:   "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

`强调#`

HTML 标签：，

Markdown 使用星号 (*) 或下划线 (_) 表示强调。一个分隔符对应；两个分隔符对应。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

`行内代码#`

HTML 标签：

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

`图片#`

HTML 标签：

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

`行内图片#`

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：


一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

`引用式图片#`

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

`删除线#`

HTML 标签：

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

`杂项#`

`自动链接#`

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

`反斜杠转义#`

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

`内联 HTML#`

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
4
    
5
        
6
    
7
Foo
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
**Work**
2

3
4
    **No Work**
5

预览：

Work


  **No Work**

***



在文章中嵌入视频
1970-01-01T00:00:00.000Z
只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。
1
---
2
title: 在文章中嵌入视频
3
published: 2023-10-19
4
// ...
5
---
6

7

YouTube#
Bilibili#