⭐ 开源博客 Litos 使用指南

⭐ Litos 开源项目使用指南

本指南将带你理解 Litos 主题的结构、配置方式、内容写法，以及如何按需扩展页面。
库地址：github.com/Dnzzk2/Lito…

---

目录

1. 项目结构总览
2. 内容系统（Markdown / MDX）
3. Posts（文章）
4. Photos（照片）：配置与渲染机制
5. Markdown 扩展语法（Callouts、代码美化、图片、视频）
6. 评论系统（Comment 模块）
7. 如何新增你的个人页面
8. 如何禁用或移除某些模块
9. 常见开发命令（pnpm）

---

1. 项目结构总览

Litos 采用 Astro + React 的混合架构。核心目录结构如下：

src/
  components/  <-- UI 组件（Header / Footer / 卡片等）
  content/     <-- 所有 Markdown 内容(posts/photos/etc)
  pages/       <-- 页面路由（首页、文章详情、列表页等）
  layouts/     <-- Astro 布局模板
  config.ts    <-- 全站可配置内容

三者的关系：

目录	作用	你要改什么
src/pages/	控制页面结构（如首页、文章列表）	新增页面、改布局
src/components/	单独组件（按钮、卡片、评论等）	UI 样式、组件风格
src/content/	所有可写内容（文章 / 照片）	写文章、加照片

---

2. 内容系统（Markdown / MDX）

Litos 使用 Astro Content Collections。
你所有文章都放在：

src/content/posts

照片放在：

src/content/photos

每篇文章都包含 frontmatter，例如：

---
title: '文章标题'
description: '文章描述'
pubDate: 2025-08-20
tags: ['TagA', 'TagB']
---
正文……

Astro 会自动读取并生成文章列表页和详情页。

---

3. Posts（文章系统）

文章详情渲染文件：
src/pages/posts/[...id].astro

如果你写：

src/content/posts/my-first-post.md

访问路径就是：

/posts/my-first-post

文章底部 可包含评论模块（后面会讲如何关闭）。

---

4. Photos（照片系统）

（已完全整合你刚提交的文件内容）

4.1 Photos 配置文件路径

src/config.ts

其中的配置如下：

export const PHOTOS_CONFIG = {
  enabled: true, // 是否开启 Photos 页面
}

如果你不需要这个功能：

enabled: false

即可完全关闭，并自动隐藏导航链接。

---

4.2 Photos 数据结构定义

路径：

src/content/photos/_schema.ts

定义了照片集合的字段类型：

export interface PhotosList {
  title: string
  date: string
  thumbnail: string
  description?: string
  images: Photo[]
}

单张照片（Photo）包含：

export interface Photo {
  url: string
  alt: string
  width: number
  height: number
  tags?: string[]
}

意味着你必须提供：

字段	描述
url	图片路径
alt	图片简介
width / height	原图尺寸
tags	可用于过滤和展示

配合 Astro 的 image component，会自动生成优化后的图像。

---

4.3 Photos 页面渲染逻辑

路径：

src/pages/photos/index.astro

流程如下：

1. 读取 PHOTOS_CONFIG.enabled
2. 读取所有 src/content/photos/*.md 文件
3. 把每个 PhotosList 的封面图渲染成展示卡片
4. 点击后进入照片页内容

---

5. Markdown 扩展语法（你提供的完整版本）

Litos 增加了大量 Markdown 拓展（非常适合写技术博客）。以下是完整说明。

---

5.1 Callouts（提示块）

格式：

> [!NOTE]
> 内容

类型包括：

类型	效果
NOTE	蓝色信息提示
TIP	绿色建议
IMPORTANT	橙色重点
WARNING	黄色警告
DANGER	红色危险

---

5.2 代码高亮（Expressive Code）

支持：

• 行高亮
• 行号
• 自动换行
• 文件名显示
• Diff 模式

示例：

```ts title="example.ts" {1-2}
console.log('hello')
console.log('world')
```

---

5.3 图片（figure）扩展

图片 + 标题

![Alt 文本](./image.png){figure="图片标题"}

---

5.4 图片 + 外链（image-a）

![点击跳转](./image.png){a="https://google.com"}

---

5.5 Polaroid 风格（宝丽来）

![Alt 文本](./a.png){polaroid}

---

5.6 视频嵌入（本地视频）

!video[描述](./video.mp4)

---

5.7 Styled Link（带图标链接）

:link[Astro]{id=https://astro.build}

会自动渲染成按钮状链接。

---

6. 评论系统（Comment 模块）

你提供的代码：

src/components/posts/base/Comment.astro

解析如下：

const { enabled, system } = COMMENT_CONFIG

if (!enabled || system === 'none') return null

来自：

src/config.ts

✔ 关闭评论（推荐）

COMMENT_CONFIG: {
  enabled: false,
}

整个评论模块全站自动隐藏。

---

✔ 只取消文章底部区域

在：

src/pages/posts/[...id].astro

找到：

<Comment id={post.id} title={frontmatter.title} />

将其删除或注释即可：

<!-- <Comment id={post.id} title={frontmatter.title} /> -->

---

7. 如何新增你的个人页面（About / Resume / Projects）

例如新增 /about：

1. 创建文件

src/pages/about.astro

2. 写内容

---
import Layout from '~/layouts/BaseLayout.astro'
---

<Layout title="About Me">
  <section class="prose">
    <h1>关于我</h1>
    <p>这里写你的内容...</p>
  </section>
</Layout>

3. 更新导航
   修改：

src/config.ts

添加：

{ name: 'About', url: '/about' }

---

8. 如何移除模块（Photos / Projects / 评论等）

想隐藏导航链接？

修改：

HEADER_LINKS

想彻底禁用 Photos 页面？

PHOTOS_CONFIG.enabled = false

想删除评论？

COMMENT_CONFIG.enabled = false

或删除组件引用。

---

9. pnpm 命令说明

命令	用途
pnpm install	安装依赖
pnpm dev	开发模式（本地预览）
pnpm build	生产环境打包
pnpm preview	本地预览打包结果

顺序无要求，只需：

• 第一次 → pnpm install
• 开发 → pnpm dev
• 部署 → pnpm build && pnpm preview

---