3025 字
15 分钟
博客框架使用教程

图片来自网络,侵权请联系删除 T^T


写在前面的话

我平常自己写博客的频率还蛮低的,为了防止遗忘,第一篇就作为自己的备忘录吧 : )

框架使用教程#

本地框架安装及初始化#

  1. 安装
Terminal window
# npm
npm create fuwari@latest
# yarn
yarn create fuwari
# pnpm
pnpm create fuwari@latest
# bun
bun create fuwari@latest
# deno
deno run -A npm:create-fuwari@latest
  1. 通过配置文件 src/config.ts 自定义博客

⚙️ 文章 Frontmatter#

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
lang: jp # 仅当文章语言与 `config.ts` 中的网站语言不同时需要设置
---
AttributeDescription
title标题 — 文章的显示标题
published发布日期 — 文章的发布日期,格式建议使用 YYYY-MM-DD
description简介 — 首页或列表页显示的短描述
image封面图片路径
tags标签 — 一个字符串数组,用于对文章进行标签分类,例如 tags: ["JS","指南"]
category分类 — 文章的所属分类,例如 FrontendTools
draft草稿标记 — 如果为 true 则文章为草稿不会在站点中显示;发布时设为 false 或移除该字段。

关于图片路径

  1. http://https:// 开头:使用外部网络图片;
  2. / 开头:表示放在仓库的 /public 目录下;
  3. 既不以 / 也不以 http 开头:相对于该 Markdown 文件的位置。

文章文件结构#

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

🧞 指令#

下列指令均需要在项目根目录执行:

CommandAction
pnpm installpnpm add sharp安装依赖
pnpm devlocalhost:4321 启动本地开发服务器
pnpm build构建网站至 ./dist/
pnpm preview本地预览已构建的网站
pnpm new-post <filename>创建新文章
pnpm astro ...执行 astro add, astro check 等指令
pnpm astro --help显示 Astro CLI 帮助

Markdown 语法参考#

一、文本格式化#

标题#

使用 # 创建标题,支持 1-6 级:

# 一级标题
## 二级标题
### 三级标题

文本强调#

*斜体文本*_斜体文本_
**粗体文本**__粗体文本__
***粗斜体***___粗斜体___
~~删除线~~
`行内代码`

效果:
斜体文本斜体文本
粗体文本粗体文本
粗斜体粗斜体
删除线
行内代码

段落与换行#

段落之间用空行分隔,行末加两个空格可实现换行。

特殊字符与转义#

使用破折号、省略号等特殊字符,以及转义特殊符号:

em-dash(破折号):---
en-dash(短破折号):--
省略号:...
转义字符:\*不加粗\* \[不成为链接\] \`纯文本\`

效果:

使用破折号 --- 和短破折号 — 以及省略号 …

转义示例:*不加粗* [不成为链接] `纯文本`


二、列表#

无序列表#

- 列表项 1
- 列表项 2
- 嵌套项 2.1
- 嵌套项 2.2
- 列表项 3

效果:

  • 列表项 1
  • 列表项 2
    • 嵌套项 2.1
    • 嵌套项 2.2
  • 列表项 3

有序列表#

1. 第一项
2. 第二项
1. 嵌套项 2.1
2. 嵌套项 2.2
3. 第三项

效果:

  1. 第一项
  2. 第二项
    1. 嵌套项 2.1
    2. 嵌套项 2.2
  3. 第三项

定义列表#

术语
: 术语的定义说明
HTML
: 超文本标记语言
: 用于创建网页的标准标记语言

效果:

术语 : 术语的定义说明

HTML : 超文本标记语言 : 用于创建网页的标准标记语言


三、链接与引用#

链接#

[链接文本](https://example.com)
[带标题的链接](https://example.com "悬停显示的标题")
<https://example.com>

效果:
链接文本
带标题的链接
https://example.com

图片#

![图片描述](图片路径)
![带标题的图片](图片路径 "图片标题")

引用块#

> 这是一个引用块
> 可以跨越多行
>
> 引用块内也可以使用 **Markdown** 格式

效果:

这是一个引用块
可以跨越多行

引用块内也可以使用 Markdown 格式

脚注#

这是一段包含脚注的文字[^1]。
[^1]: 这是脚注的内容,会显示在页面底部。

效果:
这是一段包含脚注的文字1


四、代码#

行内代码#

使用反引号包裹代码:const code = 'inline'

缩进代码块#

使用 4 个空格或 1 个制表符缩进的代码块会被识别为代码:

原始代码:

// 缩进 4 个空格的代码
function demo() {
console.log('This is indented code')
}

效果:

// 缩进 4 个空格的代码
function demo() {
console.log('This is indented code')
}

提示: 大多数情况下建议使用 ``` 围栏式代码块,因为它更明确且易于维护。 支持渲染 ANSI 颜色和文本格式,通常用于模拟终端输出效果。

原始代码:

```ansi frame="terminal"
ANSI colors:
- Regular: \u001b[31mRed\u001b[0m \u001b[32mGreen\u001b[0m \u001b[33mYellow\u001b[0m
- Bold: \u001b[1;31mBold Red\u001b[0m \u001b[1;32mBold Green\u001b[0m
- Underline: \u001b[4;35mUnderline Magenta\u001b[0m
```

效果:

Terminal window
ANSI colors:
- Regular: \u001b[31mRed\u001b[0m \u001b[32mGreen\u001b[0m \u001b[33mYellow\u001b[0m
- Bold: \u001b[1;31mBold Red\u001b[0m \u001b[1;32mBold Green\u001b[0m
- Underline: \u001b[4;35mUnderline Magenta\u001b[0m

编辑器与终端样式#

为代码块添加标题或指定为终端/编辑器样式,增强可读性。

编辑器样式(带文件名):

原始代码:

```js title="src/main.js"
// 文件名会显示在代码块顶部
export function greet(name) {
console.log(`Hello, ${name}`);
}
```

效果:

src/main.js
// 文件名会显示在代码块顶部
export function greet(name) {
console.log(`Hello, ${name}`);
}

终端样式:

原始代码:

```bash frame="terminal" title="Terminal"
$ npm run build
Building project... Complete!
```

效果:

Terminal
$ npm run build
Building project... Complete!

无样式(纯代码):

原始代码:

```sh frame="none"
echo "No decorative frame"
```

效果:

echo "No decorative frame"

文本与行标记#

支持按行标记、范围标记与标签。

基础行标记:

原始代码:

```js {1,4,7-8}
// 第 1、4、7-8 行会被高亮标记
function example() {
console.log('line 1')
console.log('line 2')
console.log('line 3')
console.log('line 4')
// ...
}
```

效果:

// 第 1、4、7-8 行会被高亮标记
function example() {
console.log('line 1')
console.log('line 2')
console.log('line 3')
console.log('line 4')
// ...
}

删除、插入、修改标记:

原始代码:

```js title="line-markers.js" del={2} ins={3-4} {6}
function demo() {
console.log('this line is marked as deleted')
// This line and the next one are marked as inserted
console.log('this is the second inserted line')
return 'neutral line'
}
```

效果:

line-markers.js
function demo() {
console.log('this line is marked as deleted')
// This line and the next one are marked as inserted
console.log('this is the second inserted line')
return 'neutral line'
}

带标签的行标记:

原始代码:

```jsx {"1. Step One":5-6} {"2. Step Two":8-10} {"3. Step Three":12-15}
// step-by-step.jsx
const Component = () => {
// Step One: Setup
const [count, setCount] = useState(0);
// Step Two: Handler
const increment = () => setCount(count + 1);
// Step Three: Render
return <button onClick={increment}>{count}</button>;
};
```

效果:

step-by-step.jsx
const Component = () => {
// Step One: Setup
const [count, setCount] = useState(0);
// Step Two: Handler
const increment = () => setCount(count + 1);
// Step Three: Render
return <button onClick={increment}>{count}</button>;
};

差异对比(Diff)#

展示代码的新旧对比或变更。

原始代码:

```diff lang="js"
function greet() {
- console.log('old')
+ console.log('new')
return 'Hello'
}
```

效果:

function greet() {
console.log('old')
console.log('new')
return 'Hello'
}

使用 del 和 ins 属性:

原始代码:

```js del={1} ins={2}
- const deprecated = 'old API'
+ const modern = 'new API'
```

效果:

- const deprecated = 'old API'
+ const modern = 'new API'

行内文本标记#

在代码块中使用双引号标记特定的行内文本。

字符串标记:

原始代码:

```js "important"
function demo() {
// This important line will be highlighted
return 'important' + 'content';
}
```

效果:

function demo() {
// This important line will be highlighted
return 'important' + 'content';
}

正则表达式标记:

原始代码:

```ts /ye[sp]/
console.log('The words yes and yep will be marked.')
```

效果:

console.log('The words yes and yep will be marked.')

处理斜杠转义:

原始代码:

```sh /\/home\/user/
echo "Test" > /home/user/file.txt
```

效果:

Terminal window
echo "Test" > /home/user/file.txt

行号显示#

控制行号的显示和起始位置。

显示行号:

原始代码:

```js showLineNumbers
console.log('line 1')
console.log('line 2')
console.log('line 3')
```

效果:

console.log('line 1')
console.log('line 2')
console.log('line 3')

自定义起始行号:

原始代码:

```js showLineNumbers startLineNumber=5
// 从第 5 行开始编号
console.log('line 5')
console.log('line 6')
```

效果:

// 从第 5 行开始编号
console.log('line 5')
console.log('line 6')

自动换行控制#

控制长行是否自动换行。

启用自动换行(wrap=true):

原始代码:

```js wrap
// 长字符串会在显示时自动换行
const longString = '这是一个非常长的字符串,用来说明自动换行功能。当启用自动换行时,超出容器宽度的内容会自动折叠到下一行。';
```

效果:

// 长字符串会在显示时自动换行
const longString = '这是一个非常长的字符串,用来说明自动换行功能。当启用自动换行时,超出容器宽度的内容会自动折叠到下一行。';

禁用自动换行(wrap=false):

原始代码:

```js wrap=false
// 长字符串会超出容器并产生横向滚动条
const longString = '这是一个非常长的字符串。当禁用自动换行时,超出容器宽度的内容会保持在同一行,用户需要水平滚动才能看到完整内容。';
```

效果:

// 长字符串会超出容器并产生横向滚动条
const longString = '这是一个非常长的字符串。当禁用自动换行时,超出容器宽度的内容会保持在同一行,用户需要水平滚动才能看到完整内容。';

代码块折叠#

使用 collapse 属性使代码块可以折叠/展开,提高页面简洁性。

按行范围折叠:

原始代码:

```ts collapse={1..10}
// 前 10 行可以折叠
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import svelte from '@astrojs/svelte';
import expressiveCode from 'astro-expressive-code';
export default defineConfig({
integrations: [
tailwind(),
svelte(),
expressiveCode(),
],
// 其他配置...
});
```

效果:

// 前 10 行可以折叠
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import svelte from '@astrojs/svelte';
import expressiveCode from 'astro-expressive-code';
export default defineConfig({
integrations: [
tailwind(),
svelte(),
expressiveCode(),
],
// 其他配置...
});

按注释标记折叠:

原始代码:

```js collapse={6..15}
function processData(items) {
const results = [];
// 核心逻辑
items.forEach(item => {
// 这些行可以被折叠
const processed = item
.trim()
.toLowerCase()
.split('-')
.map(part => part.charAt(0).toUpperCase() + part.slice(1))
.join('');
results.push(processed);
});
return results;
}
```

效果:

function processData(items) {
const results = [];
// 核心逻辑
items.forEach(item => {
// 这些行可以被折叠
const processed = item
.trim()
.toLowerCase()
.split('-')
.map(part => part.charAt(0).toUpperCase() + part.slice(1))
.join('');
results.push(processed);
});
return results;
}

五、表格#

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

效果:

左对齐居中对齐右对齐
内容1内容2内容3
内容4内容5内容6

六、数学公式#

行内公式#

行内公式示例:$E = mc^2$,这是爱因斯坦的质能方程。

效果:
行内公式示例:E=mc2E = mc^2,这是爱因斯坦的质能方程。

块级公式#

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

效果:

ex2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

七、行块#

使用竖线 | 开头的行会被识别为行块。行块用于保持原始的换行格式:

原始代码:

| 第一行
| 第二行
| 第三行

效果:

| 第一行 | 第二行 | 第三行


八、分隔线#

使用三个或更多的 - 或 * 或 _ 创建分隔线:
---
***
___

效果:


九、扩展功能#

提示框(Admonitions)#

基础语法:

:::note
这是一个普通提示框,用于强调信息。
:::
:::tip
这是一个技巧提示框,提供有用的建议。
:::
:::important
这是一个重要提示框,包含关键信息。
:::
:::warning
这是一个警告提示框,提醒注意潜在风险。
:::
:::caution
这是一个注意提示框,说明可能的负面后果。
:::

效果:

NOTE

这是一个普通提示框,用于强调信息。

TIP

这是一个技巧提示框,提供有用的建议。

IMPORTANT

这是一个重要提示框,包含关键信息。

WARNING

这是一个警告提示框,提醒注意潜在风险。

CAUTION

这是一个注意提示框,说明可能的负面后果。

自定义标题:

:::note[📌 我的自定义标题]
可以为提示框设置自定义标题。
:::

效果:

📌 我的自定义标题

可以为提示框设置自定义标题。

GitHub 风格:

> [!NOTE]
> GitHub 风格的提示框语法也支持。
> [!TIP]
> 使用 [!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION] 等标记。

效果:

NOTE

GitHub 风格的提示框语法也支持。

TIP

使用 [!TIP]、[!IMPORTANT]、[!WARNING]、[!CAUTION] 等标记。

Spoiler(隐藏内容)#

The content :spoiler[is hidden]!
查看隐藏内容::spoiler[这是被隐藏的文本 **支持格式化**]!

效果:
The content is hidden until clicked!

你可以点击这里查看隐藏内容:这是被隐藏的文本 支持格式化!

GitHub 仓库卡片#

::github{repo="saicaca/fuwari"}

效果:

saicaca
/
fuwari
Waiting for api.github.com...
00K
0K
0K
Waiting...

嵌入视频#

YouTube:

<iframe width="100%" height="468"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>

Bilibili:

<iframe width="100%" height="468"
src="//player.bilibili.com/player.html?bvid=BV_ID&p=1"
scrolling="no"
border="0"
frameborder="no"
framespacing="0"
allowfullscreen="true">
</iframe>

Footnotes#

  1. 这是脚注的内容,会显示在页面底部。

博客框架使用教程
https://fuwari.vercel.app/posts/博客使用教程/
作者
Railgun19457
发布于
2025-11-13
许可协议
CC BY-NC-SA 4.0