blogs/FixIt
1
0
Fork 0
mirror of https://github.com/hugo-fixit/FixIt.git synced 2026-08-24 15:28:57 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
1e0d1affaf6517879fc359f3074e67603739b92f
FixIt/.github/copilot-instructions.md
T

8.0 KiB
Raw Blame History

FixIt 编码标准和指导原则

本文档定义了 FixIt 主题项目的编码标准、最佳实践和开发指导原则。所有贡献者和 AI 助手在参与项目开发时都应遵循这些规范。

项目概述

FixIt 是一个面向 Hugo 静态网站生成器的现代化、响应式主题。项目基于以下技术栈：

  • Hugo: 静态网站生成器（≥ 0.158.0）
  • SCSS: CSS 预处理器，用于样式开发
  • JavaScript: ES6+ 标准，用于前端交互功能
  • Go Templates: Hugo 模板引擎
  • Node.js: 开发环境和构建工具
  • pnpm: 包管理器

目录结构约定

FixIt/
├── apps/               # 最小化站点
│   ├── demo/           # 演示站点
│   └── test/           # 测试站点
├── archetypes/         # 内容模板
├── assets/             # 主题资源文件
│   ├── css/            # SCSS 样式文件
│   ├── js/             # JavaScript 文件
│   ├── images/         # 图像资源
│   └── lib/            # 第三方库
├── i18n/               # 国际化翻译文件
├── layouts/            # Hugo 模板文件
│   ├── _markup/        # Hugo 渲染钩子
│   ├── _partials/      # 可复用模板组件
│   └── _shortcodes/    # 自定义短代码
├── packages/           # 主题相关包
├── static/             # 静态文件
├── hugo.toml           # 主题默认配置
└── package.json        # npm 脚本和依赖

SCSS/CSS 编码规范

文件组织结构

  1. 主入口文件: assets/css/style.scss
  2. 变量文件: assets/css/_variables.scss - 全局变量定义
  3. 覆写文件: assets/css/_override.scss - 用户自定义覆写
  4. 组织结构:
    • _core/: 核心样式（基础、布局、媒体查询等）
    • _mixin/: SCSS mixins 和函数
    • _page/: 页面特定样式
    • _partials/: 组件样式
    • _shortcodes/: 短代码样式

命名约定

  1. CSS 类名: 使用 BEM 方法论或语义化命名

    .header-desktop {}
.menu-item {}
.single-title {}
.post-tag {}

  2. SCSS 变量: 使用连字符分隔，语义化命名

    $global-font-family: system-ui, sans-serif;
$code-background-color: #f4f6f8;
$header-height: 3.5rem;

  3. CSS 自定义属性: 使用前缀约定

    $prefix: fi-;
$rootPrefix: --fi-;

样式组织原则

  1. 主题切换支持: 使用 CSS 变量实现主题切换

    .element {
  color: var(#{$rootPrefix}global-font-color);
}

  2. Mixin 使用: 提高代码复用性

    @include border-radius;
@include transition(all 0.2s ease);

代码质量要求

  1. 缩进: 使用 2 个空格
  2. 注释: 为复杂逻辑添加注释
  3. 颜色: 使用变量而非硬编码颜色值
  4. 单位: 优先使用相对单位（rem、em、%）

JavaScript 编码规范

代码风格

  1. ES6+ 标准: 使用现代 JavaScript 语法
  2. 模块化: 使用 ES6 模块系统

文件组织

  1. 主题核心: assets/js/theme.js - 主题核心逻辑
  2. 工具函数: assets/js/util.js - 通用工具函数
  3. 特定功能: 按功能划分独立模块

编码实例

// 使用 ES6 类
export default class Util {
  static copyText(text) {
    // ...
  }
}

// 主题类组织
class FixIt {
  constructor() {
    this.config = window.config
    this.scrollTop = Util.getScrollTop()
  }

  init() {
    this.initTheme()
    this.initComponents()
  }
}

最佳实践

  1. 错误处理: 使用 try-catch 处理异常
  2. 异步操作: 优先使用 async/await
  3. 事件处理: 合理使用事件委托
  4. 性能优化: 避免不必要的 DOM 操作

Hugo 模板规范

模板组织

  1. 布局模板: layouts/ 目录下的主要模板
  2. 局部模板: layouts/_partials/ 下的可复用组件
  3. 短代码: layouts/_shortcodes/ 下的内容短代码

编码约定

  1. 变量命名: 使用驼峰命名法

    {{- $footerConfig := .Site.Params.footer -}}
{{- $fingerprint := .Site.Store.Get "fingerprint" -}}

  2. 注释规范: 使用 Hugo 注释语法

    {{- /* 这是模板注释 */ -}}
{{- /*
  多行注释
  可以跨越多行
 */ -}}

  3. 条件判断: 清晰的条件结构

    {{- if ne $config.enable false -}}
  <!-- 内容 -->
{{- end -}}

  4. 循环遍历: 合理使用 range

    {{- range $index, $value := .Pages -}}
  <!-- 处理逻辑 -->
{{- end -}}

国际化处理

  1. 翻译函数: 使用 T 函数

    {{ T "header.switchTheme" }}

  2. 多语言支持: 考虑多语言环境

    {{- if hugo.IsMultilingual -}}
  <!-- 多语言逻辑 -->
{{- end -}}

开发工作流程

环境设置

  1. 前置要求:

    • Node.js (≥ 20.0.0)
    • Hugo Extended (≥ 0.158.0)
    • pnpm (包管理器)

  2. 开发命令:

    pnpm dev:demo      # 启动 demo 站点开发服务器
pnpm dev:test      # 启动 test 站点开发服务器
pnpm dev:docs      # 启动文档开发服务器（需有 fixit-docs 作为同级目录）
pnpm build:demo    # 构建 demo 站点
pnpm build:test    # 构建 test 站点
pnpm build         # 一键构建所有站点
pnpm preview       # 预览构建后的站点（需先构建）

代码质量

  1. 代码审查: 提交前进行自我审查
  2. 测试验证: 在多个环境中测试功能
  3. 文档更新: 必要时更新相关文档
  4. 向后兼容: 确保更改不破坏现有功能

Git 提交规范

遵循 Conventional Commits 规范：

feat: 新增功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或工具相关

性能优化指导

CSS 性能

  1. 选择器优化: 避免过深的嵌套
  2. 媒体查询: 合理组织响应式断点
  3. 动画优化: 使用 transform 和 opacity
  4. 资源压缩: 生产环境启用压缩

JavaScript 性能

  1. 延迟加载: 非关键脚本使用 defer
  2. 事件优化: 合理使用防抖和节流
  3. 内存管理: 及时清理事件监听器
  4. 模块化: 按需加载功能模块

Hugo 模板性能

  1. 缓存策略: 合理使用 Hugo 缓存机制
  2. 资源处理: 优化图片和静态资源
  3. 构建优化: 减少不必要的模板处理

可访问性要求

  1. 语义化 HTML: 使用正确的 HTML 标签
  2. ARIA 属性: 为复杂组件添加 ARIA 支持
  3. 键盘导航: 确保键盘可访问性
  4. 颜色对比: 满足 WCAG 对比度要求
  5. 屏幕阅读器: 提供适当的文本替代

浏览器兼容性

  1. 目标浏览器: 支持现代浏览器
  2. 渐进增强: 基础功能向下兼容
  3. 特性检测: 使用特性检测而非浏览器检测
  4. Polyfill: 必要时提供 polyfill 支持

安全考虑

  1. XSS 防护: 正确处理用户输入
  2. CSRF 保护: 表单提交安全
  3. 内容安全: 合理设置 CSP 策略
  4. 依赖安全: 定期更新依赖包

文档要求

  1. 代码注释: 复杂逻辑必须注释
  2. API 文档: 公共方法需要文档
  3. 使用示例: 提供清晰的使用示例
  4. 更新日志: 重要更改记录在 CHANGELOG

第三方库管理

  1. 依赖选择: 优先选择轻量、维护活跃的库
  2. 版本管理: 及时更新安全补丁
  3. 许可证: 确保许可证兼容性
  4. 定制化: 必要时进行本地化修改

贡献指导

  1. 讨论优先: 重大更改前先讨论
  2. 小步迭代: 避免大规模重构
  3. 测试覆盖: 新功能需要充分测试
  4. 文档同步: 功能和文档同时更新

遵循这些编码标准将有助于维护代码质量，提高开发效率，并确保项目的长期可维护性。

Reference in New Issue View Git Blame Copy Permalink