Merge pull request #72 from zkz098/main

docs: 增加开发文档

docs/about.md

@@ -3,23 +3,4 @@
 ShokaX 是 Shoka 的一个二次开发版，提供了更高的性能、更多的功能、更现代的代码
 
 ## 开发原因
-ShokaX的开发原因经历了很多个阶段:
-最开始的目的仅仅是解决puppeteer安装和ES6+代码无法压缩问题，所以[HRMNMI](https://github.com/zkz098/hexo-renderer-multi-next-markdown-it)诞生了
-
-后续发现shoka长时间未更新导致积压大量issues，且架构老旧带来了以下问题:
-1. shoka的主要代码仍然基于es5，这让shoka能够兼容ie11，但也为后续维护带来了极大的阻力
-2. shoka使用了js原生DOM实现操作，这影响了代码可读性和性能
-3. shoka整体和jsdelivr是捆绑的，这导致了jsdelivr无法正常运行时95%的shoka站点也会跟着炸掉
-4. shoka的page js几乎没有注释，这进一步增加了维护难度
-
-这时，shokaX便诞生了，shokaX使用ES6+(甚至ES8+)和typescript解决了第一个问题 \
-后续的Vue版本尝试解决了第二个问题，第三个问题则在shoka-fork时期便已解决
-
-第四个问题在shokaX前期几乎无解，因为shoka的代码较为难以理解(我太逊了)，而又没有工具能解决 \
-在2023年这个问题得到解决，因为ChatGPT成功为shokaX提供了近90%的注释(仅限pagejs)
-可以说shokaX在这之后才是一个"基于shoka开发的主题"，而非"shoka的魔改版"
-
-shoka主题有很多魔改，这些魔改多半以修改文件的形式进行，但对于shokaX这种更新频率来说，这样显然过于麻烦 \
-因此，shokaX参照NexT Inject制作了ShokaX Inject 并鼓励社区发布插件。诚然，Inject还存在很多问题，但现在至少可以让60%的shoka魔改无缝转换为shokaX Plugin
-
-当然，shokaX的故事才刚刚开始，我们欢迎任何人来shokaX反馈问题/提起PR，或者在讨论区闲聊
+正在重写...

docs/develop/basic/index.md

@@ -16,4 +16,37 @@
 git clone <string> # 此处为你的fork地址
 ```
 
-剩余部分正在编写...
+然后请确保你已经安装了`pnpm`包管理器，随后:
+```shell
+pnpm install
+pnpm run build
+```
+如果`build`未抛出错误，则仓库完整且可以用于开发
+
+## 开发须知
+### 目录结构
+ShokaX的目录结构(仅包含对开发重要的部分)如下:
+```text
+|- .github # issues模板、CI工作流等存储位置
+|- docs # 文档储存位置，使用vuepress
+|- languages # 国际化文件储存位置
+|- layout # 模板储存位置
+|- scripts # hexo脚本储存位置
+|- source # 前端文件位置
+- package.json # npm包json
+- tsconfig.json # typescript编译配置
+- .eslintrc.cjs # eslint配置
+- _config.yml # hexo主题配置文件
+```
+
+### 调试注意事项
+1. hexo不会自动排除typescript文件，因此在build后复制到themes文件时应手动删除`*.ts`文件，linux可使用`find . -type f -name "*.ts" -delete`批量删除
+
+### 代码注意事项
+1. `source/js`目录不能使用hexo的辅助函数和node库，`scripts`目录不能使用`source/js`的函数
+2. 注意ESM和CJS的区别，对于仅支持CJS的模块应使用`import xxx = require('xxx')`的形式，否则tsc后无法正常生成文件
+3. 尽可能少使用`@ts-ignore`，一般除去部分遗留代码和types有问题的代码外不应出现`@ts-ignore`
+4. 较通用的 interface 和 declare 应写在`library.ts`中，如果仅在一个文件中出现则写在对应文件中即可
+5. 写注释，特别是奇怪的代码(例如魔法数字和神奇的正则)。对于正则表达式应提供一个示例以便理解
+
+剩余部分正在编写

package.json

@@ -1,13 +1,13 @@
 {
     "name": "hexo-theme-shokax",
-    "version": "0.2.3",
+    "version": "0.2.4",
     "description": "a hexo theme based on shoka",
     "main": "index.js",
     "repository": "https://github.com/zkz098/hexo-theme-shokaX",
     "author": "Chou kaitaku",
     "license": "GPL-3.0-or-later",
     "scripts": {
-        "test": "cd ./source/js && tsc",
+        "test": "tsc",
         "build": "pnpm install && tsc",
         "docs:dev": "vuepress dev docs",
         "docs:build": "vuepress build docs"
@@ -19,31 +19,30 @@
         "@types/jquery": "^3.5.16",
         "@types/js-yaml": "^4.0.5",
         "@types/lozad": "^1.16.1",
-        "@types/node": "^18.15.6",
-        "@types/shelljs": "^0.8.11",
-        "@typescript-eslint/eslint-plugin": "^5.56.0",
-        "@typescript-eslint/parser": "^5.56.0",
+        "@types/node": "^18.15.13",
+        "@typescript-eslint/eslint-plugin": "^5.59.0",
+        "@typescript-eslint/parser": "^5.59.0",
         "@vuepress/client": "2.0.0-beta.61",
         "@vuepress/plugin-docsearch": "2.0.0-beta.61",
-        "algoliasearch": "^4.16.0",
-        "eslint": "^8.36.0",
+        "algoliasearch": "^4.17.0",
+        "eslint": "^8.39.0",
         "eslint-config-standard": "^17.0.0",
         "eslint-plugin-import": "^2.27.5",
-        "eslint-plugin-n": "^15.6.1",
+        "eslint-plugin-n": "^15.7.0",
         "eslint-plugin-promise": "^6.1.1",
-        "eslint-plugin-vue": "^9.10.0",
+        "eslint-plugin-vue": "^9.11.0",
         "hexo-fs": "^4.1.1",
         "hexo-util": "^3.0.1",
-        "instantsearch.js": "^4.53.0",
+        "instantsearch.js": "^4.54.1",
         "pjax": "^0.2.8",
         "theme-shokax-anime": "^0.0.4",
-        "typescript": "^5.0.2",
+        "typescript": "^5.0.4",
         "vue": "^3.2.47",
         "vuepress": "2.0.0-beta.61",
-        "vuepress-plugin-sitemap2": "2.0.0-beta.203"
+        "vuepress-plugin-sitemap2": "2.0.0-beta.205"
     },
     "dependencies": {
         "js-yaml": "^4.1.0",
-        "sass": "^1.60.0"
+        "sass": "^1.62.0"
     }
 }

scripts/helpers/list_categories.ts

@@ -1,7 +1,6 @@
 'use strict'
 /* global hexo */
 
-// @ts-ignore
 import fs = require('hexo-fs')
 
 const prepareQuery = (categories, parent) => {

source/js/_app/components.ts

@@ -64,7 +64,6 @@ const sideBarTab = function () {
     } else {
       element.removeClass('active')
     }
-    // TODO 出现BUG把event去掉
     tab.addEventListener('click', function (event) {
       const target = event.currentTarget as HTMLElement
       if (target.hasClass('active')) return

source/js/_app/fireworks.ts

@@ -133,7 +133,7 @@ function createCircle (x:number, y:number):fireworksP {
 // 渲染烟花粒子
 function renderParticule (targets:any):void {
   // 遍历所有可动画的对象
-  for (let target of targets) {
+  for (const target of targets) {
     // 调用对象上的draw函数来绘制烟花粒子
     target.draw()
   }
@@ -203,13 +203,12 @@ const hasAncestor = function (node:any, name:string):boolean {
   do {
     if (node === null || node === undefined) break
     if (node.nodeName === name) return true
-  } while (node = node.parentNode)
+  } while ((node = node.parentNode) !== null)
   return false
 }
 
 document.addEventListener(tap, function (e) {
   // 禁用A标签的Fireworks动画以修复动画不消失问题
-  // @ts-ignore
   if (hasAncestor(e.target, 'a')) {
     return
   }

tsconfig.json

@@ -10,7 +10,7 @@
     "esModuleInterop": true,
     "moduleResolution": "node",
     "resolveJsonModule": true,
-    "typeRoots": ["node_modules","node_modules/@types"],
+
     "types": ["theme-shokax-anime","lozad","jquery","fancybox"]
   },
   "typeAcquisition": {