FangYuan

内容与主题分离，以及评论接入

Fri, 24 Apr 2026 00:00:00 GMT

FangYuan 现在更适合按“双仓”来维护：公开仓库存放主题源码和 demo，私有仓库存放正式站点内容。这样做的重点不是把东西拆散，而是让主题演进和内容运营各自独立。

主题负责什么

主题仓库主要负责站点本身的结构和能力，包括：

src/components/、src/layouts/、src/styles/ 里的界面与样式
src/plugins/ 和 src/utils/ 里的 Markdown 扩展、路由规则和工具函数
src/default-config.ts 里的 demo 默认配置
src/content/ 里的内置演示文章

这层更像“可复用的站点外壳”。它可以持续迭代，但不必和真实内容仓库绑死在一起。

内容负责什么

真实站点内容更适合放在外部 site/ 输入层里维护：

site/site.config.yaml
site/content/
site/assets/

这样一来，主题仓库可以继续公开，正式文章、页面和站点配置则可以单独放在私有仓库里，再通过同步或挂载方式进入构建流程。

两种开发模式

当前仓库已经内置了内部演示模式和外部内容模式：

pnpm dev:internal
pnpm dev:external

pnpm build:internal
pnpm build:external

internal：使用仓库内 src/content/ 和默认配置，适合主题演示、功能测试和公开 demo
external：使用 site/ 下的真实内容与配置，适合联调正式站点

这样可以保证“同一套主题代码”既能展示 demo，又能服务正式站点。

评论、反馈和统计

评论相关能力已经按可选模块处理，不要求每个站点都必须启用。

评论使用 commentConfig
页面反馈使用 pageFeedbackConfig
页面统计使用 pageMetricsConfig

这些能力都可以接入 QingYan。如果后端没有配置完成，前端会直接隐藏对应区块，而不是留下空壳组件。

对于 demo 站点，这种做法很合适：可以先展示主题本身和内容结构，等正式站点准备好评论后端后，再在外部站点配置里接入。

适合的工作流

如果把这套方案落成双仓，比较顺的分工通常是：

公开仓库维护主题、演示内容和 Pages 站点
私有仓库维护正式文章、页面、资源和站点配置
正式部署时走外部内容模式
主题更新时，先在 demo 验证，再同步到正式站点

这样既能保留一个稳定的公开演示入口，也不会把真实内容直接暴露在主题仓库里。

Expressive Code 示例

Mon, 16 Feb 2026 00:00:00 GMT

下面集中展示 Expressive Code 在 FangYuan 中的代码块效果。示例主要整理自官方文档，方便直接对照查看渲染结果。

Expressive Code

语法高亮

Syntax Highlighting

常规语法高亮

console.log("这段代码启用了语法高亮！")

渲染 ANSI 转义序列

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

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

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

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

编辑器与终端边框

Editor & Terminal Frames

代码编辑器边框

console.log("标题属性示例")

<!-- src/content/index.html -->
<div>文件名注释示例</div>

终端边框

echo "这个终端边框没有标题"

Write-Output "这个终端边框带有标题！"

覆写边框类型

echo "看，这里没有边框！"

# 如果不手动覆写，这里默认会显示成终端边框
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

文本与行标记

Text & Line Markers

标记整行与行区间

// 第 1 行 - 通过行号命中
// 第 2 行
// 第 3 行
// 第 4 行 - 通过行号命中
// 第 5 行
// 第 6 行
// 第 7 行 - 通过区间 "7-8" 命中
// 第 8 行 - 通过区间 "7-8" 命中

选择行标记类型（mark、ins、del）

function demo() {
  console.log("这一行会被标记为删除")
  // 这一行和下一行会被标记为新增
  console.log("这是第二行新增内容")

  return "这一行使用默认的中性标记类型"
}

给行标记添加标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === "string" ? <span>{children}</span> : children)}
</button>

使用单独一行显示长标签

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === "string" ? <span>{children}</span> : children)}
</button>

使用 diff 风格语法

+这一行会被标记为新增
-这一行会被标记为删除
这一行是普通内容

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+这是一份真正的 diff 文件
-所有内容都会保持原样
 不会额外删除任何空白字符

结合语法高亮与 diff 风格语法

  function thisIsJavaScript() {
    // 这一整段都会按照 JavaScript 语法高亮，
    // 同时依然可以叠加 diff 标记！
-   console.log("旧代码将被移除")
+   console.log("这里换成新的代码")
  }

标记行内的局部文本

function demo() {
  // 可以在一行中标记任意指定文本
  return "支持对指定文本进行多次匹配";
}

正则表达式

console.log("yes 和 yep 这两个单词都会被标记。")

转义正斜杠

echo "测试" > /home/test.txt

选择行内标记类型（mark、ins、del）

function demo() {
  console.log("这里演示新增与删除两种行内标记");
  // return 语句会使用默认标记类型
  return true;
}

自动换行

Word Wrap

按代码块配置换行

// 启用自动换行的示例
function getLongString() {
  return "这是一段非常长的字符串，除非容器足够宽，否则大概率放不进可见区域"
}

// 禁用自动换行的示例
function getLongString() {
  return "这是一段非常长的字符串，除非容器足够宽，否则大概率放不进可见区域"
}

配置换行后的缩进

// preserveIndent 示例（默认启用）
function getLongString() {
  return "这是一段非常长的字符串，除非容器足够宽，否则大概率放不进可见区域"
}

// preserveIndent=false 示例
function getLongString() {
  return "这是一段非常长的字符串，除非容器足够宽，否则大概率放不进可见区域"
}

可折叠区块

Collapsible Sections

// 这一段样板初始化代码会被折叠
import { someBoilerplateEngine } from "@example/some-boilerplate"
import { evenMoreBoilerplate } from "@example/even-more-boilerplate"

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// 这部分代码默认会展开显示
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // 可以在同一个代码块里设置多个折叠区
  const a = 1
  const b = 2
  const c = a + b

  // 这一行会保持可见
  console.log(`计算结果：${a} + ${b} = ${c}`)
  return c
}

// 从这里到代码块结尾会再次折叠
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: "示例样板代码结束" })

行号

Line Numbers

按代码块显示行号

// 这个代码块会显示行号
console.log("这里是第 2 行")
console.log("这里是第 3 行")

// 这个代码块关闭了行号
console.log("你好")
console.log("现在你知道我在第几行了吗？")

修改起始行号

console.log("这里是第 5 行")
console.log("这里是第 6 行")

内容指令扩展示例

Mon, 09 Feb 2026 00:00:00 GMT

这篇文章集中展示 FangYuan 后续补充的内容指令组件，便于单独检查它们的渲染和交互效果。

行内高亮

当一句话里只需要强调某个短语，而不希望用整块提示区域时，可以使用行内高亮。

普通强调：重点信息

建议提示：推荐做法

强提醒：需要特别注意

<mark class="md-highlight tone-note" data-tone="note">重点信息</mark>

<mark class="md-highlight tone-tip" data-tone="tip">推荐做法</mark>

<mark class="md-highlight tone-warning" data-tone="warning">需要特别注意</mark>

折叠块

折叠块适合放可选细节、更新记录，或者不想默认展开的较长示例。

展开示例

这里是默认折叠的内容。

<details class="md-fold" data-icon="file"><summary class="md-fold-summary">展开示例</summary><div class="md-fold-body">
<p>这里是默认折叠的内容。</p>
</div></details>

折叠块选项

可以直接在指令参数里控制默认展开状态以及标题图标。

默认关闭，不写 open：

默认关闭示例

这里默认保持折叠。

默认展开，显式写 open="true"：

默认展开示例

这里会在页面加载时直接展开。

隐藏左侧图标：

无图标示例

这里保留标题和箭头，但不显示左侧图标。

替换图标：

书签图标示例

可选图标包括 file note tip warning question bookmark sparkles none

<details class="md-fold" data-icon="file"><summary class="md-fold-summary">默认关闭示例</summary><div class="md-fold-body">
<p>这里默认保持折叠。</p>
</div></details>

<details class="md-fold" data-icon="file" open><summary class="md-fold-summary">默认展开示例</summary><div class="md-fold-body">
<p>这里会在页面加载时直接展开。</p>
</div></details>

<details class="md-fold" data-icon="none"><summary class="md-fold-summary">无图标示例</summary><div class="md-fold-body">
<p>这里保留标题和箭头，但不显示左侧图标。</p>
</div></details>

<details class="md-fold" data-icon="bookmark"><summary class="md-fold-summary">书签图标示例</summary><div class="md-fold-body">
<p>可选图标包括 <code>file</code> <code>note</code> <code>tip</code> <code>warning</code> <code>question</code> <code>bookmark</code> <code>sparkles</code> <code>none</code></p>
</div></details>

补充说明块

Aside 适合放不会打断正文主线的补充说明、附言或轻量提醒。

<aside class="md-aside">
<p>这是一段补充说明，适合放背景、PS 或轻量提醒。</p>
</aside>

Markdown 扩展功能

Mon, 02 Feb 2026 00:00:00 GMT

GitHub 仓库卡片

可以在文章里插入链接到 GitHub 仓库的动态卡片。页面加载时，会自动从 GitHub API 拉取仓库信息。

::github{repo="Fabrizz/MMM-OnSpotify"}

使用 ::github{repo="<owner>/<repo>"} 就能创建一张 GitHub 仓库卡片。

::github{repo="Virace/FangYuan"}

提示块

当前支持以下几种提示块类型：note、tip、important、warning、caution

:::note 即使只是快速浏览，也应该注意这类信息。 :::

:::tip 这类补充信息可以帮助读者更顺利地完成操作。 :::

:::important 这类信息通常是顺利完成任务所必需的关键内容。 :::

:::warning 这类内容通常与潜在风险有关，需要读者立即关注。 :::

:::caution 这类内容用于提醒某个操作可能带来的负面后果。 :::

基础语法

:::note
即使只是快速浏览，也应该注意这类信息。
:::

:::tip
这类补充信息可以帮助读者更顺利地完成操作。
:::

自定义标题

提示块标题也可以自定义。

:::note[自定义标题] 这是一个带自定义标题的 note 类型提示块。 :::

:::note[自定义标题]
这是一个带自定义标题的 `note` 类型提示块。
:::

GitHub 语法

[!TIP] 也兼容 GitHub 提示块语法。

> [!NOTE]
> 也兼容 GitHub 的提示块语法。

> [!TIP]
> 也兼容 GitHub 的提示块语法。

剧透

可以在正文里插入剧透内容，剧透内部同样支持 Markdown 语法。

这段内容 :spoiler[会被隐藏嘿嘿]！

这段内容 :spoiler[会被隐藏 **嘿嘿**]！

行内高亮、折叠块和 Aside 这几类 FangYuan 后续补充的内容指令，已经单独整理到《内容指令扩展示例》里，方便分别查看效果。

在文章中嵌入视频

Mon, 26 Jan 2026 00:00:00 GMT

只要把 YouTube 或其他平台提供的嵌入代码复制出来，再粘贴进 Markdown 文件即可。

---
title: 在文章中嵌入视频
published: 2026-01-26
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube 视频播放器" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili

FangYuan 简明指南

Mon, 19 Jan 2026 00:00:00 GMT

封面图来源：来源链接

这个博客模板基于 Astro 构建。指南里没有展开说明的部分，通常都可以在 Astro Docs 里找到答案。

文章 Frontmatter

---
title: 我的第一篇博客文章
published: 2026-01-12
description: 这是我新的 Astro 博客中的第一篇文章。
image: ./cover.jpg
tags: [示例, 前端]
category: 前端
draft: false
---

字段	说明
`title`	文章标题。
`published`	文章发布时间。
`description`	文章简介，会展示在列表页。
`image`	文章封面图路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：表示图片位于 `public/` 目录 3. 没有这些前缀：表示相对当前 Markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`draft`	是否为草稿。草稿文章不会展示给访客。

文章文件应该放在哪里

文章文件应该放在 src/content/posts/ 目录下。你也可以按需创建子目录，用来更好地组织文章和配套资源。

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

Markdown 示例

Mon, 12 Jan 2026 00:00:00 GMT

一级标题

段落之间使用空行分隔。

第二段。斜体、粗体，以及 等宽文本。无序列表看起来像这样：

第一项
第二项
第三项

请注意，正文内容会从缩进 4 个空格之后开始。

引用块可以这样写。

如果需要，也可以跨越多个段落。

用 3 个连字符表示破折号。用 2 个连字符表示范围（例如“第 12--14 章”）。三个点 ... 会被转换为省略号。支持 Unicode。☺

二级标题

下面是一个有序列表：

第一项
第二项
第三项

再次注意，正文会从左侧第 4 列开始，也就是缩进 4 个字符。下面是一个代码示例：

# 再强调一次……
for i in 1 .. 10 { do-something(i) }

如你所见，这里用了 4 个空格缩进。除此之外，你也可以不用缩进，而是改用围栏代码块：

define foobar() {
    print "欢迎来到示例世界！";
}

这样复制和粘贴会更方便。你也可以额外给围栏代码块标记语言，让 Pandoc 执行语法高亮：

import time
# 快一点，开始数到十！
for i in range(10):
    # （不过别太快）
    time.sleep(0.5)
    print(i)

三级标题

下面是一个嵌套列表示例：

先准备这些食材：
- 胡萝卜
- 芹菜
- 扁豆
烧一锅水。

把所有东西都倒进锅里，然后按下面这个流程操作：

 找到木勺
 打开锅盖
 搅拌
 盖上锅盖
 小心地把木勺架在锅柄上
 等 10 分钟
 回到第一步（或者煮好后关火）

不要碰到木勺，否则它会掉下来。

再看一次，正文总是会和 4 空格缩进对齐，包括上面接在第 3 项后面的那一行。

这里有一个指向某个网站的链接、一个指向本地文档的链接，以及一个指向当前文档章节标题的链接。这里还有一个脚注 ^1。

表格可以这样写：

尺码材质颜色

9 皮革棕色 10 麻布原色 11 玻璃透明

表：鞋子、尺码以及材质

上面这一行就是表格标题。Pandoc 还支持多行表格：

关键词文本

红色日落、苹果，以及其他偏红的东西。

绿色树叶、草地、青蛙，还有那些当绿色并不轻松的东西。

接下来是一条分隔线。

下面是一个定义列表：

苹果 : 适合拿来做苹果酱。橙子 : 典型的柑橘类水果。番茄 : 英文 tomato 里没有多余的 e。

这里的正文同样缩进 4 个空格。（如果你想让版面更松一些，可以在每组术语和定义之间加一个空行。）

下面是一个“行块”：

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

图片也可以这样写：

行内数学公式可以这样写：$\omega = d\phi / dt$。独立成块的数学公式通常单独占一行，并放在双美元符号之间：

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

另外，如果你希望某些标点按字面显示，可以用反斜杠进行转义，例如：`foo`、*bar* 等。