Baiym's Blog

欢迎使用 Shirone 内容仓库

Thu, 27 Aug 2026 00:00:00 GMT

欢迎使用

这是一篇在内容分离架构下的示例文章。本篇文章保存在独立的内容仓库中，与主题代码完全解耦。

元数据说明

文章顶部的 Frontmatter 支持以下字段：

title：文章标题
published：发布日期，格式如 YYYY-MM-DD
updated：最后修改日期，可选
description：文章摘要描述
image：文章封面图路径或外部链接
category：文章所属分类
tags：标签列表
pinned：是否置顶
series：所属系列 slug，对应 content/series/<slug>.md
seriesOrder：系列内排序序号（整数），缺省时按发布日期排序
draft：是否为草稿，草稿在生产构建时会被自动过滤
comment：是否开启本篇文章的评论区

代码高亮

interface SiteIdentity {
  name: string;
  repo: string;
  mode: "external" | "local";
}

const config: SiteIdentity = {
  name: "Shirone",
  repo: "Shirone-Content",
  mode: "external"
};

提示块样式

这是一个标准的引用与提示区块示例。

第一篇博客！

Wed, 10 Jun 2026 00:00:00 GMT

如你所见，这是我搭建的一个个人博客网页，并且是我的第一条博客！

在结合众多教程下，终于将个人博客网站搭建成功。首先感谢GitHub开源项目Firefly，其次感谢bilibili视频博主：番茄煮理人以及个人博客网站：Hyde！在他们的博客教程下,我成功的将个人博客部署成功并添加各种功能组件。最后感谢Github和Cloudflare提供的各种服务！

接下来我会持续学习，继续走在前进的路上！

Shirone 像素级打磨：文章元数据（Meta）与悬停交互的重构

Sun, 25 Oct 2026 00:00:00 GMT

在上篇文章中，我们搞定了卡片等高和基础截断。但当你放大页面仔细看时，一定还会发现一堆让人血压升高的细节：

“置顶”图钉怎么是个方块？
分类图标、标签图标怎么比文字飘高了一点点？
分类和标签之间距离太远，强行换行后对齐又全乱了？
底部的日期和字数怎么才能加上阅读时间？

这篇文章记录了我对 PostMeta.astro 组件的终极重构，包含大量 CSS 玄学修复。

📌 第一阶段：“置顶”徽章的重构

原本的置顶只是一个简单的图钉 Icon。为了让它更好看，我决定把它改成带有绿色背景的胶囊形状。

在 PostCard.astro 中修改 HTML：

{pinned && (
  <span class="m3-blog-postcard__pin">
    <Icon name="material-symbols:keep-rounded" />
    <span class="m3-blog-postcard__pin-text">置顶</span>
  </span>
)}

核心 CSS 魔法：

  &__pin
    display: inline-flex
    align-items: center
    gap: 0.2rem
    padding: 0.15rem 0.5rem
    border-radius: 9999px
    background: var(--primary-container)
    color: var(--on-primary-container)
    font-size: 0.8rem
    font-weight: 500
    line-height: 1                /* 锁死行高，防止撑大 */
    vertical-align: middle
    transform: translateY(0px)    /* 玄学微调：根据实际情况上下移动，对齐文字中线 */
    margin-right: 0.4rem

🔀 第二阶段：分类与标签的“缝合”与绝对对称

在默认的 Shirone 中，分类是一个 div，标签是另一个 div。这导致它们作为 Flex 子项时，如果放不下，标签会被整体挤到下一行，留下难看的空白。

1. 打碎容器，回归文本流

我们在 HTML 中把分类和标签合并进同一个 span，并在 CSS 里使用 display: contents 打碎 PostMeta 的外壳：

  &__item--taxonomy
    display: inline         /* 变成纯文本流 */
    line-height: 1.6

2. 解决斜杠的“不对称”

以前用 <span>/</span> 会受 HTML 换行符影响，导致左右间距不一样。最终我使用了 CSS 伪元素：

  &__link--with-sep
    &::before
      content: "/"
      display: inline-block
      margin: 0 0.4rem
      color: var(--outline-variant)
      font-size: 0.875rem

3. 终极对齐：图标的物理位移

在纯文本流里，vertical-align: middle 对中文字符完全不友好，图标永远偏上。

解决方案：放弃 middle 的幻想，使用 transform 进行物理按压：

:global(.m3-blog-postmeta) :global(.m3-meta-icon)
  display: inline-flex
  width: 0.95em
  height: 0.95em
  vertical-align: middle
  transform: translateY(1px)    /* 强行往下压 1px，和文字完美平齐 */
  margin-right: 0.2rem

⏱️ 第三阶段：底部元数据的分离与计算

为了模仿高端主题的排版，我把“分类/标签”留在了标题下方，把“日期/字数/阅读时间”拆到了卡片最底部。

1. 拆分 PostMeta

在 PostCard.astro 中调用两次 PostMeta 组件：

<!-- 上方：只显示分类和标签 -->
<PostMeta {published} {category} {tags} hideDate hideWordCount hideUpdate />

<!-- 下方：纯手写底部行，只显示日期和字数 -->
<div class="m3-blog-postcard__footer">
  <span class="m3-blog-postcard__footer-item">
    <Icon name="material-symbols:calendar-today-outline-rounded" />
    {published}
  </span>
</div>

2. 阅读时间（前端计算）

Shirone 没有自带阅读时间。我们在 frontmatter 脚本中，按 300字/分钟粗略计算：

const readingMinutes = wordCount
  ? Math.max(1, Math.round(parseInt(wordCount.replace(/\D/g, ""), 10) / 300))
  : null;

然后把它渲染在底部：

{readingMinutes && (
  <>
    <span class="m3-blog-postcard__footer-divider">|</span>
    <span class="m3-blog-postcard__footer-item">
      <Icon name="material-symbols:schedule-outline-rounded" />
      {readingMinutes} 分钟
    </span>
  </>
)}

底部的 CSS 使用 margin-top: auto 沉底，并利用 &__footer-item 统一控制小图标的尺寸，防止它们大小不一。

🪄 第四阶段：列表模式的悬停魔法

最后，我们要实现右侧封面的“高级感”。

平时：图片左侧有渐变虚化，融入背景。
悬停：虚化消失，边缘变清晰，图片微微放大。

实现原理：

放大效果使用 transform: scale(1.05)。
虚化消失使用 mask-image 的过渡：

  &__cover
    > picture > img
      transition: transform 0.4s ease

    .m3-blog-postcard:hover & > picture > img
      transform: scale(1.05)

    @media (min-width: bp-md)
      mask-image: linear-gradient(to right, transparent 0%, black 30%)
      transition: mask-image 0.4s ease

      .m3-blog-postcard:hover &
        mask-image: linear-gradient(to right, transparent 0%, black 5%)

极其重要的一点：绝对不要为了“禁止点击”而给封面加上 pointer-events: none;，否则鼠标悬停事件会被直接穿透，放大动画永远不会触发！直接使用 <div> 包裹图片即可，因为 div 本身就没有链接跳转功能。

总结

这次重构，让我深刻体会到了 CSS 的“玄学”与乐趣。从 display: contents 的妙用，到 -webkit-line-clamp 的截断，再到 transform 的物理像素级微调。每一个微小的细节，最终汇聚成了极其舒适的阅读体验。

至此，我的 Shirone 卡片改造终于画上了完美的句号。

Shirone 排版调优：从三列瀑布流到完美等高卡片

Sun, 25 Oct 2026 00:00:00 GMT

在折腾完双仓分离架构后，我本以为博客的建设大业已经完成，直到我点开文章列表的「网格模式（Grid）」。

满屏的卡片高低错落、无图卡片矮一截、长标题直接把卡片撑爆……这对于强迫症来说简直是灾难。

这篇文章记录了我对 Shirone 主题 PostCard.astro 和 PostMeta.astro 组件的深度调教，一步步实现“三列等高完美网格”和“列表模式高级虚化”的全过程。

🧱 第一阶段：为什么我的网格只有两列？

Shirone 的网格布局是基于 CSS Grid 和容器查询（@container）实现的。默认情况下，如果你用的是 regular 档位，容器宽度必须达到 49rem（约 784px） 才会激活两列。如果你用的是 compact 档位，也需要达到 41rem（约 656px）。

如果你的主内容区因为侧边栏挤压，宽度只有 742px，就会刚好卡在 regular 的阈值下方，导致永远只能显示单列。

解决方案： 如果你想强行上三列，可以修改主题源码 src/config/postListConfig.ts 中的最小宽度常量：

export const POST_CARD_MIN_WIDTH = {
  compact: "14rem", // 默认是 20rem，改为 14rem 即可在 742px 下容纳三列
  regular: "24rem",
  relaxed: "28rem"
};

同时在内容仓的 post-list.yaml 中开启 compact 模式。

📐 第二阶段：强迫症福音 —— 卡片绝对等高

激活多列后，最丑的问题来了：有封面的卡片很高，无封面的卡片很矮；标题长的文章很高，标题短的很矮。

要解决这个问题，我们需要进行三步手术。

1. 无图卡片插入“透明占位块”

在 PostCard.astro 的 HTML 中，不要用 {hasCover && ...} 来控制整个图片容器的渲染。我们应该始终渲染容器，内部用三元表达式判断：

<div class="m3-blog-postcard__cover">
  {hasCover ? (
    <picture>
      {/* 你的图片代码 */}
    </picture>
  ) : (
    <div class="m3-blog-postcard__cover-placeholder"></div>
  )}
</div>

然后在 CSS 中，让它在列表模式下隐藏，网格模式下显示（利用 aspect-ratio: 16/9 撑开高度）：

  &__cover
    &-placeholder
      background: var(--card-bg) // 或者纯透明
      width: 100%
      height: 100%

  @media (min-width: bp-md)
    &:not(.m3-blog-postcard--cover) &__cover
      display: none // 列表模式隐藏占位块

  grid-card-layout(shell-selector)
    :global({shell-selector} .m3e-post-list--grid) &:not(.m3-blog-postcard--cover) &__cover
      display: block // 网格模式强制显示

2. 强制文本截断（ -webkit-line-clamp ）

为了防止长标题和长标签把卡片撑爆，必须在 PostCard.astro 中限制它们的行数。

标签行：display: -webkit-box; -webkit-line-clamp: 2; overflow: hidden;
简介行：display: -webkit-box; -webkit-line-clamp: 2; overflow: hidden;
标题：因为标题是用 <a> 包裹的 flex 布局（为了让右侧箭头对齐），直接加截断会失效。所以我们在标题文字外面套一层 <span class="m3-blog-postcard__title-text">，只对文字进行截断。

3. 锁死卡片物理高度

最后，在 grid-card-layout 宏里，给最外层的卡片加上固定高度（比如 365px），并切断溢出：

  grid-card-layout(shell-selector)
    :global({shell-selector} .m3e-post-list--grid) &
      flex-direction: column-reverse
      height: 365px            // 绝对高度
      overflow: hidden         // 超出部分物理切断

⚓ 第三阶段：底部信息的“推底”设计

默认的日期、字数、阅读时间混在元数据里。为了实现强迫症对齐，我在 PostCard.astro 的 HTML 里把手写了底部信息行：

<div class="m3-blog-postcard__footer">
  <span class="m3-blog-postcard__footer-item">
    <Icon name="material-symbols:calendar-today-outline-rounded" /> {published}
  </span>
  <span class="m3-blog-postcard__footer-divider">|</span>
  <span class="m3-blog-postcard__footer-item">
    <Icon name="material-symbols:article-outline-rounded" /> {wordCount}
  </span>
</div>

配合 __body 的 flex 布局，让它永远贴着底边：

  &__body
    display: flex
    flex-direction: column

  &__footer
    margin-top: auto             // 核心：吃掉中间所有多余的高度
    padding-top: var(--m3e-space-2)
    font-size: 0.85rem

🪄 第四阶段：列表模式的图片“高级感”

网格模式解决后，列表模式（List）的右侧封面也有讲究。我想实现：平时左侧虚化融合，悬停时放大且边缘变清晰。

注意：绝对不要加 pointer-events: none，否则 :hover 无法触发。

  &__cover
    > picture > img
      transition: transform 0.4s cubic-bezier(0.2, 0, 0, 1)
      
    // 悬停放大
    .m3-blog-postcard:hover & > picture > img
      transform: scale(1.05)

    @media (min-width: bp-md)
      position: absolute
      top: 0
      right: 0
      bottom: 0
      width: 32%
      
      // 默认渐变虚化
      mask-image: linear-gradient(to right, transparent 0%, black 30%)
      -webkit-mask-image: linear-gradient(to right, transparent 0%, black 30%)
      transition: mask-image 0.4s ease
      
      // 悬停时清晰
      .m3-blog-postcard:hover &
        mask-image: linear-gradient(to right, transparent 0%, black 5%)
        -webkit-mask-image: linear-gradient(to right, transparent 0%, black 5%)

同时，在网格模式下，必须使用 mask-image: none !important 强制取消虚化，保证网格图片边缘干净利落。

总结

经过这一番改造，PostCard.astro 不再是一个简单的展示组件，而是一个精密的布局机器。虽然代码量增加了不少，但最终呈现的视觉效果——整齐划一的等高网格和丝滑的虚化悬停，绝对对得起这几天的折腾。

如果你也受够了排版错乱，不妨对着上面的代码试试看！

告别臃肿！Shirone 博客双仓分离架构与 Vercel 自动化部署保姆级指南

Sat, 24 Oct 2026 00:00:00 GMT

如果你使用过 Hexo、Hugo 或 Astro 的各种主题，一定会面临一个痛点：主题更新与个人内容的冲突。

单仓模式下，每次官方主题发布新功能，你执行 git pull 时，满屏的冲突会让你崩溃，因为你的文章和主题的默认代码混在同一个目录里。而 npm 包模式虽然省心，但如果想修改一下页面的 CSS 布局，就会无从下手。

双仓分离（源码模式 + 独立内容仓） 完美解决了这个问题：

主题仓：存放所有的前端源码、组件和样式，随时可以跟随官方更新。
内容仓（建议设为私有）：只存放你的文章、相册和配置。即便代码开源，私密草稿也不会泄露。

🛠️ 第一步：搭建本地主题源码环境

确保你的电脑上安装了 Node.js (>= 22.12) 和 pnpm，并全局启用了 Git。

打开终端，找一个你喜欢的目录（比如 D:\Code），执行：

# 1. 克隆 Shirone 主题源码
git clone https://github.com/LyraVoid/Shirone.git my-blog
cd my-blog

# 2. 安装依赖
pnpm install

此时，不要急着运行 pnpm dev，因为我们需要先配置好内容分离架构。

📦 第二步：建立私有的“内容仓库”

这是整个流程中最容易踩坑的地方。

1. 准备空白私有仓库

不要直接在 GitHub 上点 Fork（因为 GitHub 为了安全，不允许把 Fork 来的仓库直接改成 Private）。

正确做法：

在本地找另一个文件夹，克隆官方内容模板：

git clone https://github.com/LyraVoid/Shirone-Content.git my-content
cd my-content
rm -rf .git

去 GitHub 新建一个完全空白的仓库（比如叫 my-shirone-content），务必勾选 Private。
把本地内容推送到你的私有仓库：

git init
git add .
git commit -m "init my private content repo"
git branch -M main
git remote add origin <你的私有仓库地址>
git push -u origin main

🔗 第三步：将双仓在本地“缝合”起来

回到你的主题源码目录（D:\Code\my-blog），我们要建立两者的关联。

1. 创建连接配置文件

在根目录新建 shirone.content.json，必须使用 Shirone 官方要求的 Schema 结构：

{
  "schemaVersion": 1,
  "source": {
    "type": "git",
    "url": "https://github.com/你的用户名/my-shirone-content.git",
    "ref": "main"
  },
  "mounts": {
    "content": "src/content",
    "data": "src/data",
    "assets": "src/assets",
    "public": "public"
  },
  "keep": [],
  "prune": true
}

2. 配置本地环境变量

在根目录新建 .env，填入你本地内容仓库的绝对路径（使用正斜杠 /）：

CONTENT_DIR="D:/Code/my-content"

3. 防止私有内容被误传（非常关键！）

打开根目录的 .gitignore，在末尾追加以下内容。因为 content:sync 会把文章同步到主题目录，如果不忽略，你的私有文章就会被推送到公开的主题仓：

src/content/
src/data/
.env

4. 测试本地预览

在终端执行同步命令，把文章从私仓拉取过来：

pnpm content:sync
pnpm dev

打开 http://localhost:4321，如果能看到你的文章，说明本地架构已经彻底跑通了。

🚀 第四步：Vercel 部署与终极避坑

本地跑通后，我们把主题仓库推送到 GitHub，并在 Vercel 导入。

Vercel 默认的配置绝对会失败，而且它对 Git 认证字符串的解析有 Bug（很容易报 Invalid username or token）。请放弃在 URL 里拼接变量的想法，直接使用 Vercel 环境变量注入完整地址。

1. 生成细粒度 Token (Fine-grained PAT)

去 GitHub -> Settings -> Developer settings -> Fine-grained personal access tokens。生成一个 Token：

Repository access：只选你的私有内容仓 my-shirone-content。
Permissions：找到 Contents，设置为 Read-only。复制这个以 github_pat_ 开头的 Token 保存好。

2. 修改 `shirone.content.json` 读取环境变量

在根目录把 shirone.content.json 的 url 字段改为一个自定义变量名（比如 CONTENT_REPO_URL）：

{
  "schemaVersion": 1,
  "source": {
    "type": "git",
    "url": "${CONTENT_REPO_URL}",
    "ref": "main"
  },
  "mounts": {
    "content": "src/content",
    "data": "src/data",
    "assets": "src/assets",
    "public": "public"
  },
  "keep": [],
  "prune": true
}

3. Vercel 后台配置

在 Vercel 项目 Settings -> Environment Variables 中，添加以下环境变量：

Key: CONTENT_REPO_URL
Value: https://你的用户名:你的github_pat_Token@github.com/你的用户名/my-shirone-content.git (注意：这里直接填入完整的带 Token 的 URL，Vercel 环境变量是安全的，不会泄露。不要加任何空格)
Key: NODE_VERSION
Value: 22

在 Settings -> Build & Development Settings 中，覆盖 Build Command 为：

pnpm content:sync && pnpm build

配置完成后，点击 Redeploy。如果一切顺利，你的博客就上线了！

✍️ 日常写作与更新流程

完成上述所有步骤后，你的日常维护将变得极其简单：

打开你的 my-content 文件夹。
在 content/posts/ 下新建 Markdown 文件，开始写文章。
写完后，执行 git add . -> git commit -m "更新文章" -> git push。
去 Vercel 后台点一下 Redeploy。

💡 踩坑排雷指南

报错提示 tags Expected type "array", received "string"：检查你 Markdown 头部的 frontmatter，tags 必须是数组，例如 tags: ["博客", "指南"]。
本地预览时没有同步最新文章：每次切回主题仓终端，记得先运行一次 pnpm content:sync。
Vercel 报 Invalid username or token：不要尝试在 URL 里写 ${GITHUB_TOKEN} 让 Vercel 去解析，100%会失败。必须像上面第四步那样，在环境变量里填完整的带 Token 的 URL。

折腾的尽头是稳定。双仓分离虽然搭建时稍微麻烦了一点，但它赋予了你极大的自由度——你可以随意修改主题源码，同时安全地保护你的文字。祝你的博客越写越好！