AI内容警告
本文为AI翻译expressive-code和markdown-extended并总结, 然后人工查错并优化, 更多内容请看文章内容说明

高级 Markdown 用法参考(总结自`expressive-code`和`markdown-extended`)#

本文旨在展示 Fuwari 主题支持的更多高级格式，您可以参考这些示例来丰富您的文章内容。

A.1 GitHub 仓库卡片#

您可以嵌入一个动态的 GitHub 仓库卡片，它会在页面加载时自动获取最新的仓库信息。

saicaca

fuwari

Waiting for api.github.com...

00K

Waiting...

用法：

1
::github{repo="<owner>/<repo>"}

A.2 警告框 (Admonitions)#

警告框用于突出显示特定信息，支持多种类型。

NOTE
Note (注释): 用于突出那些即使用户只是扫读也应注意到的信息。

TIP
Tip (提示): 提供一些可选信息，帮助用户更成功地完成操作。

IMPORTANT
Important (重要): 对用户成功至关重要的信息。

WARNING
Warning (警告): 要求用户立即关注的关键内容，因其存在潜在风险。

CAUTION
Caution (小心): 指出某个操作可能带来的负面后果。

基础语法#

1
:::note
2
用于突出那些即使用户只是扫读也应注意到的信息。
3
:::
4

5
:::tip
6
提供一些可选信息，帮助用户更成功地完成操作。
7
:::

自定义标题#

您也可以为警告框添加自定义标题。

这是一个自定义标题
这是一个带有自定义标题的注释。

用法：

1
:::note[这是一个自定义标题]
2
这是一个带有自定义标题的注释。
3
:::

GitHub 风格警告框#

同样支持 GitHub Flavored Markdown 的警告框语法。

TIP
这是一个 GitHub 风格的提示。

用法：

1
> [!NOTE]
2
> 这是一个 Note。
3
> [!TIP]
4
> 这是一个 Tip。

A.3 Expressive Code 代码块增强#

语法高亮 (Syntax Highlighting)#

常规语法高亮#

1
console.log('这段代码被语法高亮了！')

用法:

1
```js
2
console.log('这段代码被语法高亮了！')
3
```

渲染 ANSI 转义序列#

1
ANSI colors:
2
- Regular: Red Green Yellow Blue Magenta Cyan
3
- Bold:    Red Green Yellow Blue Magenta Cyan
4
- Dimmed:  Red Green Yellow Blue Magenta Cyan
5

6
256 colors (showing colors 160-177):
7
160 161 162 163 164 165
8
166 167 168 169 170 171
9
172 173 174 175 176 177
10

11
Full RGB colors:
12
ForestGreen - RGB(34, 139, 34)
13

14
Text formatting: Bold Dimmed Italic Underline

用法:

1
```ansi
2
ANSI colors:
3
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
4
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
5
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m
6

7
256 colors (showing colors 160-177):
8
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
9
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
10
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m
11

12
Full RGB colors:
13
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m
14

15
Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m
16
```

编辑器与终端窗口 (Editor & Terminal Frames)#

代码编辑器窗口#

可以通过 title 属性为代码块添加标题。

1
console.log('这是一个标题属性的例子')

用法:

1
```js title="my-test-file.js"
2
console.log('这是一个标题属性的例子')
3
```

也可以通过在代码块顶部添加注释来指定文件名。

1
<div>这是一个文件名注释的例子</div>

用法:

1
```html
2
<!-- src/content/index.html -->
3
<div>这是一个文件名注释的例子</div>
4
```

终端窗口#

1
echo "这个终端窗口没有标题"

用法:

1
```bash
2
echo "这个终端窗口没有标题"
3
```

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

用法:

1
```powershell title="PowerShell 终端示例"
2
Write-Output "这个有标题！"
3
```

覆盖窗口类型#

你可以强制改变窗口的类型，例如将一个通常显示为终端的 sh 代码块变为无边框样式。

1
echo "看，没有边框了！"

用法:

1
```sh frame="none"
2
echo "看，没有边框了！"
3
```

或者将 PowerShell 代码块强制显示为代码编辑器样式。

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

用法:

1
```ps frame="code" title="PowerShell Profile.ps1"
2
# 如果不覆盖，这会是一个终端窗口
3
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
4
New-Alias tail Watch-Tail
5
```

文本与行标记 (Text & Line Markers)#

标记整行与行范围#

使用 {} 来指定需要标记的行号。

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

用法:

1
```js {1, 4, 7-8}
2
// 第 1 行 - 通过行号标记
3
// ...
4
```

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

可以分别指定 mark (普通标记), ins (插入), del (删除) 三种类型的行。

1
function demo() {
2
  console.log('这行被标记为 "删除"');
3
  // 这行和下一行被标记为 "插入"
4
  console.log('这是第二行 "插入" 的内容');
5

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

用法:

1
```js title="line-markers.js" del={2} ins={3-4} {6}
2
function demo() {
3
//...
4
}
5
```

使用类 Diff 语法#

1
这行将被标记为插入
2
这行将被标记为删除
3
这是普通的一行

用法:

1
```diff
2
+这行将被标记为插入
3
-这行将被标记为删除
4
这是普通的一行
5
```

结合语法高亮与类 Diff 语法#

1
function thisIsJavaScript() {
2
  // 整个代码块都会被高亮为 JavaScript，
3
  // 同时我们仍然可以添加 diff 标记！
4
  console.log('将被移除的旧代码')
5
  console.log('闪亮的新代码！')
6
}

用法:

1
```diff lang="js"
2
//...
3
```

标记行内文本#

通过 "字符串" 或 /正则表达式/ 来标记行内的特定文本。

1
function demo() {
2
  // "文本" 这个词会被标记
3
  return '这段文本中的"文本"二字会被标记。';
4
}

用法:

1
```js "文本"
2
function demo() {
3
//...
4
}
5
```

使用正则表达式#

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

用法:

1
```ts /ye[sp]/
2
console.log('单词 "yes" 和 "yep" 会被标记。')
3
```

自动换行 (Word Wrap)#

默认情况下，长代码行会自动换行。你可以通过 wrap 或 wrap=false 来控制单个代码块的行为。

1
// 带自动换行的例子
2
function getLongString() {
3
  return '这是一个非常非常长的字符串，除非容器特别宽，否则它很可能无法在可用空间内完全显示。'
4
}

用法:

1
```js wrap
2
//...
3
```

可折叠区域 (Collapsible Sections)#

使用 collapse={...} 来指定需要默认折叠的行范围。


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
```js collapse={1-5, 12-14, 21-24}
2
//...
3
```

行号 (Line Numbers)#

显示行号#

使用 showLineNumbers 来为代码块开启或关闭行号显示。

1
// 这个代码块会显示行号
2
console.log('来自第 2 行的问候！')
3
console.log('我在第 3 行')

用法:

1
```js showLineNumbers
2
//...
3
```

禁用行号#

// 这个代码块已禁用行号
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

用法:

1
```js showLineNumbers=false
2
// 这个代码块已禁用行号
3
console.log('Hello?')
4
console.log('Sorry, do you know what line I am on?')
5
```

更改起始行号#

使用 startLineNumber 来指定行号的起始数字。

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

用法:

1
```js showLineNumbers startLineNumber=5
2
//...
3
```

A.4 链接卡片 (Link Cards)#

内容来源说明
本部分内容基于 link-cards 的原始英文文档, 并参考了 Pull Request #324 中的实现, 在此基础上进行翻译、整理和补充。

链接卡片（Link Cards）功能可以将 Markdown 中的裸链接（Bare Link）渲染成美观的卡片样式。

基本用法#

在 Markdown 的段落中, 只需单独放置一个“裸”链接（即没有链接文本的链接）, 它就会被自动转换为链接卡片。

支持以下格式:

1
**外部链接**
2
https://astro.build/
3
<https://github.com/saicaca/fuwari/>
4
[https://fuwari.vercel.app/](https://fuwari.vercel.app/)
5

6
**内部链接** (需要额外配置)
7
[/posts/guide/](/posts/guide/)
8

9
**国际化域名 (IDN)**
10
https://はじめよう.みんな/

渲染效果如下:

https://astro.build/

https://github.com/saicaca/fuwari/

https://fuwari.vercel.app/

TIP
卡片显示后, 尝试切换一下主题颜色或开启暗黑模式看看效果！

高级配置选项#

点击展开详细配置

您可以在 astro.config.mjs 文件中对链接卡片功能进行详细配置。

启用插件#

首先, 你需要在配置文件中引入并启用插件。

1
import fuwariLinkCard from "./src/plugins/fuwari-link-card.ts"
2

3
export default defineConfig({
4
  // ...
5
  integrations: [
6
    // ...
7
    fuwariLinkCard(), // 在这里添加插件
8
    // ...
9
  ]
10
})

如果插件的加载顺序比较复杂, 您也可以将其作为一个 remark 插件来指定:

1
import remarkLinkCard from "./src/plugins/remark-link-card.ts"
2

3
export default defineConfig({
4
  // ...
5
  markdown: {
6
    // ...
7
    remarkPlugins: [
8
      // ...
9
      remarkLinkCard, // 在这里添加插件
10
      // ...
11
    ],
12
  },
13
})

主要配置项#

名称	类型	默认值	描述
`devMode`	`boolean`	`import.meta.env.DEV`	启用或禁用开发模式。
`excludedUrls`	`Array<string \| RegExp>`	`[]`	一个由字符串或正则表达式组成的列表, 用于排除特定的 URL, 防止它们被处理成链接卡片。这也有助于避免与其他插件冲突。
`linkAttributes`	`Object`	`{ target: '', rel: '' }`	为外部链接设置 `target` 和 `rel` 属性。也可以留空, 将处理交由其他插件决定。
`rewriteRules`	`Array<Object>`	`[]`	重写从链接获取的特定元数据属性, 例如标题和描述。
`base`	`string`	`'/'`	指定与 Astro 配置中相同的 `base` 路径。作为 integration 使用时, 若不指定, 该选项会自动推断。
`defaultThumbnail`	`string`	`''`	当元数据中不包含图片时, 使用的默认缩略图路径。该路径应相对于 `public` 目录。
`internalLink`	`Object`	`{ enabled: false, site: '' }`	启用站点内部链接的处理。
`cache`	`Object`	见下方详细说明	在构建过程中下载并缓存图片。

`linkAttributes` 详细说明#

名称	类型	默认值	描述
`target`	`string`	`''`	指定在何处打开链接文档。默认为空, 不设置 `target` 属性。
`rel`	`string`	`''`	定义当前文档与链接文档之间的关系。默认为空, 不设置任何关系。

`rewriteRules` 详细说明#

名称	类型	默认值	描述
`url`	`RegExp`		用于匹配特定 URL 的正则表达式。
`rewriteSteps`	`Array<Object>`		定义特定元数据属性的重写规则。

以下是一个重写 GitHub 仓库链接的标题和描述的示例:

1
rewriteRules: [
2
  {
3
    url: /^https:\/\/github\.com\/[^\/]+\/[^\/]+\/?$/,
4
    rewriteSteps: [
5
      { key: "title", pattern: /:.*/, replacement: "" },
6
      {
7
        key: "description",
8
        pattern: /(?: (?:\. )?Contribute to (?:.+\/.+) .+\.?)|(?: - (?:.+\/.+))$/,
9
        replacement: "",
10
      },
11
      {
12
        key: "description",
13
        pattern: /^Contribute to (?:.+\/.+) .+\.?$/,
14
        replacement: "No description provided.",
15
      },
16
    ],
17
  },
18
],

名称	类型	描述
`key`	`string`	要重写的元数据属性的键名。
`pattern`	`RegExp`	用于匹配元数据属性当前值的正则表达式。匹配的部分将被替换。
`replacement`	`string`	用于替换元数据属性中匹配内容的字符串。

`internalLink` 详细说明#

将 enabled 设置为 true 以启用站点内部链接的处理。site 和 base 选项用于将内部链接解析为绝对 URL。内部链接必须指向服务器上存在的文件。

名称	类型	默认值	描述
`enabled`	`boolean`	`false`	启用或禁用内部链接处理。
`site`	`string`	`''`	指定与 Astro 配置中相同的部署 URL。作为 integration 使用时, 若不指定, 该选项会自动推断。

`cache` 详细说明#

以下相关选项可让您轻松控制缓存行为。

名称	类型	默认值	描述
`enabled`	`boolean`	`false`	启用或禁用缓存。
`outDir`	`string`	`'./dist/'`	输出目录路径。与 Astro 的 `outDir` 保持一致可以利用图像优化等特性。
`cacheDir`	`string`	`'./link-card/'`	缓存目录路径。如果 `devMode` 为 `true`, 缓存图片的最终 URL 将是 `base + outDir + cacheDir`；否则是 `base + cacheDir`。
`maxFileSize`	`number`	`0`	要缓存的最大文件大小（字节）。设置为 0 表示无限制。
`maxCacheSize`	`number`	`0`	最大总缓存大小（字节）。设置为 0 表示无限制。
`userAgent`	`string`	`Mozilla/5.0 ...`	HTTP 请求头中包含的客户端标识符。

快速简便的选项设置#

该插件使用 @fastify/deepmerge 来简化选项设置。

https://www.npmjs.com/package/@fastify/deepmerge

用于样式定制的HTML结构#

链接卡片的样式由 src/styles/link-card.css 文件定义, HTML 结构是自动生成的。当您需要自定义样式时, 可以参考以下结构:

1
<div class="link-card__container">
2
  <a href="https://astro.build/" class="link-card">
3
    <div class="link-card__info">
4
      <div class="link-card__title">Astro</div>
5
      <div class="link-card__description">Astro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between.</div>
6
      <div class="link-card__metadata">
7
        <div class="link-card__domain">
8
          <img alt="favicon" class="link-card__favicon" src="https://www.google.com/s2/favicons?domain=astro.build">
9
          <span class="link-card__domain-name">astro.build</span>
10
        </div>
11
      </div>
12
    </div>
13
    <div class="link-card__thumbnail">
14
      <img alt="Astro - Build the web you want." class="link-card__image" src="https://astro.build/og/astro.jpg">
15
    </div>
16
  </a>
17
</div>

Fuwari 主题 Markdown 速查表与高级用法

高级 Markdown 用法参考(总结自expressive-code和markdown-extended)#

A.1 GitHub 仓库卡片#

A.2 警告框 (Admonitions)#

基础语法#

自定义标题#

GitHub 风格警告框#

A.3 Expressive Code 代码块增强#

语法高亮 (Syntax Highlighting)#

常规语法高亮#

渲染 ANSI 转义序列#

编辑器与终端窗口 (Editor & Terminal Frames)#

代码编辑器窗口#

终端窗口#

覆盖窗口类型#

文本与行标记 (Text & Line Markers)#

标记整行与行范围#

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

使用类 Diff 语法#

结合语法高亮与类 Diff 语法#

标记行内文本#

使用正则表达式#

自动换行 (Word Wrap)#

可折叠区域 (Collapsible Sections)#

行号 (Line Numbers)#

显示行号#

禁用行号#

更改起始行号#

A.4 链接卡片 (Link Cards)#

基本用法#

高级配置选项#

启用插件#

主要配置项#

linkAttributes 详细说明#

rewriteRules 详细说明#

internalLink 详细说明#

cache 详细说明#

快速简便的选项设置#

用于样式定制的HTML结构#

赞助支持

评论区

目录

高级 Markdown 用法参考(总结自`expressive-code`和`markdown-extended`)#

`linkAttributes` 详细说明#

`rewriteRules` 详细说明#

`internalLink` 详细说明#

`cache` 详细说明#