1350 字
107 分钟
Shirone Markdown 扩展
2026-08-19指南演示MarkdownShirone扩展主题

Shirone 提供了一组主题专属的 Markdown 扩展与自定义语法容器。它们构建在我们原生 unified AST 处理管线之上。

想了解这套管线为什么「零注水」，可以看 Astro 的岛架构说明。

Shirone 提供了一组主题专属的 Markdown 扩展与自定义语法容器。它们构建在我们原生 unified AST 处理管线之上，所有扩展都在站点构建期渲染为无障碍且语义化的 HTML，不产生任何客户端 JavaScript 注水开销，并完全对齐 M3E 设计令牌。

文件树#

文件树把多层级项目结构、源码层级与终端目录输出变成紧凑、可交互的树状视图，支持自动匹配扩展名图标、差异高亮以及可折叠分支。

1. 嵌套列表语法（:::file-tree）#

当你想直接用 Markdown 嵌套列表书写文件层级时，使用 :::file-tree 块级指令。

:::file-tree{title="Shirone source tree"}
- src
  - components/
    - ++ Navigation.svelte # added component
    - -- Button.astro # removed component
  - content
    - posts/
      - markdown-enhancements.md
  - layouts/
    - PostLayout.astro
  - plugins
    - markdown/
      - rehype-file-tree.mjs
  - styles
    - markdown/
      - trees.css
  - **content.config.ts** # important file
- public/
  - favicon.svg
- package.json
:::
Shirone source tree
  • src
    • components
      • +Navigation.svelteadded component
      • -Button.astroremoved component
    • content
      • posts
        • markdown-enhancements.md
    • layouts
      • PostLayout.astro
    • plugins
      • markdown
        • rehype-file-tree.mjs
    • styles
      • markdown
        • trees.css
    • content.config.tsimportant file
  • public
    • favicon.svg
  • package.json

写作规则与标记#

  • 差异状态：给条目前加 ++（绿色背景与徽标）或 --（红色背景与删除线）即可高亮变更。
  • 注释：# 之后的文本会渲染为淡色、右对齐的行内注释。
  • 强调：用 **粗体** 包裹名称，让关键文件获得更醒目的视觉权重。
  • 可折叠目录：由嵌套列表项推断出的目录默认展开。加上结尾斜杠（如 components/）可创建默认折叠的目录，读者点击或用键盘导航即可展开。

2. 终端输出语法（```file-tree）#

当你已经有 tree 这类命令行工具生成的目录树文本时，直接把它粘贴进 file-tree 围栏代码块即可。Unicode 分支字符（├──、└──、│）与 ASCII 分支都会被自动解析。

```file-tree title="Build output" icon="simple"
dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico
```
Build output
  • dist
    • _astro
      • index.css
      • page.js
    • favicon.ico

配置项#

  • title="string"：为文件树设置自定义头部标题与无障碍标签。
  • icon="colored" | "simple"：在多彩扩展名图标（colored，默认）与极简单色图标（simple）之间切换。

代码树#

可交互的代码树把左侧的多层级文件导航面板与右侧即时切换的代码面板配对。它能为多文件示例、模块或整目录走读提供类似 IDE 的阅读体验。

1. 容器语法（:::code-tree）#

在 :::code-tree 块级指令中组合多个围栏代码块。每个代码块通过 title="path/to/file" 指定它的路径。

:::code-tree{title="Shirone Component Demo" height="380px" entry="src/Button.svelte"}
```svelte title="src/Button.svelte"
<script lang="ts">
  let { label = "Click me" } = $props();
</script>


<button class="m3-btn">{label}</button>
```


```stylus title="src/styles/button.styl"
.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
```


```json title="package.json"
{
  "name": "button-demo",
  "version": "1.0.0"
}
```
:::
Shirone Component Demo
src/Button.svelte
<script lang="ts">
  let { label = "Click me" } = $props();
</script>


<button class="m3-btn">{label}</button>

配置与标记#

  • title="string"：为代码树设置头部标题与无障碍标签。
  • height="string"：设置桌面视图的高度（默认 420px，例如 380px、26rem）。
  • entry="filepath"：指定首次加载时处于激活状态的文件。
  • icon="colored" | "simple"：在彩色与极简单色文件图标之间切换。
  • :active：在任意围栏代码块上放置 :active，即可将其指定为默认激活标签页。

2. 本地目录自动导入（@[code-tree]）#

直接指向工作区中的任意本地目录路径，即可在构建期自动扫描并生成可交互的代码树，无需手动复制文件内容。

@[code-tree title="Anime Utilities" entry="status.ts"](/src/utils/anime)
Site Configuration
siteConfig.ts
import type { SiteConfig } from "@/types/config";
import type {
  ResolvedTextureOptions,
  TextureConfig,
} from "@/types/textureConfig";
import { withUserConfig } from "../utils/config-overlay.ts";


/**
 * 站点核心配置：标题 / 语言 / 主题色（HCT 动态配色）/ 横幅 / 目录 / 进度条 / favicon。
 * 类型见 src/types/config.ts。
 */
export const siteConfig: SiteConfig = withUserConfig("site", {
  site: "https://www.dafeiyu.site/",
  base: "/",
  title: "蓝色大肥鱼",
  subtitle: "DeepSeek鲸鱼娘的个人博客",
  // 电脑端顶栏标题与导航内容区域："left" 左对齐，"center" 居中。
  topAppBar: {
    contentAlign: "center",
  },
  // 显示设置面板控制：配置各项前端切换项的可见性（默认全部开启）。
  displaySettings: {
    colorStyle: true, // 是否展示配色风格 9 宫格
    colorSpec: true, // 是否展示 Color Spec 调色规范切换
    wallpaperMode: true, // 是否展示页面背景（纯色/横幅）切换
    layoutMode: true, // 是否展示文章列表布局（列表/网格）切换
    reduceMotion: true, // 是否展示减少动效切换
    texture: true, // 是否展示背景纹理选择
  },
  lang: "zh_CN", // Language code, e.g. 'en', 'zh_CN', 'ja', etc.
  // IANA time zone for precise post and moment timestamps. It is independent of lang.
  timeZone: "Asia/Shanghai",
  themeColor: {
    hue: 218, // Default hue 0-360. 蓝白手绘风取 218（蓝）；315 粉紫 / 262 紫 也可选
    fixed: false, // Hide the theme color picker for visitors
    // Dynamic Material 3 palette style (TonalSpot/Vibrant/Content/Expressive/Rainbow/FruitSalad/Monochrome/Neutral/Fidelity)
    style: "tonalSpot",
    // Design spec version: "2021" (MD3) or "2025" (M3 Expressive)。角色集一致，
    // 差异仅在调色板派生（库的 colorSpec 静态为 2025 委托）
    spec: "2025",
  },
  // 默认页面背景模式："banner" 使用壁纸横幅，"none" 使用主题纯色。
  // 访客在“显示设置”中的选择会保存在浏览器中，并覆盖这里的默认值。
  wallpaperMode: {
    defaultMode: "banner",
  },
  // 页面背景纹理系统配置（5 大精美预设 + 零开销 HCT 动态取色）
  texture: {
    enable: true, // 是否启用背景纹理系统
    defaultPreset: "grid-paper", // 默认纹理预设："none" | "starlight" | "cyber-dots" | "topography" | "geometric" | "sakura" | "grid-paper"
    defaultOpacity: 0.5, // 默认纹理浓度 (0.05 ~ 0.85)
    allowMotion: true, // 是否允许背景微动效（开启 reduced-motion 时自动静止）
  },
  banner: {
    // 推荐将图片放入 src/assets，并填写相对 src 的路径，以启用构建期 AVIF/WebP 响应式优化。
    // 以 "/" 开头的 public 路径与远程 URL 仍可用，但会保留原图、不生成候选。
    // desktop 用于 >= 1024px；mobile 仅用于 < 1024px 的首页，手机非首页不显示壁纸。
    // 数组顺序就是轮播顺序；只需要静态 Banner 时，每组保留一张图片即可。
    src: {
      desktop: ["assets/images/banner/desktop/1.webp"],
      mobile: ["assets/images/banner/mobile/1.webp"],
    },
    // 图片裁切焦点："top"、"center" 或 "bottom"。
    position: "center",
    dim: {
      // 在图片上覆盖黑色遮罩以提高标题和顶部栏的对比度；opacity 范围为 0-1。
      enable: true,
      opacity: 0.24,
    },
    homeText: {
      // 仅在首页 Banner 中显示，标题与副标题会上下居中排列。
      enable: true,
      title: "蓝色大肥鱼",
      subtitle: [
        "收好每一张有趣的图",
        "猫鲸的日常，小小一只，表情很多",
        "蓝色大肥鱼 · DeepSeek鲸鱼娘的个人博客",
        "表情包、随笔、技术笔记，想到什么写什么",
        "找到今天的心情",
      ],
      typewriter: {
        // 副标题逐字显示；关闭后直接显示完整副标题。
        enable: true,
        // 打字速度（每个字符间隔，毫秒）。
        speed: 100,
        // 回退反向删除速度（每个字符间隔，毫秒）。
        deleteSpeed: 50,
        // 打字完成后停顿时间，单位为毫秒。
        pauseTime: 2000,
        // 完成后是否循环播放；关闭表示只播放一次。
        loop: true,
      },
    },
    carousel: {
      // 是否开启多张图片自动轮播；多张图片时生效，单张图片时自动降级为静态展示。
      enable: true,
      // 轮播切换间隔时间（毫秒），运行时最小值限制为 3000ms。
      interval: 6000,
      // 交叉淡入淡出（Crossfade）过渡时长（毫秒，默认 1200ms）。
      fadeDuration: 1200,
      // 运镜呼吸动画模式："ken-burns"（默认，循环运镜）| "zoom-in"（推进）| "zoom-out"（拉远）| "pan-left"（左移）| "pan-right"（右移）| "none"（无运镜）。
      animation: "ken-burns",
    },
    waves: {
      // 在 Banner 底部渲染页面背景色水波纹；关闭后不输出波浪 DOM。
      enable: true,
    },
  },
  // Markdown 正文图片处理；仅匹配远程图片，不会产生额外网络请求或客户端代码。
  imageOptimization: {
    // 为需要防盗链兼容的图片 CDN 添加 referrerpolicy="no-referrer"，支持通配符。
    noReferrerDomains: ["*.hdslb.com"],
  },
  toc: {
    enable: true, // Display the table of contents on the right side of the post
    depth: 2, // Maximum heading depth to show in the table, from 1 to 3
  },
  progressIndicator: {
    // 进度条预设样式：dual 双向扫描（官方默认双线）/ single 单向扫描（单线）
    style: "dual",
  },
  favicon: [
    // 浏览器标签页图标，路径相对于 public 目录。
    { src: "/logo/icon.webp" },
  ],
});


/**
 * 解析并返回背景纹理配置选项（包含关闭短路与 0 开销优化判定）
 */
export function resolveTextureOptions(
  config: boolean | TextureConfig | undefined = siteConfig.texture,
  displaySettingsTexture: boolean = siteConfig.displaySettings?.texture ?? true,
): ResolvedTextureOptions {
  if (config === false || config === undefined) {
    return {
      enable: false,
      defaultPreset: "none",
      defaultOpacity: 0.12,
      allowMotion: false,
    };
  }


  if (config === true) {
    return {
      enable: true,
      defaultPreset: "grid-paper",
      defaultOpacity: 0.5,
      allowMotion: true,
    };
  }


  const enable = config.enable ?? true;
  const defaultPreset = config.defaultPreset ?? "grid-paper";
  const defaultOpacity = config.defaultOpacity ?? 0.5;
  const allowMotion = config.allowMotion ?? true;


  // 性能短路优化：
  // 如果配置 enable: false，或者 defaultPreset: "none" 且显示设置面板未允许切换（访客也无法开启），
  // 则自动视为完全关闭以达成零 DOM、零 CSS、零运行时代价。
  const effectiveEnable =
    enable && (defaultPreset !== "none" || displaySettingsTexture);


  return {
    enable: effectiveEnable,
    defaultPreset,
    defaultOpacity,
    allowMotion,
  };
}


/** 站点默认配色风格（访客未做选择时的回退值） */
export function getDefaultStyle(): string {
  return siteConfig.themeColor.style;
}


/** 站点默认 Color Spec（2021 / 2025） */
export function getDefaultSpec(): string {
  return siteConfig.themeColor.spec;
}


/** 解析并返回显示设置面板各项开关（未配置时默认 true） */
export function resolveDisplaySettings(): {
  colorStyle: boolean;
  colorSpec: boolean;
  wallpaperMode: boolean;
  layoutMode: boolean;
  reduceMotion: boolean;
  texture: boolean;
} {
  const cfg = siteConfig.displaySettings;
  const textureOpts = resolveTextureOptions(
    siteConfig.texture,
    cfg?.texture ?? true,
  );
  return {
    colorStyle: cfg?.colorStyle ?? true,
    colorSpec: cfg?.colorSpec ?? true,
    wallpaperMode: cfg?.wallpaperMode ?? true,
    layoutMode: cfg?.layoutMode ?? true,
    reduceMotion: cfg?.reduceMotion ?? true,
    texture: textureOpts.enable && (cfg?.texture ?? true),
  };
}

Markdown 语法指南

已完结

第 3 篇，共 3 篇本文属于系列

Shirone Markdown 扩展
https://www.dafeiyu.site/posts/markdown-enhancements/
作者
蓝色大肥鱼
发布于
2026-08-19
许可协议
CC BY-NC-SA 4.0

分享文章

生成精美分享图或复制链接，与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取

评论

0 条评论
文章加密与密码保护演示
我的一些小工具