Skip to main content
我的博客
Astro Modular 预览，显示不同的主题和布局选项

配置指南

Astro Modular • Version 1.0.0 •

本综合指南涵盖了设置和自定义模块化 Astro 博客所需的一切，专为想要以最小摩擦发布内容的 Obsidian 用户设计。

前置要求与设置

您需要：

  • Node.js 18+
  • pnpm（推荐）或 npm
  • 基本的 Markdown 知识
  • Obsidian（可选）

安装

# 安装 pnpm
npm install -g pnpm

# 安装依赖
pnpm install

# 预览
pnpm dev # 或 pnpm preview
# 访问 http://localhost:5000

# 构建生产版本
pnpm build

配置

核心设置

在 src/config.ts 中配置所有内容。配置分为几个部分：

网站信息

export const siteConfig = {
  // 网站信息
  site: "https://yourdomain.com",
  title: "您的博客标题",
  description: "您的博客描述",
  author: "您的名字",
  language: "zh-CN",
  
  // 全局设置
  theme: "oxygen", // 可用主题：oxygen, minimal, nord, dracula 等
  customThemeFile: "custom", // 仅在 theme 设置为 "custom" 时使用
  
  // 字体设置
  fonts: {
    source: "local", // "local" 自托管字体，"cdn" Google Fonts
    families: {
      body: "Inter",
      heading: "Inter",
      mono: "JetBrains Mono"
    },
    display: "swap"
  },
  
  // 布局
  layout: {
    contentWidth: "45rem"
  },
  
  // 目录
  tableOfContents: {
    enabled: true,
    depth: 4 // 包含在目录中的最大标题深度
  },
  
  // 页脚
  footer: {
    enabled: true,
    content: `© 2025 {author}. 使用 Astro Modular 主题构建。`,
    showSocialIconsInFooter: true
  }
}

主题

Astro Modular 包含 17+ 内置主题：

  • oxygen - 现代优雅（默认）
  • minimal - 简洁清爽
  • nord - 冷色调主题
  • dracula - 经典暗色
  • gruvbox - 复古风格
  • rose-pine - 柔和色彩
  • catppuccin - 柔和主题
  • ayu - 干净优雅
  • everforest - 自然色调
  • solarized - 经典设计
  • 等等…

在 src/config.ts 中更改主题：

theme: "oxygen" // 更改为任何可用主题

导航

navigation: {
  showNavigation: true,
  style: "traditional", // 'minimal' 或 'traditional'
  showMobileMenu: true,
  pages: [
    { title: "文章", url: "/posts" },
    { title: "项目", url: "/projects" },
    { title: "关于", url: "/about" }
  ],
  social: [
    {
      title: "GitHub",
      url: "https://github.com/yourusername",
      icon: "github"
    }
  ]
}

命令面板

commandPalette: {
  enabled: true,
  shortcut: "ctrl+K", // 或 "cmd+K"
  placeholder: "搜索文章",
  search: {
    posts: true,
    pages: false,
    projects: false,
    docs: false
  },
  quickActions: {
    enabled: true,
    toggleMode: true, // 明暗模式切换
    graphView: true, // 图表视图
    changeTheme: true // 主题切换器
  }
}

首页选项

homeOptions: {
  featuredPost: {
    enabled: true,
    type: "latest", // "latest" 或 "featured"
    slug: "getting-started" // 仅在 type 为 "featured" 时使用
  },
  recentPosts: {
    enabled: true,
    count: 7 // 显示的最近文章数量
  },
  projects: {
    enabled: true,
    count: 2 // 显示的项目数量
  },
  docs: {
    enabled: true,
    count: 3 // 显示的文档数量
  }
}

文章选项

postOptions: {
  postsPerPage: 6,
  readingTime: true, // 显示阅读时间
  wordCount: true, // 显示字数
  tags: true, // 启用标签
  linkedMentions: {
    enabled: true, // 反向链接
    linkedMentionsCompact: false
  },
  graphView: {
    enabled: true,
    showInSidebar: true,
    maxNodes: 100,
    showOrphanedPosts: true
  },
  postNavigation: true, // 上一篇/下一篇导航
  showPostCardCoverImages: "featured-and-posts",
  postCardAspectRatio: "og", // 文章卡片图片比例
  comments: {
    enabled: false // 使用 Giscus 的评论
  }
}

内容类型

文章 (Posts)

在 src/content/posts/ 创建文章：

---
title: 我的文章标题
date: 2025-10-30
description: 文章描述
tags:
  - 标签1
  - 标签2
image: "[[attachments/cover.jpg]]"
imageAlt: 封面图片描述
draft: false
---

您的文章内容在这里...

页面 (Pages)

在 src/content/pages/ 创建静态页面：

---
title: 关于
description: 关于页面描述
---

关于页面内容...

项目 (Projects)

在 src/content/projects/ 展示项目：

---
title: 项目名称
description: 项目描述
date: 2025-10-30
categories:
  - 分类1
projectUrl: https://github.com/user/project
status: in-progress
featured: true
---

项目详情...

文档 (Docs)

在 src/content/docs/ 创建文档：

---
title: 文档标题
description: 文档描述
category: 分类
order: 1
---

文档内容...

Markdown 功能

支持的功能：

  • 基本格式：粗体、斜体、删除线
  • 代码块：语法高亮
  • 表格：Markdown 表格
  • 标注：Obsidian 风格的标注
  • Wikilinks：[[文章标题]]
  • 数学公式：KaTeX 支持
  • Mermaid 图表：流程图、时序图等
  • 高亮：==高亮文本==
  • 任务列表：- [ ] 任务

部署

Netlify

  1. 在 src/config.ts 中设置：
deployment: {
  platform: "netlify"
}
  1. 推送到 Git 仓库
  2. 连接 Netlify
  3. 自动部署

Vercel

  1. 在 src/config.ts 中设置：
deployment: {
  platform: "vercel"
}
  1. 推送到 Git 仓库
  2. 连接 Vercel
  3. 自动部署

GitHub Pages

  1. 在 src/config.ts 中设置：
deployment: {
  platform: "github-pages"
}
  1. 推送到 GitHub 仓库
  2. 在仓库设置中启用 GitHub Pages
  3. 自动部署

最佳实践

性能优化

  • 使用 WebP 格式的图片
  • 启用图片优化
  • 限制首页显示的文章数量
  • 使用延迟加载

SEO 优化

  • 为每篇文章添加描述
  • 使用有意义的 URL
  • 添加图片 alt 文本
  • 使用适当的标题结构

内容组织

  • 使用清晰的文件夹结构
  • 使用有意义的文件名
  • 为相关内容添加标签
  • 使用 Wikilinks 创建连接

故障排除

常见问题

问题：图片不显示

  • 检查图片路径是否正确
  • 确保图片在 attachments/ 文件夹中
  • 使用正确的语法：![alt](attachments/image.jpg) 或 ![[attachments/image.jpg]]

问题：构建失败

  • 检查前置元数据格式
  • 确保所有必需字段都存在
  • 查看构建日志获取详细错误

问题：主题不工作

  • 确保主题名称拼写正确
  • 检查是否安装了所有依赖
  • 清除缓存并重新构建

获取帮助

总结

Astro Modular 提供了一个强大而灵活的博客平台，特别适合 Obsidian 用户。通过简单的配置，您可以创建一个功能齐全、性能卓越的博客。