su-island

一款 SSG 生成框架, 用于快速搭建文档中心, 类似 vitePress

目录结构如下:

├── .husky // 用于git hooks
├── bin
│   └── island.js // bin所指脚本目录
├── docs // 文档目录-用于模拟使用者
├── e2e // e2e测试目录
├── scripts // 脚本目录
│   └── prepare-e2e.ts // 用于启动e2e相关
├── src
│   ├── node // su-island运行相关
│      ├── __text__ // 测试相关目录
│      ├── constants // 存储常量相关
│      ├── plugin-island
│          ├── config.ts // 用于返回配置文件和热更新相关
│          └── indexHtml.ts // 用于首页 html 处理返回给浏览器
│      ├── plugin-mdx
│          ├── rehypePlugins
│              ├── preWrapper.ts // rehype插件-用于改变md中大代码块编译结果
│              └── shiki.ts // rehype插件-用于代码高亮
│          ├── remarkPlugins
│              └── toc.ts // remark插件-用于生成页面内容右侧的大纲
│          ├── index.ts // 创建mdx插件
│          ├── pluginMdxHmr.ts // 用于mdx文件更新的准确获取热更新边界
│          └── pluginMdxRollup.ts // mdx插件集中rehype和remark插件
│      ├── plugin-routes
│          ├── fixtures // 单元路由测试目录
│          ├── index.ts // vite插件-用于生成约定式路由
│          ├── RouteService.test.ts // 路由服务层测试
│          └── RouteService.ts // 路由服务层
│      ├── build.ts // 打包命令相关
│      ├── cli.ts // cli 命令行相关
│      ├── config.ts // 解析用户配置文件相关
│      ├── dev.ts // 开发服务器
│      ├── index.ts // 导出默认配置
│      ├── unocssOptions.ts // unocss vite插件配置
│      └── vitePlugins.ts // 用于整合所有 vite 插件
│   ├── runtime // 运行时目录
│       ├── App.tsx
│       ├── client-entry.tsx // 客户端入口组件
│       ├── Content.tsx // 根据路由生成内容组件
│       ├── hooks.ts // 导出React-Context上下文
│       ├── index.ts // 导出所需配置
│       └── ssr-entry.tsx // 用于服务端渲染-拿到组件的html字符串
│   ├── shared // 公共共享目录
│       └── types // 公共类型目录
│   ├── theme-default // 默认主题目录
│       ├── components // 主题组件
│       ├── Layout // 主题布局
│           ├── DocLayout // 文档界面布局
│           ├── HomeLayout // 首页界面布局
│       ├── logic // 主题交互逻辑
│       ├── styles // 主题样式
│       └── index // 导出
├── .eslintignore
├── .eslintrc.cjs // eslint 配置
├── .gitignore
├── .npmrc // node 版本和包管理器相关
├── .prettierignore
├── .prettierrc.cjs // prettier 配置
├── commitlint.config.cjs // commitlint 配置
├── LICENSE
├── package.json
├── playwright.config.ts // playwright 配置
├── pnpm-lock.yaml
├── README.md
├── template.html // 模板html文件
├── tsconfig.json // ts配置
├── tsupconfig.ts // tsup配置
└── vitest.config.ts // vitest配置

启动开发服务器运行:

su-island dev docs

运行打包命令:

su-island build docs

这将生成打包目录 build 到 docs 下

运行如下命令进行预览

su-island start docs

tsup 编译运行监控命令:

pnpm dev

su-island 为什么要使用 tsup:

• 我们使用在 build 里使用import ora from 'ora'导入, 用tsc -w运行, 然后打包会报错
• 我们查看/dist/node/build.js, 会发现 ora 是通过 require 方式引入的, 而 ora 是一个 esm 的包, 因此这里会报错
• 值得注意的是 esm 可以导入 cjs 包, 反之则不行
• 根本原因: 模块加载机制不同, CJS 同步加载, ESM 异步加载

调试 cli 如下:

• 在 package.json 中声明 bin 字段
• 通过 npm link 将命令 link 到全局
• 执行 su-island dev 命令

su-island 使用 vitest 执行单元测试:

pnpm test:unit
# 开启 vitest ui界面
pnpm test:init

su-island 使用 playwright 执行 e2e 测试:

pnpm test:e2e

在执行 e2e 测试之前, 我们建议您使用如下命令暂行下载无头浏览器:

pnpm prepare:e2e

LICENSE

MIT Copyright (c) 2024 suzhenghui