1150 字
6 分钟

Shirone 写作与使用指南

2026-08-26GuidesShironeGuideMarkdownM3EBlogging

欢迎使用 Shirone（白音）：这是一款富有表现力、灵感源自动漫的博客主题，基于 Astro 7、Svelte 5 和 **Material 3 Expressive（M3E）**设计系统构建。

本指南介绍文章创建、frontmatter 规范、目录结构，以及全部内置 Markdown 和 MDX 扩展。

1. 创建新文章#

使用内置 CLI 命令，可以快速创建包含标准 frontmatter 的文章框架：

Terminal window
# 创建单文件文章
pnpm new-post my-first-post


# 或在子目录中创建文章
pnpm new-post guides/getting-started

新建文件会放在 src/content/posts/ 中。

2. Frontmatter 规范#

每篇 Markdown（.md）或 MDX（.mdx）文章都以 YAML frontmatter 块开头，用于定义元数据。

示例#

---
title: "探索 Material 3 Expressive 设计"
published: 2026-08-26
updated: 2026-08-27
publishedAt: 2026-08-26T10:00:00+08:00
updatedAt: 2026-08-27T09:30:00+08:00
pinned: true
description: "深入了解 Shirone 中的动态 HCT 色彩科学与流畅过渡。"
image: "./cover.webp"
tags: [M3E, Design, Frontend]
category: Guides
draft: false
comment: true
---

支持的 frontmatter 字段#

字段类型必填说明
titlestring是文章主标题。
publishedDate是发布日期，格式为 YYYY-MM-DD。
publishedAtDate否精确发布时间，用于对同一天发布的文章排序。在站点配置的时区中，它必须落在 published 所指定的日期。
updatedDate否最后更新日期。填写后会显示更新提示徽标。
updatedAtDate否供订阅源和机器可读元数据使用的精确更新时间。必须与 updated 配套设置。
pinnedboolean否将文章置顶于文章列表（默认：false）。
descriptionstring否显示在文章卡片、搜索结果和 OpenGraph 元数据中的文章摘要。
imagestring否封面图路径。支持相对路径（./cover.webp）、公共资源路径（/images/cover.jpg）或远程 URL。
tagsstring[]否标签名称数组，用于分类筛选和标签云。
categorystring否用于分类索引的主分类名称。
draftboolean否标记为草稿。生产构建（pnpm build）时会隐藏草稿文章。
commentboolean否控制当前文章的评论区开关（默认：true）。
langstring否文章语言与站点默认语言不同时使用的语言代码（如 en、zh_CN、ja）。

3. 文章加密#

Shirone 提供客户端文章加密。这是一道静态密码门，而非服务端访问控制：加密载荷和资源 URL 仍可公开下载，因此不要用它保存真正的机密文件或受监管的秘密信息。对于私人日记或限制阅读的文章，可以在 frontmatter 中指定密码：

---
title: "私人研究笔记"
published: 2026-08-26
encrypted: true
password: "your-secret-passphrase"
passwordHint: "最喜欢的动漫角色"
hideHomeContent: true
---
  • encrypted: 设为 true 以启用加密；
  • password: 解锁文章所需的口令，可以是字符串或数字；
  • passwordHint: 显示在密码输入表单上方的可选提示；
  • hideHomeContent: 在首页隐藏字数和内容预览，防止数据泄漏。

4. 组织文章文件#

Shirone 同时支持文章与资源同目录存放，以及单文件布局：

文件夹结构（本地资源推荐使用）#

将文章与媒体放在同一目录，便于管理资源：

src/content/posts/
├── my-great-post/
│   ├── index.md           <-- 文章内容
│   ├── cover.webp         <-- 封面图 (image: "./cover.webp")
│   └── diagram.png        <-- Markdown 中引用的正文插图

单文件结构（适合简短文字）#

src/content/posts/
├── hello-world.md
└── quick-thoughts.md

5. 丰富的 Markdown 与 MDX 扩展#

Shirone 开箱即用地提供现代 Markdown 扩展：

5.1 提示块#

使用容器指令展示注释、提示、警告和提醒：

:::tip
使用提示容器突出关键结论或最佳实践。
:::


:::warning
使用警告容器提示潜在陷阱或破坏性变更。
:::

5.2 GitHub 仓库卡片#

使用指令语法嵌入实时更新、样式精美的 GitHub 仓库卡片：

::github{repo="LyraVoid/Shirone"}
LyraVoidShirone

5.3 Expressive Code 代码块#

增强代码块支持语法高亮、文件名徽标、行号和指定行高亮：

src/utils/theme.ts
// 动态推导 HCT 色彩令牌
import { argbFromHex, themeFromSourceColor } from "@material/material-color-utilities";


const theme = themeFromSourceColor(argbFromHex("#f472b6"));
console.log("主色令牌：", theme.schemes.light.primary);

5.4 数学排版（KaTeX）#

直接在 Markdown 中渲染美观的 LaTeX 数学表达式：

  • 行内公式： E=mc2E = mc^2 或欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0.
  • 块级公式：
∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}

5.5 Mermaid 图表#

用纯文本创建流程图、时序图和架构图：

sequenceDiagram
    autonumber
    actor Visitor as 访客
    participant Page as Shirone 页面
    participant Swup as Swup 容器
    participant Audio as 持久应用框架

    Visitor->>Page: 点击导航链接
    Page->>Swup: 触发无缝过渡
    Swup->>Page: 替换 #swup-container
    Note over Audio: 背景音乐持续播放
    Page-->>Visitor: 新页面渲染完成

5.6 图片画廊与 Fancybox 灯箱#

图片会自动接入 Fancybox，支持无损缩放、平移手势和全屏预览：

![封面预览](./cover.jpeg)

6. 后续步骤与自定义#

  • 站点配置：了解全局设置，参阅 src/config/siteConfig.ts 和 src/config/README.md.
  • 设计令牌：了解令牌与调色板，参阅 DESIGN.md 和 docs/m3e-standard.md。
  • 反馈与社区：在以下页面分享想法和问题： GitHub Issues.
Shirone 写作与使用指南
https://blog.codingshen.top/posts/guide/
作者
AlexShen
发布于
2026-08-26
许可协议
CC BY-NC-SA 4.0

分享文章

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

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取

评论

正在加载评论...
我是 AlexShen，在蛋壳宇宙记录技术与日常
密码保护与文章加密演示