From 3a9fcb6c0fa93844835f4e254e633c4448440483 Mon Sep 17 00:00:00 2001 From: RiseForever Date: Tue, 11 Aug 2026 21:07:54 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=BB=E9=A2=98=E5=A4=A7Debuff?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- NOTICE.md | 225 +++++++++++++++++++++++++++++++ README.md | 232 +++----------------------------- src/layouts/BaseLayout.astro | 2 +- src/pages/posts/[...slug].astro | 2 +- src/styles/content.css | 92 +++++++++++-- src/styles/global.css | 8 +- src/styles/shortcodes.css | 5 +- src/styles/themes.css | 10 ++ src/styles/tokens.css | 40 ++++-- 9 files changed, 378 insertions(+), 238 deletions(-) create mode 100644 NOTICE.md diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 0000000..62d4da4 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,225 @@ +# Mirages Astro + +Mirages 是一个基于 Astro 的静态博客主题，用于发布文章和独立页面。旧版 PHP 文件位于本项目之外，保持不变。 + +本文档说明 Astro 主题的常用配置、Twikoo 评论和文章 Frontmatter。 + +## 运行项目 + +运行项目需要 Node.js 和 Corepack。 + +```sh +corepack pnpm install +corepack pnpm dev +``` + +`corepack pnpm check` 用于执行 Astro 类型和内容检查；`corepack pnpm build` 用于构建静态站点并生成 Pagefind 搜索索引；`corepack pnpm preview` 用于预览构建后的站点。 + +## 基本配置 + +主要配置文件是 `src/site.config.ts`。发布前至少修改以下内容： + +| 配置 | 位置 | 用途 | +| --- | --- | --- | +| 站点名称 | `site.title` | 页面标题、导航站点名 | +| 站点描述 | `site.description` | 默认 description、RSS 描述 | +| 作者信息 | `site.author` | 头像、作者名、简介 | +| 正式域名 | `site.url` | canonical、RSS、sitemap、robots.txt 和社交分享地址 | +| 导航菜单 | `navigation` | 顶部和移动端导航 | +| Banner | `banner` | 首页横幅标题、图片、尺寸和遮罩 | +| 默认封面 | `cards.defaultCovers` | 文章没有封面时使用的候选图片 | +| 标签云数量 | `archives.tagLimit` | 归档页显示的最多标签数，设为 `0` 显示全部 | +| 页脚 | `footer` | 版权、说明和页脚链接 | + +`site.url` 必须替换为真实的 HTTPS 域名，不要保留 `https://example.com`，否则 sitemap、canonical 和 Open Graph URL 都会指向错误地址。 + +### 网站图标 Favicon + +当前 `src/layouts/BaseLayout.astro` 中的默认配置使用空白 data URI 图标。添加自己的图标时： + +1. 将图标放入 `public/`，例如 `public/favicon.svg` 或 `public/favicon.png`。 +2. 编辑 `src/layouts/BaseLayout.astro` 的 ``，把默认图标： + +```astro + +``` + +替换为： + +```astro + +``` + +PNG 图标示例： + +```astro + +``` + +如需 Apple 设备图标，可同时添加： + +```astro + +``` + +`public/` 下的文件会原样复制到站点根目录。修改后运行 `pnpm build`，并使用强制刷新检查浏览器缓存。 + +### 其他基本信息 + +颜色主题、默认主题和主题色位于 `appearance`；RSS、搜索、导航和自定义工具按钮也都在 `src/site.config.ts` 中配置。自定义工具按钮可按 `toolbarItems` 的类型定义添加 `link` 或 `rss` 项。`astro.config.mjs` 会读取 `site.url` 用于 sitemap 和站点构建配置。 + +## Twikoo 配置 + +Twikoo 评论默认关闭。完整配置入口是： + +```text +astro/src/site.config.ts +``` + +将： + +```ts +comments: { provider: 'none' }, +``` + +改为： + +```ts +comments: { + provider: 'twikoo', + envId: '你的 Twikoo 云函数地址', + region: 'cn', + lang: 'zh-CN' +}, +``` + +其中 `envId` 就是 Twikoo 云函数或后端服务地址。例如使用 Vercel、Netlify、CloudBase 或自有服务器部署后，填写部署平台提供的公开访问地址： + +```ts +envId: 'https://your-twikoo-api.example.com' +``` + +不要填写管理后台地址，也不要填写带具体文章路径的 URL。这里填写的是 Twikoo 服务根地址，前端会将它传给 `twikoo.init()`。 + +只有使用腾讯云 CloudBase 环境 ID 时才需要填写 `region`；填写 URL 型云函数或自托管服务地址时不要填写它。`lang` 可按需要修改，默认使用站点语言。 + +然后在需要评论的文章 Frontmatter 中启用： + +```yaml +comments: true +``` + +Twikoo 客户端脚本由 `src/components/TwikooComments.astro` 从 jsDelivr 延迟加载，只有评论区域接近视口时才初始化。评论数量由 `src/components/TwikooCommentCounts.astro` 读取。修改配置后重新构建并部署： + +```sh +pnpm build +``` + +如果页面显示“评论暂时不可用”，依次检查云函数地址是否能从浏览器直接访问、CORS 配置、Twikoo 环境变量和 `envId` 是否包含多余路径或空格。 + +## 文章 Frontmatter + +文章位于 `src/content/posts`，独立页面位于 `src/content/pages`。两者使用相同的字段结构： + +```yaml +title: 文章标题 # 必填 +description: 简短摘要 # 可选，文章摘要和 SEO 描述 +pubDate: 2026-07-30 +updatedDate: 2026-08-01 +draft: false +slug: custom-url +cover: https://images.example.com/article-cover.jpg +hero: https://images.example.com/article-hero.jpg +categories: [Notes] +tags: [astro] +textTone: auto +toc: + enabled: true + position: right +comments: true +math: false +mermaid: false +``` + +### 字段说明 + +| 字段 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `title` | 字符串 | 必填 | 文章标题。用于文章页标题、卡片和 SEO 标题。 | +| `description` | 字符串 | 无 | 文章摘要；用于 SEO description，未填写时会从正文生成摘要。 | +| `pubDate` | 日期 | 必填 | 发布日期，支持 `YYYY-MM-DD` 等可被 JavaScript 解析的日期格式。 | +| `updatedDate` | 日期 | 无 | 修改日期，适合在文章有实质更新时填写。 | +| `draft` | 布尔值 | `false` | `true` 时不生成文章路由，也不会出现在列表、RSS 和 sitemap 中。 | +| `slug` | 字符串 | 文件名/路径 | 自定义文章 URL slug。建议只使用稳定的英文、数字和短横线。 | +| `cover` | 字符串 | 无 | 文章卡片和文章 Banner 的封面 URL。支持绝对 URL 和项目内路径。 | +| `hero` | 字符串 | 无 | 兼容旧内容的 Banner 图片字段；没有 `cover` 时可作为图片来源。 | +| `categories` | 字符串数组 | `[]` | 文章分类，例如 `[随笔, 写作]`。 | +| `tags` | 字符串数组 | `[]` | 文章标签，例如 `[Astro, 前端]`。 | +| `textTone` | `light` / `dark` / `auto` | 无 | Banner 文字颜色。`auto` 会在图片加载后根据图片亮度判断。 | +| `toc` | 布尔值或对象 | `false` | 是否显示目录。对象可设置 `enabled` 和 `position: left/right`。 | +| `comments` | 布尔值 | `false` | 是否显示 Twikoo 评论区；还需要先在站点配置中启用 Twikoo。 | +| `math` | 布尔值 | `false` | 是否加载 KaTeX，用于 LaTeX 数学公式。 | +| `mermaid` | 布尔值 | `false` | 是否加载 Mermaid，用于 `mermaid` 代码块。 | + +Frontmatter 必须放在 Markdown 文件开头的两个 `---` 之间。数组可以使用行内格式，也可以使用多行格式： + +```yaml +categories: + - 随笔 + - 写作 +tags: + - Astro + - 网站 +``` + +目录配置示例： + +```yaml +toc: + enabled: true + position: left +``` + +文章卡片在构建时按以下顺序选择图片：`cover`、兼容旧内容的 `hero`、Markdown/MDX 正文中的第一张标准 Markdown 图片或 HTML `img`，最后使用 `siteConfig.cards.defaultCovers` 中的确定性候选图片。正文中的相对图片地址会根据最终文章 URL 解析，例如 `/posts/hello/` 中的 `images/photo.jpg` 会解析为 `/posts/hello/images/photo.jpg`。如果 `defaultCovers` 为空且没有其他图片，卡片会使用确定性的纯色背景作为兜底。 + +如果文章没有 `cover` 或 `hero`，只在正文中添加图片也可以： + +```md +![Article image](./images/article.jpg) +``` + +`src/content/posts/first-light.md`、`content-workflow.md` 和 `quiet-default.md` 分别演示了 Frontmatter 封面、正文图片和默认封面路径。 + +`draft: true` 会将文章从文章列表、RSS、sitemap 和生成路由中排除。`toc` 也可以直接设置为 `true` 或 `false`；对象形式支持 `position: left` 或 `right`。目录标题由 Astro `render()` 返回的 headings 生成，并使用真实的 `#slug` 锚点。桌面端显示侧边目录，较小屏幕使用原生 `details` 控件，不会导致页面整体偏移。 + +包含 LaTeX 公式时设置 `math: true`。Markdown 通过 `remark-math` 和 `rehype-katex` 构建，只有这些页面会加载 KaTeX CSS。这是构建时渲染，不会加载 MathJax。 + +包含 `mermaid` 代码块时设置 `mermaid: true`。Mermaid 只会在这些页面中动态加载，渲染主题会跟随当前深色模式设置。 + +## 路由和工具 + +- `/` 是文章首页；`/posts/.../` 是公开文章页面。 +- `/about/` 和其他非保留路径由 `src/content/pages` 生成。 +- `/archives/`、`/categories/.../` 和 `/tags/.../` 提供归档及分类、标签页面。 +- `/rss.xml` 是公开文章 RSS Feed。 +- `/sitemap-index.xml` 由 `@astrojs/sitemap` 生成；`/robots.txt` 会将搜索引擎指向 sitemap。 +- `build` 会为 `dist` 生成 Pagefind 索引；也可以使用 `search:index` 单独重新生成索引。 +- Twikoo 通过 `siteConfig.comments` 按需启用。浏览器端 CDN 地址固定使用已安装的 `twikoo` `1.7.15` 版本，并以延迟方式加载评论和评论数量。 + +## Markdown 短代码 + +短代码由 `src/lib/shortcodes.ts` 在构建时处理；现有 `.md` 文件继续支持，不需要迁移到 MDX。块级语法是 `[name key="value"]...[/name]`；GitHub 卡片还支持 `[github repo="owner/repo" /]`；`[!] text` 和 `[!/ ] text` 是行内提示。属性支持 ASCII 引号、中文排版引号、不加引号的值和布尔标记。代码围栏不会被短代码处理。 + +| 语法 | 支持情况 | 说明 | +| --- | --- | --- | +| `[!]`、`[!/ ]` | 支持 | 行内提示，仅识别这些明确形式 | +| `button`、`btn` | 支持 | 支持 `href`、`url` 或 `link`；仅允许 http/https/mailto/tel 和相对地址 | +| `file` | 支持 | URL 规则与按钮相同 | +| `tag`、`label` | 支持 | `type` 支持 primary、success、warning、danger、info、default；支持 `outline` | +| `hint`、`tip` | 支持 | `type` 支持 warn、warning、error、danger、success、info；可选 `title` | +| `collapse` | 支持 | 使用原生且可访问的 `details`/`summary`；支持 Markdown 和嵌套折叠 | +| `tabs`、`tab` | 支持 | 静态可访问标签页，通过少量原生客户端脚本切换；多个实例互不影响 | +| `github` | 支持 | 构建时生成 GitHub 仓库卡片，并验证 `owner/repo`。可选 `description`、`stars`、`forks`、`lastCommit` 或 `commitDate`、`readMore`、`download` | +| 未知或不安全的值 | 安全兜底 | 无效链接和仓库会作为普通文本输出 | + +`selected` 用于指定初始标签页。执行 `build` 时，`[github repo="owner/repo" /]` 使用的仓库会从 GitHub 公开仓库 API 获取，并缓存到 `.astro-cache/github.json`，缓存时间为 24 小时。可以设置 `GITHUB_CACHE_TTL_MS` 或 `GITHUB_API_TIMEOUT_MS` 调整默认值，也可以设置 `GITHUB_TOKEN` 以提高 API 访问限制；Token 不会写入缓存或构建输出。项目只使用公开仓库元数据。API 出错或处于开发模式时，会安全降级为仓库链接和 `—`，不会阻断构建。短代码中显式填写的属性始终优先于 API 数据；`readMore` 默认使用 `html_url`，`download` 使用 API 返回的 `default_branch`。浏览器端不会请求 GitHub API。已移除的短代码会触发构建错误，而不会作为普通 Markdown 输出。 diff --git a/README.md b/README.md index 62d4da4..b4a7839 100644 --- a/README.md +++ b/README.md @@ -1,225 +1,25 @@ -# Mirages Astro +![Astro](https://img.shields.io/badge/Built%20with-Astro-dee2e6?logo=astro&logoColor=white&style=for-the-badge)![Eidolon](https://img.shields.io/badge/theme-eidolon-yellow?style=for-the-badge) -Mirages 是一个基于 Astro 的静态博客主题，用于发布文章和独立页面。旧版 PHP 文件位于本项目之外，保持不变。 +--- -本文档说明 Astro 主题的常用配置、Twikoo 评论和文章 Frontmatter。 +这里是 **⌈路明笔记⌋** 的代码仓库。 -## 运行项目 +之所以在自己的服务器上托管一份，是因为 GitHub 直连很不稳定，导致我无法愉快地更新博客。自托管后，无需挂代理即可轻松更新。 -运行项目需要 Node.js 和 Corepack。 +## 主题 -```sh -corepack pnpm install -corepack pnpm dev -``` +Eidolon，基于 [Astro](https://astro.build) 进行构建的主题，设计思想参照了 Typecho 主题 [Mirages](https://get233.com/archives/mirages-intro.html)。 -`corepack pnpm check` 用于执行 Astro 类型和内容检查；`corepack pnpm build` 用于构建静态站点并生成 Pagefind 搜索索引；`corepack pnpm preview` 用于预览构建后的站点。 +我曾是 Mirages 主题用户，后为追求极致速度，便产生了移植主题到 Astro 的想法。 -## 基本配置 +一款外观相似、免费的主题，如果开源，可能会对原付费主题的销售造成影响。但细想想，我们其实不在一个赛道。喜欢使用 Typecho 博客系统、追求简约的用户，一定还会选择 Mirages 的。本主题的开源，只是为 Astro 用户提供另一种选择。 -主要配置文件是 `src/site.config.ts`。发布前至少修改以下内容： +特点： -| 配置 | 位置 | 用途 | -| --- | --- | --- | -| 站点名称 | `site.title` | 页面标题、导航站点名 | -| 站点描述 | `site.description` | 默认 description、RSS 描述 | -| 作者信息 | `site.author` | 头像、作者名、简介 | -| 正式域名 | `site.url` | canonical、RSS、sitemap、robots.txt 和社交分享地址 | -| 导航菜单 | `navigation` | 顶部和移动端导航 | -| Banner | `banner` | 首页横幅标题、图片、尺寸和遮罩 | -| 默认封面 | `cards.defaultCovers` | 文章没有封面时使用的候选图片 | -| 标签云数量 | `archives.tagLimit` | 归档页显示的最多标签数，设为 `0` 显示全部 | -| 页脚 | `footer` | 版权、说明和页脚链接 | - -`site.url` 必须替换为真实的 HTTPS 域名，不要保留 `https://example.com`，否则 sitemap、canonical 和 Open Graph URL 都会指向错误地址。 - -### 网站图标 Favicon - -当前 `src/layouts/BaseLayout.astro` 中的默认配置使用空白 data URI 图标。添加自己的图标时： - -1. 将图标放入 `public/`，例如 `public/favicon.svg` 或 `public/favicon.png`。 -2. 编辑 `src/layouts/BaseLayout.astro` 的 ``，把默认图标： - -```astro - -``` - -替换为： - -```astro - -``` - -PNG 图标示例： - -```astro - -``` - -如需 Apple 设备图标，可同时添加： - -```astro - -``` - -`public/` 下的文件会原样复制到站点根目录。修改后运行 `pnpm build`，并使用强制刷新检查浏览器缓存。 - -### 其他基本信息 - -颜色主题、默认主题和主题色位于 `appearance`；RSS、搜索、导航和自定义工具按钮也都在 `src/site.config.ts` 中配置。自定义工具按钮可按 `toolbarItems` 的类型定义添加 `link` 或 `rss` 项。`astro.config.mjs` 会读取 `site.url` 用于 sitemap 和站点构建配置。 - -## Twikoo 配置 - -Twikoo 评论默认关闭。完整配置入口是： - -```text -astro/src/site.config.ts -``` - -将： - -```ts -comments: { provider: 'none' }, -``` - -改为： - -```ts -comments: { - provider: 'twikoo', - envId: '你的 Twikoo 云函数地址', - region: 'cn', - lang: 'zh-CN' -}, -``` - -其中 `envId` 就是 Twikoo 云函数或后端服务地址。例如使用 Vercel、Netlify、CloudBase 或自有服务器部署后，填写部署平台提供的公开访问地址： - -```ts -envId: 'https://your-twikoo-api.example.com' -``` - -不要填写管理后台地址，也不要填写带具体文章路径的 URL。这里填写的是 Twikoo 服务根地址，前端会将它传给 `twikoo.init()`。 - -只有使用腾讯云 CloudBase 环境 ID 时才需要填写 `region`；填写 URL 型云函数或自托管服务地址时不要填写它。`lang` 可按需要修改，默认使用站点语言。 - -然后在需要评论的文章 Frontmatter 中启用： - -```yaml -comments: true -``` - -Twikoo 客户端脚本由 `src/components/TwikooComments.astro` 从 jsDelivr 延迟加载，只有评论区域接近视口时才初始化。评论数量由 `src/components/TwikooCommentCounts.astro` 读取。修改配置后重新构建并部署： - -```sh -pnpm build -``` - -如果页面显示“评论暂时不可用”，依次检查云函数地址是否能从浏览器直接访问、CORS 配置、Twikoo 环境变量和 `envId` 是否包含多余路径或空格。 - -## 文章 Frontmatter - -文章位于 `src/content/posts`，独立页面位于 `src/content/pages`。两者使用相同的字段结构： - -```yaml -title: 文章标题 # 必填 -description: 简短摘要 # 可选，文章摘要和 SEO 描述 -pubDate: 2026-07-30 -updatedDate: 2026-08-01 -draft: false -slug: custom-url -cover: https://images.example.com/article-cover.jpg -hero: https://images.example.com/article-hero.jpg -categories: [Notes] -tags: [astro] -textTone: auto -toc: - enabled: true - position: right -comments: true -math: false -mermaid: false -``` - -### 字段说明 - -| 字段 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `title` | 字符串 | 必填 | 文章标题。用于文章页标题、卡片和 SEO 标题。 | -| `description` | 字符串 | 无 | 文章摘要；用于 SEO description，未填写时会从正文生成摘要。 | -| `pubDate` | 日期 | 必填 | 发布日期，支持 `YYYY-MM-DD` 等可被 JavaScript 解析的日期格式。 | -| `updatedDate` | 日期 | 无 | 修改日期，适合在文章有实质更新时填写。 | -| `draft` | 布尔值 | `false` | `true` 时不生成文章路由，也不会出现在列表、RSS 和 sitemap 中。 | -| `slug` | 字符串 | 文件名/路径 | 自定义文章 URL slug。建议只使用稳定的英文、数字和短横线。 | -| `cover` | 字符串 | 无 | 文章卡片和文章 Banner 的封面 URL。支持绝对 URL 和项目内路径。 | -| `hero` | 字符串 | 无 | 兼容旧内容的 Banner 图片字段；没有 `cover` 时可作为图片来源。 | -| `categories` | 字符串数组 | `[]` | 文章分类，例如 `[随笔, 写作]`。 | -| `tags` | 字符串数组 | `[]` | 文章标签，例如 `[Astro, 前端]`。 | -| `textTone` | `light` / `dark` / `auto` | 无 | Banner 文字颜色。`auto` 会在图片加载后根据图片亮度判断。 | -| `toc` | 布尔值或对象 | `false` | 是否显示目录。对象可设置 `enabled` 和 `position: left/right`。 | -| `comments` | 布尔值 | `false` | 是否显示 Twikoo 评论区；还需要先在站点配置中启用 Twikoo。 | -| `math` | 布尔值 | `false` | 是否加载 KaTeX，用于 LaTeX 数学公式。 | -| `mermaid` | 布尔值 | `false` | 是否加载 Mermaid，用于 `mermaid` 代码块。 | - -Frontmatter 必须放在 Markdown 文件开头的两个 `---` 之间。数组可以使用行内格式，也可以使用多行格式： - -```yaml -categories: - - 随笔 - - 写作 -tags: - - Astro - - 网站 -``` - -目录配置示例： - -```yaml -toc: - enabled: true - position: left -``` - -文章卡片在构建时按以下顺序选择图片：`cover`、兼容旧内容的 `hero`、Markdown/MDX 正文中的第一张标准 Markdown 图片或 HTML `img`，最后使用 `siteConfig.cards.defaultCovers` 中的确定性候选图片。正文中的相对图片地址会根据最终文章 URL 解析，例如 `/posts/hello/` 中的 `images/photo.jpg` 会解析为 `/posts/hello/images/photo.jpg`。如果 `defaultCovers` 为空且没有其他图片，卡片会使用确定性的纯色背景作为兜底。 - -如果文章没有 `cover` 或 `hero`，只在正文中添加图片也可以： - -```md -![Article image](./images/article.jpg) -``` - -`src/content/posts/first-light.md`、`content-workflow.md` 和 `quiet-default.md` 分别演示了 Frontmatter 封面、正文图片和默认封面路径。 - -`draft: true` 会将文章从文章列表、RSS、sitemap 和生成路由中排除。`toc` 也可以直接设置为 `true` 或 `false`；对象形式支持 `position: left` 或 `right`。目录标题由 Astro `render()` 返回的 headings 生成，并使用真实的 `#slug` 锚点。桌面端显示侧边目录，较小屏幕使用原生 `details` 控件，不会导致页面整体偏移。 - -包含 LaTeX 公式时设置 `math: true`。Markdown 通过 `remark-math` 和 `rehype-katex` 构建，只有这些页面会加载 KaTeX CSS。这是构建时渲染，不会加载 MathJax。 - -包含 `mermaid` 代码块时设置 `mermaid: true`。Mermaid 只会在这些页面中动态加载，渲染主题会跟随当前深色模式设置。 - -## 路由和工具 - -- `/` 是文章首页；`/posts/.../` 是公开文章页面。 -- `/about/` 和其他非保留路径由 `src/content/pages` 生成。 -- `/archives/`、`/categories/.../` 和 `/tags/.../` 提供归档及分类、标签页面。 -- `/rss.xml` 是公开文章 RSS Feed。 -- `/sitemap-index.xml` 由 `@astrojs/sitemap` 生成；`/robots.txt` 会将搜索引擎指向 sitemap。 -- `build` 会为 `dist` 生成 Pagefind 索引；也可以使用 `search:index` 单独重新生成索引。 -- Twikoo 通过 `siteConfig.comments` 按需启用。浏览器端 CDN 地址固定使用已安装的 `twikoo` `1.7.15` 版本，并以延迟方式加载评论和评论数量。 - -## Markdown 短代码 - -短代码由 `src/lib/shortcodes.ts` 在构建时处理；现有 `.md` 文件继续支持，不需要迁移到 MDX。块级语法是 `[name key="value"]...[/name]`；GitHub 卡片还支持 `[github repo="owner/repo" /]`；`[!] text` 和 `[!/ ] text` 是行内提示。属性支持 ASCII 引号、中文排版引号、不加引号的值和布尔标记。代码围栏不会被短代码处理。 - -| 语法 | 支持情况 | 说明 | -| --- | --- | --- | -| `[!]`、`[!/ ]` | 支持 | 行内提示，仅识别这些明确形式 | -| `button`、`btn` | 支持 | 支持 `href`、`url` 或 `link`；仅允许 http/https/mailto/tel 和相对地址 | -| `file` | 支持 | URL 规则与按钮相同 | -| `tag`、`label` | 支持 | `type` 支持 primary、success、warning、danger、info、default；支持 `outline` | -| `hint`、`tip` | 支持 | `type` 支持 warn、warning、error、danger、success、info；可选 `title` | -| `collapse` | 支持 | 使用原生且可访问的 `details`/`summary`；支持 Markdown 和嵌套折叠 | -| `tabs`、`tab` | 支持 | 静态可访问标签页，通过少量原生客户端脚本切换；多个实例互不影响 | -| `github` | 支持 | 构建时生成 GitHub 仓库卡片，并验证 `owner/repo`。可选 `description`、`stars`、`forks`、`lastCommit` 或 `commitDate`、`readMore`、`download` | -| 未知或不安全的值 | 安全兜底 | 无效链接和仓库会作为普通文本输出 | - -`selected` 用于指定初始标签页。执行 `build` 时，`[github repo="owner/repo" /]` 使用的仓库会从 GitHub 公开仓库 API 获取，并缓存到 `.astro-cache/github.json`，缓存时间为 24 小时。可以设置 `GITHUB_CACHE_TTL_MS` 或 `GITHUB_API_TIMEOUT_MS` 调整默认值，也可以设置 `GITHUB_TOKEN` 以提高 API 访问限制；Token 不会写入缓存或构建输出。项目只使用公开仓库元数据。API 出错或处于开发模式时，会安全降级为仓库链接和 `—`，不会阻断构建。短代码中显式填写的属性始终优先于 API 数据；`readMore` 默认使用 `html_url`，`download` 使用 API 返回的 `default_branch`。浏览器端不会请求 GitHub API。已移除的短代码会触发构建错误，而不会作为普通 Markdown 输出。 +- 美观、简洁、耐看； +- 页面自适应，根据屏幕大小判断显示顶栏或侧栏； +- 完美支持 Pjax 无刷新加载； +- 支持用户前端深浅色模式切换、字体切换、字体大小调整等功能； +- 支持 LaTeX 数学公式解析； +- 支持多样的短代码； +- 原生支持友链卡片。 diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro index 5b904b1..765c616 100644 --- a/src/layouts/BaseLayout.astro +++ b/src/layouts/BaseLayout.astro @@ -13,7 +13,7 @@ import '../styles/global.css'; interface Props { title?: string; description?: string; image?: string; type?: 'website' | 'article'; noindex?: boolean; math?: boolean; navbarOverlay?: boolean; } const { title, description, image, type, noindex, math, navbarOverlay = false } = Astro.props; const hasMasthead = Astro.slots.has('masthead'); - const appearanceScript = `(function(){var r=document.documentElement,t='mirages-theme',s='mirages-font-scale',f='mirages-font-family',themes=['auto','light','sunset','dark'],fonts=['serif','sans'],stored=Number(localStorage.getItem(s)),scale=stored>=.8&&stored<=1.5?stored*100:stored>=80&&stored<=150?stored:100,theme=localStorage.getItem(t),font=localStorage.getItem(f);scale=Math.round(scale/5)*5;r.dataset.theme=themes.indexOf(theme)>-1?theme:'${siteConfig.appearance.defaultTheme}';r.dataset.font=fonts.indexOf(font)>-1?font:'sans';r.style.fontSize=scale+'%'})();`; + const appearanceScript = `(function(){var r=document.documentElement,t='mirages-theme',s='mirages-font-scale',f='mirages-font-family',themes=['auto','light','sunset','dark'],fonts=['serif','sans'],stored=Number(localStorage.getItem(s)),scale=stored>=.8&&stored<=1.5?stored*100:stored>=80&&stored<=150?stored:100,theme=localStorage.getItem(t),font=localStorage.getItem(f);scale=Math.round(scale/5)*5;r.dataset.theme=themes.indexOf(theme)>-1?theme:'${siteConfig.appearance.defaultTheme}';r.dataset.font=fonts.indexOf(font)>-1?font:'sans';r.dataset.platform=/Win/.test(navigator.userAgentData?.platform||navigator.platform)?'windows':'other';r.style.fontSize=scale+'%'})();`; const tabsScript = `document.addEventListener('click',function(event){var button=event.target.closest('[data-shortcode-tab]');if(!button)return;var group=button.closest('[data-shortcode-tabs]');var id=button.dataset.shortcodeTab;group.querySelectorAll('[data-shortcode-tab="'+id+'"]').forEach(function(tab){var active=tab===button;tab.setAttribute('aria-selected',String(active));tab.tabIndex=active?0:-1;var panel=group.querySelector('#'+tab.getAttribute('aria-controls'));if(panel)panel.hidden=!active;});});`; const collapseScript = `document.querySelectorAll('.shortcode-collapse').forEach(function(details){details.dataset.collapseReady='';details.classList.toggle('is-expanded',details.open);var body=details.querySelector(':scope>.shortcode-body');if(body instanceof HTMLElement&&details.open)body.style.height='auto';});document.addEventListener('click',function(event){var summary=event.target.closest('.shortcode-collapse>summary');if(!summary)return;var details=summary.parentElement;if(!(details instanceof HTMLDetailsElement))return;event.preventDefault();var body=details.querySelector(':scope>.shortcode-body');if(!(body instanceof HTMLElement))return;var expand=!details.classList.contains('is-expanded');details.classList.toggle('is-expanded',expand);if(matchMedia('(prefers-reduced-motion: reduce)').matches){details.open=expand;body.style.height=expand?'auto':'';delete details.dataset.animating;return;}var height=body.getBoundingClientRect().height;details.open=true;body.style.height=height+'px';void body.offsetHeight;details.dataset.animating='true';body.style.height=(expand?body.scrollHeight:0)+'px';});document.addEventListener('transitionend',function(event){var body=event.target;if(!(body instanceof HTMLElement)||!body.classList.contains('shortcode-body')||event.propertyName!=='height')return;var details=body.parentElement;if(!(details instanceof HTMLDetailsElement))return;var expanded=details.classList.contains('is-expanded');details.open=expanded;body.style.height=expanded?'auto':'';delete details.dataset.animating;});`; --- diff --git a/src/pages/posts/[...slug].astro b/src/pages/posts/[...slug].astro index f32cb1e..72a1a35 100644 --- a/src/pages/posts/[...slug].astro +++ b/src/pages/posts/[...slug].astro @@ -42,7 +42,7 @@ const dateText = `${date.year} 年 ${date.month} 月 ${date.day} 日`;
{tags.length > 0 &&
- {tags.map((tag) => #{tag})} + {tags.map((tag) => #{tag})}
}