入门指南 | 哪里不会

欢迎使用哪里不会博客平台！本指南将帮助您快速开始使用我们的平台，从安装到发布您的第一篇文章。

前置要求

您需要：

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",
customThemeFile: "custom", 
availableThemes: "all", 
fonts: {
  source: "local",
  families: {
    body: "Inter",
    heading: "Inter",
    mono: "JetBrains Mono", 
  },
  display: "swap",
},
layout: {
  contentWidth: "45rem",
},
tableOfContents: {
  enabled: true,        // 所有文章的全局目录开关
  depth: 4,            // 最大标题深度（2-6，其中2=H2，3=H3等）
},
footer: {
  enabled: true,
  content: `© 2025 {author}. 由哪里不会博客平台构建。`,
  showSocialIconsInFooter: true,
},
hideScrollBar: false,  // 隐藏浏览器滚动条
scrollToTop: true,     // 显示回到顶部按钮
featureButton: "mode", // "mode" | "graph" | "theme" | "none" - 主功能按钮的作用
seo: {
  defaultOgImageAlt: "哪里不会博客平台标志。",
},
deployment: {
  platform: "netlify", // "netlify" | "vercel" | "github-pages" - 设置重定向配置
},

当前可用的主题包括：Oxygen、Minimal、Atom、Ayu、Catppuccin、Charcoal、Dracula、Everforest、Flexoki、Gruvbox、macOS、Nord、Obsidian、Rosé Pine、Sky、Solarized、Things 和 Custom。使用 pnpm dev 可以实时查看主题变化。

自定义主题

您可以通过以下方式创建自己的自定义主题：

重命名模板：将 src/themes/custom/custom.ts 重命名为您想要的名称
修改颜色：更新颜色比例以匹配您的设计
更新配置：
- 在 src/config.ts 中设置 theme: "custom"
- 设置 customThemeFile: "your-theme-name"（不带 .ts 扩展名的文件名）
测试：使用 pnpm dev 实时查看主题变化

系统会自动找到并使用您的自定义主题！

有关详细说明和最佳实践，请参阅 src/themes/custom/README.md。

字体配置

使用灵活的加载选项自定义标题、正文文本和代码的字体：

fonts: {
  source: "local", // "local" 表示自托管字体，"cdn" 表示 Google Fonts CDN
  families: {
    body: "Inter",      // 正文字体
    heading: "Inter",   // 标题字体  
    mono: "JetBrains Mono", // 等宽字体
  },
  display: "swap", // 字体加载策略："swap"、"fallback" 或 "optional"
}

字体加载选项：

本地字体（source: "local"）：自托管字体以获得更好的性能和隐私
CDN 字体（source: "cdn"）：Google Fonts CDN 提供无限的字体选择

建议的字体组合：

默认：heading: "Inter"、body: "Inter"、mono: "JetBrains Mono"
现代：heading: "Montserrat"、body: "Lato"、mono: "Fira Code"
优雅：heading: "Playfair Display"、body: "Source Sans Pro"、mono: "Source Code Pro"
衬线：heading: "Merriweather"、body: "Merriweather"、mono: "IBM Plex Mono"

支持的字体（本地模式）：

无衬线：Inter、Roboto、Open Sans、Lato、Poppins、Source Sans Pro、Nunito、Montserrat
衬线：Playfair Display、Merriweather、Lora、Crimson Text、PT Serif、Libre Baskerville
等宽：Fira Code、JetBrains Mono、Source Code Pro、IBM Plex Mono、Cascadia Code

CDN 模式优势：

任何 Google 字体都可以立即使用
无需安装包
无限的字体选择

本地模式优势：

更好的性能（无外部请求）
增强的隐私（无跟踪）
离线工作
更快的加载时间

系统通过回退到系统字体来优雅地处理不支持的字体，确保您的网站永远不会崩溃。

命令面板

命令面板提供即时导航和搜索功能：

commandPalette: {
    enabled: true,
    shortcut: "ctrl+K",
    placeholder: "搜索文章",
    search: {
      posts: true,
      pages: false,
      projects: false,
      docs: false,
    },
    sections: {
      quickActions: true,
      pages: true,
      social: true,
    },
    quickActions: {
      enabled: true,        // 启用快速操作部分
      toggleMode: true,     // 显示深色/浅色模式切换
      graphView: true,      // 显示图形视图按钮
      changeTheme: true,    // 显示主题切换器
    },
}

功能：

即时搜索：按 Ctrl+K（或您定义的不同快捷键）搜索文章、页面和项目
快速操作：主题切换、导航快捷键
可自定义：更改快捷键、占位符文本和启用的部分

个人资料图片

添加可配置的个人资料图片以增添个人风格：

profilePicture: {
  enabled: true,
  image: "/profile.jpg",        // 您的图片路径（放在 public/ 目录中）
  alt: "个人资料图片",       // 可访问性的替代文本
  size: "md",                   // "sm"（32px）、"md"（48px）或 "lg"（64px）
  url: "/about",                // 点击时的可选 URL
  placement: "footer",          // "footer" 或 "header"
  style: "circle",              // "circle"、"square" 或 "none"
}

功能：

灵活放置：页眉（替换文本标志）或页脚
多种样式：圆形（个人资料照片）、方形（标志）或无（横幅）
响应式：移动设备和桌面设备的不同布局
主题感知：样式适应所有可用主题

导航配置

自定义您网站的导航菜单和社交链接：

navigation: {
  showNavigation: true,           // 显示/隐藏主导航
  style: "traditional",           // "minimal" 或 "traditional" 导航样式
  showMobileMenu: true,           // 显示移动菜单切换
  pages: [                        // 导航菜单项
    { title: "文章", url: "/posts" },
    { title: "项目", url: "/projects" },
    { title: "文档", url: "/docs" },
    { title: "关于", url: "/about" },
  ],
  social: [                       // 社交媒体链接
    { title: "GitHub", url: "https://github.com/username", icon: "github" },
    { title: "X", url: "https://x.com/username", icon: "x-twitter" },
  ],
}

导航样式：

传统：全尺寸文本，居中对齐
极简：较小文本，右对齐

首页配置

首页内容由 homeOptions 部分控制：

特色文章：显示最新文章或特定特色文章
最近文章：显示可配置数量的最近文章
项目和文档：显示特色项目和文档
首页简介：控制放置位置或完全禁用

当只启用一种内容类型时，它会得到特殊处理，带有居中的”查看全部”链接。当只显示简介时，它会显示为带有 H1 标题和圆角容器样式的适当页面。

文章选项

在 postOptions 部分配置文章相关功能：

postOptions: {
  postsPerPage: 6,
  readingTime: true,
  wordCount: true,
  tableOfContents: true,
  tags: true,
  linkedMentions: {
    enabled: true,
    linkedMentionsCompact: false,
  },
  graphView: {
    enabled: true,
    showInSidebar: true,
    showInCommandPalette: true,  // 在命令面板中显示图形按钮
    maxNodes: 100,               // 要显示的最大节点数
    showOrphanedPosts: true,     // 显示没有连接的文章
  },
  postNavigation: true,
  showPostCardCoverImages: "featured-and-posts",
  postCardAspectRatio: "og",
  customPostCardAspectRatio: "2.5/1",
  comments: {
    enabled: false,
    provider: "giscus",
    // ... 其他评论设置
  },
}

目录：

启用目录是所有文章的全局开关。这与其他内容类型（如页面）不同，页面可以通过 frontmatter 获得每页目录开关。

链接提及功能：

linkedMentions: true - 在页面末尾启用链接提及部分，显示哪些文章引用了当前文章
linkedMentionsCompact: false - 为链接提及选择详细视图（默认）或紧凑视图

封面图片选项：

"all" - 在所有文章卡片上显示封面图片
"featured" - 仅在特色文章部分和特色文章上显示
"home" - 仅在首页部分（特色和最近）显示
"posts" - 仅在文章页面、标签页面和文章卡片上显示
"featured-and-posts" - 在特色文章部分和文章页面/标签卡片上显示（但不在最近文章部分）
"none" - 从不在文章卡片上显示封面图片

**注意：**此设置仅影响文章卡片。项目和文档卡片在可用时始终显示封面图片。

文章卡片宽高比： 配置文章卡片封面图片的宽高比：

postOptions: {
  postCardAspectRatio: "og", // 默认：OpenGraph 标准
  customPostCardAspectRatio: undefined, // 用于自定义比例
}

宽高比选项：

"og" (1.91:1) - 开放图标准（默认）
"16:9" (1.78:1) - 标准宽屏
"4:3" (1.33:1) - 传统
"3:2" (1.5:1) - 经典摄影
"square" (1:1) - 正方形
"golden" (1.618:1) - 黄金比例
"custom" - 使用您自己的比例

自定义宽高比示例：

postOptions: {
  postCardAspectRatio: "custom",
  customPostCardAspectRatio: "2.5/1" // 自定义 2.5:1 比例
}

注意：这仅影响文章卡片（列表、首页、标签页面）。个别文章封面图片保持其原始宽高比。

内容结构

src/content/
├── posts/                   # 博客文章
│   ├── attachments/           # 共享文章图片、音频或其他附件。
│   ├── getting-started.md   # 基于文件的文章
│   └── sample-folder-post/  # 基于文件夹的文章
│       ├── index.md         # 主要内容文件
│       ├── hero-image.jpg   # 文章特定资源
│       └── diagram.png
├── pages/                   # 静态页面
│   ├── attachments/           # 共享页面图片、音频或其他附件。
│   ├── about.md
│   ├── contact.md
│   └── privacy-policy.md
├── special/                 # 特殊页面
│   ├── home.md             # 首页简介内容
│   ├── 404.md              # 404 错误页面
│   ├── projects.md         # 项目索引页面内容
│   └── docs.md             # 文档索引页面内容
├── projects/                # 特色项目
│   ├── attachments/           # 共享项目图片、音频或其他附件。
│   └── sample-project/      # 基于文件夹的项目
│       ├── index.md
│       └── screenshot.png
├── docs/                    # 文档
│   ├── attachments/           # 共享文档图片、音频或其他附件。
│   └── sample-guide.md      # 文档文件
└── .obsidian/               # Obsidian vault 设置
    ├── plugins/             # 配置的插件
    ├── themes/              # 最小主题
    └── snippets/            # 自定义 CSS 代码片段

内容组织

特殊内容集合

特殊索引页面由 src/content/special/ 中的 special 内容集合处理：

home.md - 首页简介内容
404.md - 404 错误页面
posts.md - 文章索引页面（标题、描述、H1）
projects.md - 项目索引页面内容
docs.md - 文档索引页面内容

这些页面具有固定的 URL 和最少的 frontmatter，以防止意外破坏核心功能。大多数支持 frontmatter 以下的内容，除了 posts.md 只使用 frontmatter 字段。

可选内容类型

您可以在 src/config.ts 中全局启用/禁用可选内容部分：

optionalContentTypes: {
  projects: true, // 启用项目部分
  docs: true,     // 启用文档部分
},

禁用时，动态索引页面会重定向到 404，允许您在 src/content/pages/ 中创建静态后备页面（例如，pages/projects.md）。

草稿

开发环境：所有文章可见
生产环境：仅显示已发布的文章
在 frontmatter 中使用 draft: true 来隐藏

编写文章

在 src/content/posts/ 中创建文章，使用以下 frontmatter：

---
title: "{{title}}"
date: {{date}}
description: ""
tags: []
image: ""
imageAlt: ""
imageOG: false
hideCoverImage: false
targetKeyword: ""
hideTOC: false
draft: true
---

## 从 H2 标题开始

使用 markdown 和增强功能编写。

使用 [[wikilinks]] 或 [markdown 链接](/posts/post.md) 来连接文章。

> [!note] Obsidian 提示框
> 在 Obsidian 中完全一样工作！

由于文章标题被硬编码为 H1，您的内容应该从 H2 标题开始。

您也可以创建基于文件夹的文章，如您在此处所见：示例基于文件夹的文章。基本文件名是 index.md，父文件夹名作为文章的 slug。

创建页面

关于页面代表一个标准页面，您可以轻松复制。它的 frontmatter 如下所示：

---
title: "{{title}}"
description: ""
hideTOC: false
noIndex: false
---

## 从 H2 标题开始

使用 markdown 和增强功能编写。

H1 从 frontmatter 标题硬编码而来，与文章一样，但页面获得一个独特的 noIndex 属性，该属性设置页面是否应被搜索引擎索引或包含在站点地图中。对于您不希望被索引的页面（如感谢页面）很有帮助。

其他页面详细信息

联系页面有一个可选的表单嵌入其中，填写后会引导到感谢页面。它预配置为与 Netlify 开箱即用，您只需启用表单检测。

可选的隐私政策页面可以通过删除它来编辑或删除，如果您不想要它。

special/home.md 控制首页简介的内容。向 special/404.md 添加内容将在任何”未找到”页面上显示。

创建项目

在 src/content/projects/ 中创建项目以展示您的工作。项目支持单文件和基于文件夹的组织：

---
title: "{{title}}"
description: "项目描述"
date: {{date}}
categories: ["Web Development", "Open Source"]
repositoryUrl: "https://github.com/username/repo"
projectUrl: "https://your-project.com"
status: "completed"  # "in-progress" 或 "completed"
image: "cover.jpg"
imageAlt: "项目截图"
hideCoverImage: false
hideTOC: false
draft: false
featured: true
---

特色标志：启用时在首页显示。

创建文档

在 src/content/docs/ 中创建文档以提供指南和参考：

---
title: "{{title}}"
description: "文档描述"
category: "Setup"  # 可选 - 如果缺失则创建"Unsorted"
order: 1
version: "1.0.0"
lastModified: 2024-01-15
image: "hero.jpg"
imageAlt: "文档截图"
hideCoverImage: false
hideTOC: false
draft: false
featured: true
---

按 order 编号在类别内对文档进行排序。使用 featured 在启用时在首页显示。

自动别名和重定向

当您在 Obsidian 中重命名内容类型（默认为文章或页面，但在设置中可配置）时，旧文件名会自动存储为别名。Astro 处理这些别名并创建重定向规则，因此旧 URL 继续工作。您无需手动添加别名 - 当您使用 Obsidian 的重命名功能时，它们会自动出现。

Obsidian 集成

使用包含的 Vault

在 Obsidian 中打开 src/content/
信任作者并启用插件（Astro Composer、Minimal 主题）
开始写作

该 vault 提供：

预配置的插件，为此 Astro 博客优化
可调节的主题，用于无干扰写作
可选的 CSS 代码片段，以自定义您的体验
自定义热键，用于加速文章创建和发布

阅读指南获取更详细的信息。

要删除 Obsidian，只需删除 .obsidian 文件夹。

关键功能

命令面板

按 Ctrl+K（或自定义热键）进行即时导航、搜索和深色/浅色模式切换。

文章内部链接和连接

[[文章标题|自定义文本]] - wikilinks（仅文章）
[文章标题](posts/post-slug.md) - 标准 markdown 链接
[文章标题](/posts/post-slug) - 相对标准 markdown 链接（这些适用于除页面外的每种内容类型*）
链接提及自动显示文章连接，带有可折叠界面
紧凑或详细视图链接提及显示选项

因为标准页面位于 pages 文件夹下，特殊页面位于 special 文件夹下，相对链接不会在 Obsidian 中都按预期工作来链接和*在您的博客上显示。如果您不关心它在 Obsidian 中工作，您可以做类似 About 的事情，它将在您的网站上按预期工作。

内容类型之间的链接

Wikilinks 无缝适用于文章，但仅限于文章集合。对于链接到其他内容类型（页面、项目、文档），请使用标准 markdown 链接：

文章：[[file-name|Article Title]]、[Article Title](posts/file-name.md) 或 [Article Title](/posts/file-name)
页面：[Page Title](pages/file-name.md)（例如，[About](pages/about.md)
项目：[Project Name](projects/file-name.md)
文档：[Documentation](docs/file-name.md)