Modernize project structure to 2025 Node.js best practices#39
Closed
Modernize project structure to 2025 Node.js best practices#39
Conversation
- Update Node.js engine requirement to >=20.0.0 - Update packageManager to pnpm@9.0.0 - Restructure source code: src/lib → src/core and add src/hexo layer - Move tests from test/ to src/__tests__/ - Update biome.json lineWidth to 100 - Add tsconfig.build.json for build-specific configuration - Update CI to test Node 20.x, 22.x, 24.x - Update .mise.toml to prioritize Node 24.x - Reorder package.json scripts for better workflow - Fix all Biome linting issues - All tests passing (246 tests) Co-authored-by: hcoona <712433+hcoona@users.noreply.github.com>
- Create examples/basic-hexo-site with sample AsciiDoc posts - Add comprehensive README for the example site - Update .gitignore to exclude example artifacts - Update main README to document new project structure - Add examples section to README The example demonstrates: - Basic AsciiDoc features (lists, code, tables, admonitions) - Advanced features (cross-refs, math, callouts, quotes, sidebars) - Configuration via _config.yml - Multiple AsciiDoc file extensions (.adoc) Co-authored-by: hcoona <712433+hcoona@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Setup Hexo AsciiDoc renderer plugin with Node LTS
Modernize project structure to 2025 Node.js best practices
Nov 17, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructures the codebase following clean architecture principles with updated tooling for Node.js 24 LTS and modern development workflows.
Architecture Changes
src/core/(pure AsciiDoc logic) →src/hexo/(Hexo adapter)test/→src/__tests__/for better discoverabilitysrc/core/types.ts) and Hexo integration (src/types.ts)Configuration Updates
>=20.0.0with CI matrix for 20.x/22.x/24.x,.mise.tomldefaults to 24pnpm@9.0.0minimum (currently using 10.x)tsconfig.build.jsonto exclude tests from compilationDeveloper Experience
examples/basic-hexo-site/with sample AsciiDoc posts demonstrating plugin featuresprepare→build→test→check)No breaking changes—maintains full backward compatibility with existing Hexo sites.
Original prompt
下面这套就是“可以直接开干”的最终方案：Node LTS + PNPM + Biome + TypeScript，专门针对「Hexo AsciiDoc 渲染器插件」。
一、技术栈定稿
运行环境（给用户用）：
Node：24.x LTS 优先，兼容 Node ≥20
Hexo：建议对 Hexo 8+ 做适配（插件用 peerDependency 声明）
开发工具：
包管理：pnpm 9+（通过 Node 自带 corepack 管理）Node.js+1
语言：TypeScript 5+
Lint & Format：Biome（替代 ESLint + Prettier）DEV Community+4Biome+4GitHub+4
测试：Vitest（现代、TS 友好）
AsciiDoc 引擎：asciidoctor (Asciidoctor.js 3.x)Asciidoctor Docs+2npmjs.com+2
二、目录结构（最终版）
原则：
core/不依赖 Hexo，方便单测和复用hexo/只做“接 Hexo”那一层src/index.ts是真正的包入口，导出给 Hexo三、关键配置文件（可直接拷）
1.
package.json{ "name": "hexo-renderer-asciidoc", "version": "0.1.0", "description": "AsciiDoc renderer plugin for Hexo (TypeScript, Biome, Vitest)", "license": "MIT", "main": "dist/index.js", "types": "dist/index.d.ts", "files": [ "dist" ], "keywords": [ "hexo", "hexo-plugin", "hexo-renderer", "asciidoc", "asciidoctor" ], "engines": { "node": ">=20.0.0" }, "peerDependencies": { "hexo": ">=8.0.0" }, "dependencies": { "asciidoctor": "^3.0.4" }, "devDependencies": { "@biomejs/biome": "^1.9.0", "@types/hexo": "^3.0.0", "typescript": "^5.6.0", "vitest": "^2.0.0" }, "scripts": { "prepare": "pnpm build", "build": "tsc -p tsconfig.build.json", "typecheck": "tsc --noEmit", "test": "vitest run", "test:watch": "vitest", "lint": "biome lint .", "format": "biome format . --write", "check": "biome check .", "prepublishOnly": "pnpm build && pnpm test && pnpm check" }, "packageManager": "pnpm@9.0.0" }2. TypeScript 配置
tsconfig.json（开发 / 类型检查）{ "compilerOptions": { "target": "ES2020", "module": "CommonJS", "lib": ["ES2020"], "moduleResolution": "Node10", "rootDir": "src", "outDir": "dist", "declaration": true, "declarationMap": true, "strict": true, "esModuleInterop": true, "skipLibCheck": true, "resolveJsonModule": true }, "include": ["src", "vitest.config.ts"] }tsconfig.build.json（构建专用）{ "extends": "./tsconfig.json", "exclude": ["src/__tests__/**/*", "**/*.spec.ts"] }3. Biome 配置：
biome.json按官方推荐用 JSON 配置，统一 Format + Lint + import 排序。Biome+3Biome+3Biome+3
{ "$schema": "https://biomejs.dev/schemas/latest/schema.json", "formatter": { "enabled": true, "lineWidth": 100 }, "linter": { "enabled": true, "rules": { "recommended": true } }, "organizeImports": { "enabled": true }, "files": { "include": ["src/**/*.ts", "vitest.config.ts"], "ignore": ["dist/**", "examples/**"] } }VS Code 装官方 Biome 插件之后，保存时就能自动 format + lint。Biome
4. Vitest 配置：
vitest.config.ts四、核心代码骨架
1. 插件入口：
src/index.tsHexo 在加载插件时会执行这个导出函数，把 Hexo 实例丢进来。Hexo+1
2. ...
Created from VS Code via the GitHub Pull Request extension.
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.