这个主题是我在业余时间开发的，文档可能不够全面，但我会尽力解释。

前提条件

在开始之前，请确保你的开发环境中已安装以下工具：

• Node.js - 运行开发环境所必需。
• pnpm - 我们首选的包管理器，用于依赖管理。
• Git - 用于版本控制和项目管理。
• VS Code - 推荐使用的代码编辑器，开发体验极佳。

启动项目

有两种方式：

• Fork 仓库
• 使用此模板 - 将来会推出无内容分支，无需删除和替换内容。

获取你自己的仓库后，可以将其克隆到本地。

更新主题

当主题发布新版本时，你可以按照以下步骤拉取最新更改而不丢失内容：

1. 添加 upstream 远程（只需一次）

git remote add upstream https://github.com/Dnzzk2/Litos.git

2. 获取并合并最新的主题

git fetch upstream
git merge upstream/main --no-edit

3. 解决冲突（如有）

冲突通常只发生在你修改过的文件中，例如 src/config.ts。在这种情况下，只需保留你自己的配置，接受其余的主题更新即可。

结束

后续文档将分为多个页面，如 readme、posts…

以下文件与此文档兼容：

• src/pages/index.astro - readme 页面。
• src/config.ts - readme 页面配置。
• src/components/base - 大部分组件来自这里。

站点配置

配置基本站点信息：

export const SITE: Site = {
  title: 'Litos',
  description: 'Litos is a blog theme built with Astro.js and 夜猫子Ai手记.',
  website: 'https://litos.vercel.app/',
  lang: 'en',
  base: '/',
  author: '夜猫子Ai手记',
  ogImage: '/og-image.jpg',
}

顶部链接

顶部跳转链接组件配置：

export const HEADER_LINKS: Link[] = [
  {
    name: 'Posts',
    url: '/posts',
  },
]

底部链接

底部链接组件配置：

export const FOOTER_LINKS: Link[] = [
  {
    name: 'Readme',
    url: '/',
  },
]

社交链接

在 readme 页面中，你可以在主题介绍下方看到一排图标，可以通过以下方式配置。图标来自 Iconify。

export const SOCIAL_LINKS: SocialLink[] = [
  {
    name: 'github',
    url: 'https://github.com/yourname',
    icon: 'icon-[ri--github-fill]',
    count: 11,
  },
  {
    name: 'twitter',
    url: 'https://x.com/yourname',
    icon: 'icon-[ri--twitter-x-fill]',
  },
]

聚光灯

技能展示

在 readme 页面中，你可以看到一个技能展示区域，可以通过配置以下代码来展示你的技能：

export const SKILLSSHOWCASE_CONFIG: SkillsShowcaseConfig = {
  SKILLS_ENABLED: true,
  SKILLS_DATA: [
    {
      direction: 'left',
      skills: [
        {
          name: 'JavaScript',
          icon: 'icon-[mdi--language-javascript]',
        },
        {
          name: 'CSS',
          icon: 'icon-[mdi--language-css3]',
        },
        {
          name: 'HTML',
          icon: 'icon-[mdi--language-html5]',
        },
        {
          name: 'TypeScript',
          icon: 'icon-[mdi--language-typescript]',
        },
      ],
    },
  ],
}

文章

这里主要展示置顶文章。如果没有置顶文章，我们将根据 POSTS_CONFIG 显示最新 size 数量的文章。

以下文件与此文档兼容：

• src/pages/posts/[...id].astro - 文章具体内容显示页面。
• src/pages/posts/[...page].astro - 文章列表页面。
• src/content/posts - 文章集合
• src/content.config.ts - 文章数据集和前置数据配置。
• ec.config.mjs - expressiveCode 配置。
• plugins/index.ts - remark 和 rehype 插件。
• src/config.ts - 文章页面配置。
• src/components/posts - 大部分组件来自这里。

文章页面配置

文章页面配置如下：

export const POSTS_CONFIG: PostConfig = {
  title: 'Posts',
  description: 'Posts by 夜猫子Ai手记',
  introduce: 'Here, I will share the usage instructions for this theme to help you quickly use it.',
  author: '夜猫子Ai手记',
  homePageConfig: {
    size: 3,
    type: 'compact',
  },
  postPageConfig: {
    size: 10,
    type: 'minimal',
  },
  tagsPageConfig: {
    size: 10,
    type: 'time-line',
  },
  ogImageUseCover: false,
  postType: 'metaOnly',
  imageDarkenInDark: true,
  readMoreText: 'Read more',
  prevPageText: 'Previous',
  nextPageText: 'Next',
  tocText: 'On this page',
  backToPostsText: 'Back to Posts',
  nextPostText: 'Next Post',
  prevPostText: 'Previous Post',
  recommendText: 'REC',
}

以下是一些配置属性的详细说明，请参考下表。

Type 和 PostType

在上面的文档中，我们提到了可配置的 types 用于配置 readme 页面、文章页面和标签页面的列表数据显示样式，以及可配置的 postTypes 用于在文章内容页面顶部显示元数据。

以下是 type 的具体样式展示：

以下是 postType 的具体样式展示：

前置数据

讨论完文章列表和整体设计后，让我们一起看看文章的内容。这些内容都在 src/content/posts 文件夹中。

下面是文章内容的前置数据：

---
title: 'Litos: Posts Page Config'
description: ''
pubDate: 2025-08-13
author: '夜猫子Ai手记'
recommend: true
tags: ['Litos', 'Documentation']
---

你可以通过以下代码配置文章内容的前置数据：

const posts = defineCollection({
  loader: glob({
    pattern: '**/*.{md,mdx}',
    base: './src/content/posts',
  }),
  schema: ({ image }) =>
    z
      .object({
        title: z.string(),
        description: z.string(),
        pubDate: z.date(),
        tags: z.array(z.string()).optional(),
        updatedDate: z.date().optional(),
        author: z.string().default(POSTS_CONFIG.author),
        cover: image().optional(),
        ogImage: image().optional(),
        recommend: z.boolean().default(false),
        postType: z.custom<PostType>().optional(),
        coverLayout: z.custom<CoverLayout>().optional(),
        pinned: z.boolean().default(false),
        draft: z.boolean().default(false),
      })
      .transform((data) => ({
        ...data,
        ogImage: data.ogImage ? data.ogImage : POSTS_CONFIG.ogImageUseCover && data.cover ? data.cover : undefined,
      })),
})

语法和代码样式

本指南将通过一个 3 天城市旅行行程来展示如何使用 Markdown 格式化文本。在规划行程的同时学习 Markdown！

标题级别

对于旅行笔记，多级标题有助于组织天数、时间块和提示：

文本格式化

撰写旅行笔记时，突出重要信息：

必看景点 应加粗 灵活时间 使用斜体 重要警告 可以同时使用 可选绕路 使用删除线

行李清单（无序列表）

• 护照、签证
• 相机、备用电池
  • 带一个快充充电器
  • 备用 SD 卡
• 可重复使用的水瓶
• 公共交通卡

第一天行程（有序列表）

1. 机场 → 酒店入住
2. 老城徒步之旅
3. 夜间游船
   1. 提前 15 分钟到达
   2. 在 B 入口排队
   3. 推荐靠窗座位

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

Blockquotes

Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.

Save the hotel address in offline maps for quick access.

> Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.
>
> Save the hotel address in offline maps for quick access.

代码块

使用简单的代码来估算预算：

type Budget = { flight: number; hotel: number; meals: number; transport: number }
export const total = (b: Budget) => b.flight + b.hotel + b.meals + b.transport

console.log(total({ flight: 1200, hotel: 450, meals: 180, transport: 60 })) // 1890

表格

示例行程：

链接和图片

更多提示：官方旅游委员会

旅行照片：

水平分隔线

行内代码

地铁 A 线在高峰期每 5-7 分钟一班。

数学公式

每日预算估算：budget=hotel+meals+transportbudget = hotel + meals + transportbudget=hotel+meals+transport

总行程：

任务列表

出行前检查清单：

• 预订航班
• 预订酒店
• 购买地铁通票
• 下载离线地图

脚注

本行程参考了当地旅游指南（点击脚注）¹。

Expressive-code 配置

在 Markdown 文档中，我们使用代码块来显示代码片段和其他内容。本文档介绍如何自定义代码块配置。

本主题的代码块使用 Expressive Code 进行配置，所有配置选项都在 ec.config.mjs 文件中定义。以下是主要配置选项：

import { defineEcConfig } from 'astro-expressive-code'
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'

export default defineEcConfig({
  defaultLocale: 'zh-CN',
  defaultProps: {
    wrap: false,
    collapseStyle: 'collapsible-auto',
    showLineNumbers: false,
    preserveIndent: true,
  },
  minSyntaxHighlightingColorContrast: 0,

  styleOverrides: {
    uiFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    uiFontSize: '1em',
    codeFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    codeFontSize: '14px',
    codeLineHeight: '1.4',
    borderRadius: '0',
    codePaddingBlock: '0.8571429em',
    codePaddingInline: '1.1428571em',
    borderColor: ({ theme }) => (theme.type === 'dark' ? '#24273a' : '#e6e9ef'),

    frames: {
      frameBoxShadowCssValue: false,
      inlineButtonBackgroundActiveOpacity: '0.2',
      inlineButtonBackgroundHoverOrFocusOpacity: '0.1',
    },
    textMarkers: {
      backgroundOpacity: '0.2',
      borderOpacity: '0.4',
    },
  },

  plugins: [
    pluginCollapsibleSections({
      defaultCollapsed: false,
    }),
    pluginLineNumbers(),
  ],

  themes: ['catppuccin-macchiato', 'catppuccin-latte'],
  themeCssSelector: (theme) => (theme.name === 'catppuccin-macchiato' ? '.dark' : ':root:not(.dark)'),
  useDarkModeMediaQuery: false,
  useStyleReset: false,
})

你可以访问该网站查看 expressive-code 的配置选项。

评论系统 (Gitalk)

该主题内置了 Gitalk 评论系统，使用 GitHub Issues 作为评论后端。每篇文章会自动获得自己的 Issues 用于评论。

前提条件

首先你需要创建一个 GitHub OAuth App：

1. 前往 GitHub 开发者设置 → OAuth Apps → New OAuth App。
2. 填写表单：
   • Application name：任意名称（例如 My Blog Comments）
   • Homepage URL：你的站点 URL（例如 https://yourdomain.com）
   • Authorization callback URL：与你的站点 URL 相同
3. 创建后，复制 Client ID 并生成 Client Secret。
4. 在 GitHub 上创建一个 公开仓库 用于存储评论 Issues（例如 blog-comments）。

配置

在 src/config.ts 中配置评论系统：

export const COMMENT_CONFIG: CommentConfig = {
  enabled: true,
  system: 'gitalk',
  gitalk: {
    clientID: import.meta.env.PUBLIC_GITHUB_CLIENT_ID,
    clientSecret: import.meta.env.PUBLIC_GITHUB_CLIENT_SECRET,
    repo: 'blog-comments',
    owner: 'YourGitHubUsername',
    admin: ['YourGitHubUsername'],
    language: 'en-US',
    perPage: 5,
    pagerDirection: 'last',
    createIssueManually: false,
    distractionFreeMode: false,
    enableHotKey: true,
  },
}

然后设置环境变量。在项目根目录创建 .env 文件（参考 .env.example）：

PUBLIC_GITHUB_CLIENT_ID=your-github-client-id
PUBLIC_GITHUB_CLIENT_SECRET=your-github-client-secret

配置属性

This guide has made slight changes based on the markdown-mdx-extended-features.

Callouts

Supported by the rehype-callouts , you can configure the plugin in plugins/index.ts.

If you change the theme configuration (default: 'vitepress'), you will also need to update the imported CSS file in src/styles/pro.css (@import 'rehype-callouts/theme/yourconfig').

<!-- Callout type names are case-insensitive: 'Note', 'NOTE', and 'note' are equivalent. -->

<!-- vitepress -->

<!-- This is a _non-collapsible_ callout -->

> [!note]
> Note content.

> [!tip]
> Tip content.

> [!important]
> Important content.

> [!warning]
> Warning content.

> [!caution]
> Caution content.

> [!caution]- This is a **collapsible** callout
> Caution content.

> [!note]+ This is a **collapsible** callout
> Note content.

Fully-featured Code Blocks

Supported by astro-expressive-code with @expressive-code/plugin-collapsible-sections and @expressive-code/plugin-line-numbers plugins to add styling and extra functionality for code blocks.

To customize code block themes or functionality, modify the ec.config.mjs file at the project root after reviewing the Configuring Expressive Code, such as change themes, enable word wrap, or toggle line numbers.

Here’s a quick preview of what’s possible. Check the detailed guide for more info.

Syntax highlighting

console.log('This code is syntax highlighted!')

ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline

Code editor frames

// Use `title="my-test-file.js"`
console.log('Title attribute example')

// src/content/index.ts
// Use `// src/content/index.ts`
console.log('File name comment example')

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// 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>

Adding long labels on their own lines

// 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>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

// Plaintext search strings
function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported'
}

Marking individual text inside lines

// Regular expressions
console.log('The words yes and yep will be marked.')

# Regular expressions
echo "Test" > /home/test.txt

// Regular expressions
If you only want to mark certain parts matched by your regular expression, you can use capture groups.

For example, the expression `/ye(s|p)/` will match yes and yep, but only mark the character s or p:

// Regular expressions
To prevent this special treatment of capture groups, you can convert them to non-capturing groups by adding ?: after the opening parenthesis. For example:

This block uses `/ye(?:s|p)/`, which causes the full
matching words "yes" and "yep" to be marked.

// Selecting inline marker types (mark, ins, del)
function demo() {
  console.log('These are inserted and deleted marker types')
  // The return statement uses the default marker type
  return true
}

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

// Changing the starting line number
console.log('Greetings from line 5!')
console.log('I am on line 6')

Image Caption & Link

Use the :::image directive from remark-directive-sugar to wrap images in a container for captions, clickable links, and more. Customize via the image option in plugins/index.ts (remarkDirectiveSugar) and style under /* :::image */ in src/styles/pro.css.

image-figure

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[This Is a **Figcaption** with _`<figure>` Attrs_]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::

:::image-figure[This is a **figcaption** with _`<img>` attrs_.]
![](assets/cover.png)(style: width:600px;)
:::

<!-- 💡 Use `(class:no-zoom)` to disable zoom -->

:::image-figure[This is a **figcaption** with `class:no-zoom`.]
![](assets/cover.png)(class:no-zoom)
:::

<!-- 💡 If no `[caption]`, use `[alt]` as figcaption. -->

:::image-figure
![If `[caption]` not set, the alt text from `![]()` will be used as the figcaption.](assets/cover.png)
:::

<!-- 💡 Images for light (img-light) and dark (img-dark) modes -->
<!-- ⚠️ At least one line must separate two image syntaxes (![]()), or won't work. -->

:::image-figure[This example shows different images for light (add `class:img-light`) and dark (add `class:img-dark`) modes.]
![](assets/image-16-9-light.png)(class:img-light)

![](assets/image-16-9-light.png)(class:img-dark)
:::

<!-- ❌ If no text is available for the figcaption, it won't work.  -->

:::image-figure
![](assets/cover.png)
:::

image-a

The custom directive wraps an image inside a link, making it clickable.

:::image-a{<a> attrs}: Define the link (href), styles, or classes in the curly braces for <a> element.

![alt](image path)(<img> attrs): Same as above.

:::image-a{href="https://github.com/Dnzzk2/Litos"}
![OG image](assets/cover.png)
:::

:::image-a{href="https://github.com/Dnzzk2/Litos" style="display:block" .custom-class}
![OG image](assets/cover.png)(style: margin-bottom: -1rem; transform:scaleX(1.1) scaleY(1.1);, loading: eager)
:::

::::image-a{href="https://github.com/Dnzzk2/Litos"}
:::image-figure[This example shows `:::image-a` wraps around `:::image-figure` (both are interchangeable).]
![OG image](assets/cover.png)
:::
::::

<!-- ❌ No external links provided, it won't work.-->

:::image-a
![OG image](assets/cover.png)
:::

image-figure-polaroid

Polaroid style images with a border and shadow.

In order to ensure the style size on the phone, I have set a minimum width of 300px, and you can modify and expand the style in src/styles/picture.css.

:::::image-div-polaroid
:::image-figure-polaroid[This is a **figcaption** with _`<img>` attrs_.]
![OG image](assets/cover.png)
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)

cover.png
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)
:::
:::::

<!-- change style -->

:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::

This is a figcaption with <img> attrs.

cover.png

GitHub Card

Congratulations from oopsunix

::github{repo="Dnzzk2/Litos"}

Video Embedding

Use the ::video directive from remark-directive-sugar for consistent video embedding across different platforms. Customize via the video option in plugins/index.ts and style under /* ::video */ in src/styles/pro.css.

Say example.md contains:

<!-- Embed a YouTube video -->

::video-youtube{#gxBkghlglTg}

<!-- Embed a Bilibili video with a custom `title` attr -->

::video-bilibili[custom title]{id=BV1MC4y1c7Kv}

<!-- Embed a Vimeo video with class `no-scale` to disable scaling -->

::video-vimeo{id=912831806 class='no-scale'}

<!-- ::video-vimeo{id=912831806 .no-scale} -->

<!-- Embed a custom video URL (must use `id`, not `#`) -->

::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}

Then example.mdx renders as:

Styled Link（:link）

Use the :link directive from remark-directive-sugar to add links with avatars or favicons for GitHub, npm, or custom URLs. Customize via the link option in plugins/index.ts and style under /* :link */ in src/styles/pro.css.

Link to a GitHub user or organization (prepend id with @)

Example 1: :link[Dnzzk2]{#@Dnzzk2} links to the GitHub profile of the project maintainer, Dnzzk2.

Example 2: Vite links to the GitHub profile of the Vite organization.

Example 3: :link{#@Dnzzk2 tab=repositories} links directly to the repositories tab of the GitHub user, like Dnzzk2. For GitHub users, valid tab options: 'repositories','projects', 'packages', 'stars', 'sponsoring', 'sponsors'.

Example 4: :link{#@vitejs tab=org-people} links directly to the people section of a GitHub organization, like vitejs. For GitHub organizations, valid tab options: 'org-repositories', 'org-projects', 'org-packages', 'org-sponsoring', and 'org-people'.

Link to a GitHub repository

Example 5: :link[Astro]{#withastro/astro} or Astro creates a link to Astro repo.

Link to an npm package

Example 6: :link{#remark-directive-sugar} links to the npm homepage of the remark-directive-sugar.

Example 7: :link{id=remark-directive-sugar tab=dependencies} links to the dependencies section of the remark-directive-sugar on npm. For npm package, valid tab options: 'readme', 'code', 'dependencies', 'dependents', and 'versions'.

Link to a custom URL (must use id, not #)

Example 8: :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} creates an external link to the developer.mozilla.org/en-US/docs/Web....

Example 9: Google creates an external link to the Google.

Customization

Example 10: Vite creates a Vite to https://vite.dev/ instead of https://github.com/vitejs by using the url.

Example 11: Vite creates a Vite that displays a custom logo by using the img.

Example 12: :link{id=Dnzzk2/Litos class=github} creates a Dnzzk2/Litos with class=github (or .github) to override the default style of a GitHub repository.

Example 13: Litos Themes fully customizes a link. Litos Themes

Badges

Use the :badge directive from remark-directive-sugar to display small pieces of information, such as status or category.

The theme provides the following one predefined badges. You can customize them via the badge option in plugins/index.ts and style them under /* :badge */ in src/styles/pro.css.

• badge-n: NEW

Additionally, you can direct use :badge[text]{attrs} for easy visual customization of badges. For example: :badge[ISSUE]{style="background-color: #bef264"} will display as ISSUE. If no color is specified, the default appearance will look like This.

Details Dropdown

:::details
::summary[Details Dropdown]

- List item 1
- List item 2
- List item 3
- List item 4
  :::

• List item 1
• List item 2
• List item 3
• List item 4

Additionally, it also supports usage similar to the examples in remark-directive.

由于项目和标签页配置内容较少，因此合并为一个文档。

以下文件与此文档兼容：

• src/pages/projects/index.astro - 项目页面。
• src/pages/tags/index.astro - 标签统计页面。
• src/pages/tags/[tag]/[...page].astro - 特定标签的文章列表页面。
• src/config.ts - 项目和标签页配置。
• src/components/base - 大部分组件来自这里。

项目页面配置

配置页面文本：

export const PROJECTS_CONFIG: ProjectConfig = {
  title: 'Projects',
  description: 'The examples of my projects.',
  introduce: 'The examples of my projects.',
}

项目内容

项目页面显示的内容来自 /src/content/projects。

它的写作风格与文章类似：一个 MDX 文件代表一个项目。

项目前置数据

示例 (src/content/projects/Litos/index.mdx):

---
name: 'Litos'
description: 'A Simple & Modern Blog Theme for Astro.'
githubUrl: 'https://github.com/Dnzzk2/Litos'
website: 'https://litos.vercel.app/'
type: 'image'
icon: '../../../../public/projects/litos.png'
imageClass: 'w-10 h-10'
star: 32
fork: 7
---

标签页面配置

export const TAGS_CONFIG: TagsConfig = {
  title: 'Tags',
  description: 'All tags of Posts',
  introduce: 'All the tags for posts are here, you can click to filter them.',
}

本文档描述了照片页面的当前实现。

当前文件结构

• src/pages/photos/index.astro
  • 从 PHOTOS_CONFIG 读取页面文本
  • 从 PhotosList 读取时间线数据
• src/config.ts
  • 存储 PHOTOS_CONFIG
• src/lib/photos.ts
  • 存储 PhotosList
  • 自动导入照片文件
  • 将一个文件夹的图片转换为 Photo[]，使用 getPhotos()
• src/types.ts
  • 定义 PhotoData、Photo 和 PolaroidVariant
• src/components/photos/PolaroidCard.tsx
  • 将每个 variant 映射到实际的卡片尺寸

页面文本

页面标题和介绍文本来自 src/config.ts。

export const PHOTOS_CONFIG: PhotosConfig = {
  title: 'Photos',
  description: 'Here I will record some photos taken in daily life.',
  introduce: 'Here I will record some photos taken in daily life.',
}

src/pages/photos/index.astro renders the page like this:

---
import { PHOTOS_CONFIG } from '~/config'
import { PhotosList } from '~/lib/photos'

const { title, description, introduce } = PHOTOS_CONFIG
---

<Layout {title} {description}>
  <PageTitle {title} {introduce} />
  <PhotoTimeline photoData={PhotosList} />
</Layout>

PhotosList

PhotosList 在 src/lib/photos.ts 中定义。每一项是一个时间线条目。

export const PhotosList: PhotoData[] = [
  {
    title: 'Ningbo - Botanical Garden',
    icon: { type: 'emoji', value: '🌼' },
    description: 'It was early spring, so I went to see the cherry blossoms.',
    date: '2026-03-07',
    travel: '',
    photos: getPhotos('2026-03-07-botanicalGarden', 'Early spring cherry blossoms at the botanical garden', [
      '3x4',
      '3x4',
      '3x4',
      '3x4',
      '3x4',
      '3x4',
    ]),
  },
]

PhotoData 字段

getPhotos() 的工作原理

当前实现：

function getPhotos(dir: string, alt: string, variants: PolaroidVariant[]): Photo[] {
  return Object.entries(photoModules)
    .filter(([path]) => path.includes(`/${dir}/`))
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([, mod], index) => {
      const img = mod.default
      return {
        src: img,
        alt,
        width: img.width,
        height: img.height,
        variant: variants[index] || '4x3',
      }
    })
}

参数含义

重要行为

1. getPhotos() 首先按文件夹名称过滤所有导入的图片。
2. 然后使用 localeCompare 对匹配的文件路径进行排序。
3. 按排序顺序创建最终的 Photo[]。
4. variants[index] 应用于相同索引的图片。
5. 如果 variants 中缺少某个索引，该图片将回退到 '4x3'。

第三个参数如何匹配

第三个参数不是随机元数据。它是基于位置的。

对于以下代码：

photos: getPhotos('2026-03-07-botanicalGarden', 'Early spring cherry blossoms at the botanical garden', [
  '3x4',
  '3x4',
  '3x4',
  '3x4',
  '3x4',
  '3x4',
])

假设文件夹 src/assets/photos/2026-03-07-botanicalGarden/ 排序后包含以下文件：

01.webp
02.webp
03.webp
04.webp
05.webp
06.webp

那么映射关系是：

因此，如果你想让文件夹中的第一张照片使用 3x4，第三个数组的第一个元素必须是 3x4。

如果你想混合比例，请按照排序文件的相同顺序编写：

photos: getPhotos('2025-03-01-dongqianhu', 'Ningbo - Dongqian Lake', ['4x5', '1x1', '4x3'])

这意味着：

• 第一张排序后的图片 -> 4x5
• 第二张排序后的图片 -> 1x1
• 第三张排序后的图片 -> 4x3

如果文件夹中的照片多于数组长度：

photos: getPhotos('example-folder', 'Example alt', ['3x4', '4x5'])

那么：

• 第一张排序后的图片 -> 3x4
• 第二张排序后的图片 -> 4x5
• 第三张及之后的图片 -> 默认 4x3

支持的比例

当前 PolaroidVariant 为：

export type PolaroidVariant = '1x1' | '4x5' | '4x3' | '3x4' | '9x16'

src/components/photos/PolaroidCard.tsx 中的当前尺寸映射：

const polaroidVariants: Record<PolaroidVariant, string> = {
  '1x1': 'w-20 h-20',
  '4x5': 'w-20 h-24',
  '4x3': 'w-20 h-16',
  '3x4': 'w-[4.5rem] h-24',
  '9x16': 'w-20 h-32',
}

如何添加新的时间线条目

1. 在 src/assets/photos/ 下创建一个文件夹，例如 2026-04-01-spring-walk。
2. 将图片文件放入该文件夹。
3. 确保文件名按照排序后的顺序排列。
4. 在 src/lib/photos.ts 中向 PhotosList 添加一项。
5. 将第三个参数按照排序文件的相同顺序传递给 getPhotos()。

示例：

{
  title: 'Spring Walk',
  icon: { type: 'emoji', value: '🌿' },
  description: 'A short walk with a camera.',
  date: '2026-04-01',
  travel: '',
  photos: getPhotos(
    '2026-04-01-spring-walk',
    'Photos from a spring walk',
    ['3x4', '4x3', '4x5', '4x3']
  ),
}

注意事项

• alt 应用于从同一文件夹返回的每张照片。
• 顺序由排序后的文件路径决定，而不是编辑器中的导入顺序。
• 如果重命名文件，排序顺序可能会改变，variants 数组将映射到不同的照片。