# tami-web-tech-doc

**Repository Path**: aulence/tami_web_tech_doc

## Basic Information

- **Project Name**: tami-web-tech-doc
- **Description**: 此版技术文档命名为《獭米 web 技术文档》，它基于原来个人编写并为职业技术培训机构服务的《Web 前端入门教程》为基础。重新编写一版新的技术文档的目的在于：重构出更为清晰的知识框架以及更易于使用的导航，梳理出由浅入深的学习理解过程，编写出更易于理解和贴合实际使用的代码案例等等。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-01
- **Last Updated**: 2025-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 獭米 web 技术文档



## 项目介绍

此版技术文档命名为《獭米WEB技术文档》，它基于原来个人编写并为职业技术培训机构服务的《Web 前端入门教程》。重新编写一版新的技术文档的目的在于：

- 重构出更为清晰的知识框架以及更易于使用的导航
- 梳理出由浅入深的学习理解过程
- 编写出更易于理解和贴合实际使用的代码案例

该项目是基于 **Gulp.js** 的最新版本第 5 版来进行自动化构建的常规项目模版，内含新版本的 **Normalize.css** 对项目样式进行初始化。CSS 预处理使用 SCSS 进行编写，不建议在项目内加入原生 CSS 文件，因为这样会让项目的自动构建变得繁琐且难以维护管理。



## 安装教程

1. 确保您的电脑上已经有 Node.js 至少 18.0 以上的版本，并保证 **npm** 或 **npx** 模块处于可用状态（使用 `npm -v` 检查是否安装成功），并也处在一个较新的版本；
2. 全局安装 Gulp.js 命令工具 `npm i -g gulp-cli` 或 `cnpm i -g gulp-cli`，然后输入 `gulp -v` 检查是否安装成功；
3. 下载或使用 **Git** 工具克隆本项目到本地指定文件夹内（启动 Git Bash 工具，输入命令 `git clone git@gitee.com:aulence/project-gulp.git` 或 `git clone https://gitee.com/aulence/project-gulp.git`）；
4. 打开本项目，进入项目根目录下启动指定当前目录的命令行工具（Windows 10 操作系统用户可以按住 <kbd>Shift</kbd> + <kbd>鼠标右键</kbd>，选择“在此处打开 Powershell 窗口”。也可以用组合快捷键先 <kbd>Alt</kbd> + <kbd>F</kbd> 后接键盘的 <kbd>R</kbd> 键打开命令行窗口）；
5. 在打开的命令行内输入命令 `npm i` 或 `cnpm i` 快速地安装自动化构建所需的依赖，使用 Gulp 5 自动化构建的环境就安装完成了。



## 使用注意事项

1. 尽可能维持现有的文件夹结构，否则构建可能产生错误，或者构建出来的文件的引用关系也可能发生错误。
2. src 各目录下不同层级不要有同类型但同名的文件，否则 md5 文件重命名的时候可能会产生标记混淆，从而让构建出来的文件可能产生引用错误。如不要出现 src/scripts/index.js 和 src/scripts/utils/index.js 这样两个同属 src/scripts 目录下的同名文件，否则构建过程中产生的 release/rev/**/*.json 文件对 JS 文件的 md5 重命名就会出现错误的概率。



## 使用说明

### 开发阶段

如果是你处于开发阶段可以执行命令:
```powershell
gulp
```
运行成功后在最后几行中提供可以访问的本地服务器地址“<http://localhost:8040>”，通过该地址即可预览项目效果。如果该端口被占用了，可以进入根目录下的 **Gulpfile.js** 文件内搜索“8040”关键字进行修改并保存，然后重新运行 `gulp` 命令。

打开这个地址后，可以在编辑器内对 **src** 内对任意文件进行修改，保存文件之后浏览器端就会自动重载更改之后的内容而不用您去手动刷新浏览器。

这时，开发的根目录下会生成 **release** 和 **dist** 两个文件夹。**release** 是用于存放自动化构建需要对应源文件路径信息的一些 JSON 文件，而 **dist** 是构建完成的项目，该目录下虽然项目功能完整，但是不建议将其作为上线文件使用，原因后续会说明。每次执行 `gulp` 命令都会将这两个目录删除而重新生成最新的，所以我们一般不要去手动管理它们。

> 为了提升项目编译效率，在这个开发阶段我们没有对任何的 HTML、CSS、JavaScript 和图片文件进行压缩处理，只是为“*.scss”文件提供了资源映射，方便您在浏览器开发者工具中查找样式效果在源 SCSS 文件中对应的行数。
>
> 为了解决项目文件在更新后出现的文件缓存导致重载功能的无效，我们为所有的CSS和JS文件都添加了 MD5 编码作为文件名的一部分，每次更改文件保存后，在浏览器端都会自动去访问最新版本的 CSS 和 JS 文件。当然这对于需要经常更新服务器线上文件缓存的网站应用来说会特别的省心。



另外主要注意的是图片的构建处理会比较消耗时间，所以我们没有默认开启对图片文件变动的构建处理，所以当您往项目的“src/images”文件夹内添加了新的图片资源后，可以新开一个命令行窗口并使用命令 `gulp moveImgToDist`，它会自动将这些新的文件拷贝一份到项目发布文件 **dist** 目录下。



### 项目版本提交规范

在使用 Git 提交代码的时候其实有 4 个部分，其中只有 **header** 是必填的：

 **header**：也就是提交的首行（详见下方的常用 header 标识），header 里面又包含了 subject，是指本次提交的内容改动。（必填）
 **scope**：提交的范围描述，如指定模块的限定范围
 **body**：和 header-subject 的内容对应，用来提供更加详细的描述
 **footer**：用于代码评审，开发者署名等

注释前面需要加的规范标识（header），注意每个标识词冒号后面需要加上一个空格。

- **type:** `commit` 的类型
- **feat:** 新的功能特性
- **fix:** 修复代码 Bug
- **refactor:** 代码的重构
- **enhance:** 代码功能的流程、体验或性能的优化
- **docs:** 文档修改
- **annotation:** 注释的修改或完善
- **style:** 代码的格式改动（并不是 CSS 样式的改动，一般需保证代码逻辑业务并未产生任何变化，只针对规范的代码格式化，分号，缩进等）
- **test:** 测试用例修改
- **chore:** 其他修改，比如构建流程，依赖管理
- **scope:** `commit` 影响的范围，比如: `route`, `component`, `utils`, `build` 等
- **release:** 项目版本发布
- **subject:** `commit` 的概述
- **body:** `commit` 具体修改
- **footer:** 备注信息



### 项目上线打包

使用 `gulp build` 命令即可将项目进行上线前的打包，该命令会自动将项目的 **src** 目录下的文件进行编译并输出到 **dist** 目录下。然后根据自己的需要，将这个目录内的内容进行服务器部署上线的相关操作即可（可以由系统运维人员来完成这部分的操作，或由自动化部署系统来完成）。



## 项目更新日志

### 2025-08-02

1. 创建项目，并对开发基本环境进行了配置



### 2025-08-03
1. 完成项目导航样式及基本选中功能



### 2025-08-04
1. 完成首页中问题注解鼠标悬浮显示对话气泡的功能
2. 设计好了文本段落以及无序、有序列表的样式



### 2025-10-14
1. 新增首页导航封面，并优化布局与样式
2. 统一首页样式的作用域与组织结构
3. 引入页面骨架与内容片段机制，限定改动仅影响主体内容
4. 修复页面资源路径问题，确保页头元素正常显示
5. 将 Markdown 编译接入开发流程，生产构建不处理源 Markdown 目录
6. 添加HTML文档示例代码和代码高亮功能
7. 添加HTML文本标签页面及导航结构
8. 优化导航栏样式并添加选中状态



### 2025-10-15
1. 修改导航栏的内边距和溢出处理，更新活动链接的背景色和文字样式
2. 更新HTML文档结构和标签组成内容



### 2025-10-16
1. 新增HTML文档中图片点击查看大图功能
2. 新增HTML文档中代码块语法高亮功能
3. 新增文档类型声明一节的内容
4. 调整导航栏样式，增加滚动和阴影效果



### 2025-10-18
1. 修正HTML文档内容格式和样式选择器
2. 添加动态锚点导航功能



### 2025-10-27
1. 添加HTML文档中表格功能
2. 完成 `<head>`标签一节的全部课程内容
3. 完善了段落、标题和列表的样式



### 2025-10-28
1. 完成了 `<body>`标签一节全部课程内容
2. 新增了“章节练习”的页面内容样式设计
3. 修改了锚点导航的序号判断逻辑
4. 新增了 HTML 示例文件，并创建了 Gulp 对应的编译规则