写作规范与命名规范

本文档定义了博客文章的写作规范、文件命名规范，以及如何在博客中融合双链笔记（双向链接）功能。

📋 目录

  1. 文件命名规范
  2. 写作规范
  3. 双链笔记融合指南
  4. Front Matter 规范
  5. 目录结构规范
  6. 最佳实践

📝 文件命名规范

基本原则

  1. 使用小写字母和连字符（kebab-case）

    • ✅ 正确：hugo-blog-setup-guide.md
    • ❌ 错误：Hugo_Blog_Setup_Guide.md、hugoBlogSetupGuide.md

  2. 使用有意义的描述性名称

    • ✅ 正确：obsidian-hugo-integration-tutorial.md
    • ❌ 错误：post1.md、article.md、untitled.md

  3. 避免特殊字符

    • 不允许：空格、中文标点、特殊符号（!@#$%^&*()）
    • 允许：连字符 -、下划线 _（推荐使用连字符）

  4. 包含关键词

    • 文件名应反映文章的核心主题
    • 便于 SEO 和文件查找

命名模式

模式 1：主题-描述（推荐）

技术栈-具体主题.md

示例：

  • hugo-automation-setup.md
  • obsidian-daily-workflow.md
  • github-actions-deployment.md

模式 2：日期-主题（可选）

YYYY-MM-DD-主题描述.md

示例：

  • 2025-01-20-writing-guidelines.md
  • 2025-01-15-weekly-summary.md

注意： 如果使用日期前缀，确保在 Front Matter 中也设置正确的 date 字段。

模式 3：分类-主题

分类-主题描述.md

示例：

  • tutorial-hugo-setup.md
  • review-obsidian-plugins.md
  • tutorial-git-workflow.md

命名检查清单

创建新文件前，确认：

  • 文件名全小写
  • 使用连字符分隔单词
  • 文件名清晰描述内容
  • 无空格和特殊字符
  • 长度适中（建议 20-50 个字符）
  • 避免重复（检查现有文件）

✍️ 写作规范

文章结构

每篇博客文章应包含以下部分：

# 标题（H1，只有一个）

## 引言/概述
简要介绍文章主题和目的

## 正文部分
根据内容组织多个 H2 或 H3 标题

## 总结
总结要点和关键信息

## 相关链接（可选）
- 相关文章
- 参考资料

Markdown 语法规范

标题层级

  • 使用 # 表示一级标题（文章标题，通常只有一个）
  • 使用 ## 表示二级标题（主要章节）
  • 使用 ### 表示三级标题（子章节）
  • 避免跳过层级（不要从 H1 直接跳到 H3）

列表

有序列表：

1. 第一项
2. 第二项
3. 第三项

无序列表：

- 项目一
- 项目二
- 项目三

代码块

使用三个反引号包裹代码，并指定语言：

```python
def hello_world():
    print("Hello, World!")
```

引用

> 这是一段引用文字

强调

**粗体文字**
*斜体文字*
`代码片段`

内容质量要求

  1. 清晰性

    • 使用简洁明了的语言
    • 避免冗长的句子
    • 段落长度适中（3-5 句）

  2. 完整性

    • 提供必要的上下文
    • 包含完整的步骤说明
    • 添加必要的示例

  3. 准确性

    • 验证技术信息
    • 检查链接有效性
    • 更新过时的内容

  4. 可读性

    • 使用适当的标题层级
    • 添加代码示例
    • 使用列表和表格组织信息

🔗 双链笔记融合指南

什么是双链笔记

双链笔记（双向链接）允许你在文章之间创建可导航的链接，形成知识网络。在 Obsidian 中，使用 [[链接文本]] 语法创建双链。

在博客中使用双链

方法 1：使用 Obsidian 链接语法（推荐）

这篇文章介绍了 [[Hugo 博客设置]] 的完整流程。

如果你对 [[GitHub Actions]] 感兴趣，可以查看相关文章。

更多信息请参考 [[写作规范与命名规范]]。

在 Hugo 中的处理：

Hugo 不会自动处理 [[链接]] 语法，但可以通过以下方式实现：

  1. 使用 Hugo 短代码（需要配置）
  2. 转换为标准 Markdown 链接（手动或自动化）
  3. 使用插件转换（如 obsidian-hugo 插件）

方法 2：使用标准 Markdown 链接

这篇文章介绍了 [Hugo 博客设置]({{< relref "hugo-blog-setup.md" >}}) 的完整流程。

如果你对 [GitHub Actions]({{< relref "github-actions-guide.md" >}}) 感兴趣，可以查看相关文章。

Hugo relref 短代码的优势：

  • 自动解析相对路径
  • 支持锚点链接
  • 链接失效时会在构建时警告

方法 3：混合使用（最佳实践）

在 Obsidian 中写作时使用双链语法，发布时转换为标准链接：

<!-- 在 Obsidian 中 -->
这篇文章介绍了 [[Hugo 博客设置]] 的完整流程。

<!-- 发布到博客时转换为 -->
这篇文章介绍了 [Hugo 博客设置]({{< relref "hugo-blog-setup.md" >}}) 的完整流程。

双链命名规范

链接文本规范

  1. 使用文章的实际标题

    [[Hugo 博客设置]]  ✅
[[hugo-blog-setup]]  ❌（使用文件名）

  2. 保持一致性

    • 同一篇文章使用相同的链接文本
    • 避免使用缩写或别名

  3. 使用描述性文本

    [[Hugo 博客自动化部署指南]]  ✅
[[那篇文章]]  ❌

创建双链的最佳实践

  1. 建立知识图谱

    • 将相关主题的文章链接起来
    • 创建主题索引页面
    • 使用标签和分类辅助组织

  2. 使用 MOC（Map of Content）

    # 技术文章索引

## Hugo 相关
- [[Hugo 博客设置]]
- [[Hugo 主题定制]]
- [[Hugo 部署指南]]

## Obsidian 相关
- [[Obsidian 使用指南]]
- [[Obsidian 插件推荐]]

  3. 反向链接管理

    • 在 Obsidian 中查看反向链接
    • 确保链接关系是双向的
    • 定期检查和更新断链

双链转换工具

方案 1：使用 Obsidian 插件

安装 obsidian-hugo 或类似插件，自动将 [[链接]] 转换为 Hugo 兼容格式。

方案 2：使用脚本转换

创建自动化脚本，在提交前转换链接：

# 示例：将 [[链接]] 转换为 [链接](relref短代码)
import re

def convert_obsidian_links(content):
    pattern = r'\[\[([^\]]+)\]\]'
    def replace_link(match):
        link_text = match.group(1)
        # 根据链接文本查找对应的文件名
        filename = find_filename(link_text)
        # 返回 Hugo relref 短代码格式的链接
        return f'[{link_text}](relref "{filename}")'
    return re.sub(pattern, replace_link, content)

方案 3：手动转换

在发布前手动检查并转换所有双链链接。

📄 Front Matter 规范

必填字段

---
title: "文章标题"
date: 2025-01-20T10:00:00+08:00
draft: false
---

推荐字段

---
title: "完整的文章标题"
date: 2025-01-20T10:00:00+08:00
draft: false
tags:
  - 标签1
  - 标签2
  - 标签3
categories:
  - 分类1
  - 分类2
description: "文章的简短描述，用于 SEO 和摘要显示"
author: "作者名（可选）"
cover:
  image: "/images/2025/01/article-cover.png"
  alt: "封面图描述"
---

字段说明

字段 类型 必填 说明
title 字符串 ✅ 文章标题，会显示在页面和列表中
date 日期时间 ✅ 发布时间，格式：YYYY-MM-DDTHH:mm:ss+08:00
draft 布尔值 ✅ false 表示发布，true 表示草稿
tags 数组 推荐 标签列表，用于分类和搜索
categories 数组 推荐 分类列表，用于组织文章
description 字符串 推荐 SEO 描述，建议 150-160 字符
author 字符串 可选 作者名称
cover 对象 可选 封面图片配置

标签和分类规范

标签（Tags）

  • 使用小写字母
  • 多个单词用连字符分隔
  • 保持标签数量适中（3-8 个）
  • 使用通用标签，便于聚合

示例：

tags:
  - hugo
  - obsidian
  - github-actions
  - 自动化
  - 博客

分类（Categories）

  • 使用层级分类
  • 保持分类体系一致
  • 每篇文章 1-2 个分类

示例：

categories:
  - 技术
  - 教程

📁 目录结构规范

推荐结构

obsidian-notes/
├── posts/                    # 博客文章目录
│   ├── 2025/                # 按年份组织（可选）
│   │   ├── 01/              # 按月份组织（可选）
│   │   │   └── article-name.md
│   │   └── article-name.md
│   └── article-name.md      # 直接在 posts/ 下（推荐）
├── post/                    # 规范文档目录
│   └── 写作规范与命名规范.md
├── about/                   # 关于页面
├── archive/                 # 归档内容
└── images/                  # 图片资源
    └── 2025/
        └── 01/
            └── article-name/
                ├── cover.png
                └── screenshot1.png

文件组织建议

  1. 扁平结构（推荐）

    • 所有文章直接放在 posts/ 目录下
    • 通过文件名和 Front Matter 的日期组织
    • 便于查找和管理

  2. 按日期组织（可选）

    • 使用 YYYY/MM/ 目录结构
    • 适合文章数量较多的场景
    • 需要更新图片路径引用

  3. 按主题组织（不推荐）

    • 使用分类目录
    • 可能导致文件重复分类
    • 建议使用标签和分类字段代替

🎯 最佳实践

写作流程

  1. 规划阶段

    • 确定文章主题和标题
    • 创建文件名（遵循命名规范）
    • 规划文章结构

  2. 写作阶段

    • 在 Obsidian 中使用双链语法
    • 遵循 Markdown 语法规范
    • 添加必要的 Front Matter

  3. 完善阶段

    • 检查拼写和语法
    • 验证所有链接
    • 添加标签和分类
    • 设置合适的描述

  4. 发布阶段

    • 转换双链为 Hugo 兼容格式（如需要）
    • 检查 draft: false
    • 提交到 Git 仓库

双链使用建议

  1. 适度使用

    • 不要过度链接，影响阅读流畅性
    • 只链接真正相关的内容
    • 每个段落 1-2 个链接即可

  2. 维护链接

    • 定期检查断链
    • 更新过时的链接
    • 删除不再相关的链接

  3. 创建索引

    • 为主题创建 MOC 页面
    • 使用标签页组织相关内容
    • 建立知识网络

文件管理建议

  1. 版本控制

    • 使用有意义的提交信息
    • 定期提交更改
    • 使用分支管理草稿

  2. 备份

    • 定期推送到远程仓库
    • 保留本地备份
    • 使用 Git 历史恢复

  3. 清理

    • 删除未使用的文件
    • 整理图片资源
    • 归档旧文章

📚 相关资源

  • [[README]] - 仓库使用说明
  • [[Hugo 文档]] - Hugo 官方文档
  • [[Obsidian 使用指南]] - Obsidian 功能说明

🔄 更新日志

  • 2025-01-20: 创建初始版本，定义基本规范

最后更新： 2025-01-20
维护者： 博客作者