探索了一阵,最终采用nest + docsify方案
废话不多说,直接开摆
背景介绍
考虑到适用于公共模块的说明文档,内部使用,故为了减少开发人员的参与使用成本,放弃如 hexo、hugo 等博客类文档方案(当然,用于自己的技术总结类站点文档也是妥妥的)
docsify特点
- 简单轻便
- 无需编译生成html,浏览器端渲染,易维护
- 主题、插件丰富,支持多语言
- 服务器成本低、部署方便
快速开始
$ npm i docsify-cli -g
$ docsify init ./docs
nest特点
- TS完美支持
- 社区活跃
- 可扩展性好
- 底层基于express,三方库完善
快速开始
$ npm i -g @nestjs/cli
$ nest new project-name
上菜
文件目录
服务端核心代码
# main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { join } from 'path';
import { Logger } from '@nestjs/common';
import { NestExpressApplication } from '@nestjs/platform-express';
const port = parseInt(process.env.PORT, 10) || 3000;
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.setGlobalPrefix('api');
app.useStaticAssets(join(__dirname, '..', 'docs'));
await app.listen(port);
Logger.log(`服务已启动,请访问 http://localhost:${port}`);
}
bootstrap();
# app.controller.ts
import { Controller, Post, Body, Param } from '@nestjs/common';
import { execCmd } from './utils';
@Controller()
export class AppController {
// constructor(private readonly appService: AppService) {}
@Post('hook')
async hook(@Body() body, @Param() param) {
await execCmd('git pull');
console.log(body, param['ref'], 'pull done');
}
}
前端核心配置
window.$docsify = {
repo: 'https://github.com/stackwar/nest-doc-demo',
loadSidebar: true,
loadNavbar: true,
auto2top: true,
subMaxLevel: 2,
name: 'wycommon',
alias: {
'/zh-cn/jsbridge': '/jsbridge',
},
// routerMode: 'history',
notFoundPage: {
'/': '_404.md',
},
search: {
placeholder: {
'/zh-cn/': '搜索',
'/': 'Type to search',
},
noData: {
'/zh-cn/': '找不到结果',
'/': 'No Results',
},
},
count: {
countable: true,
fontsize: '0.9em',
color: 'rgb(90,90,90)',
language: 'chinese',
},
pagination: {
previousText: '上一篇',
nextText: '下一篇',
crossChapter: true,
crossChapterText: true,
},
formatUpdated: '{MM}/{DD} {HH}:{mm}',
plugins: [
// function (hook) {
// var footer = [
// '<hr/>',
// '<footer>',
// '<span><a href="https://stackwar.github.io">stackwar</a> ©2022.</span>',
// '<span>Proudly published with docsify</a>.</span>',
// '</footer>',
// ].join('');
// hook.afterEach(function (html) {
// return html + footer;
// });
// },
function (hook, vm) {
hook.beforeEach(function (html) {
var url =
'https://github.com/stackwar/nest-doc-demo/blob/master/docs/' +
vm.route.file;
var editHtml = '[📝 EDIT DOCUMENT](' + url + ')\n';
return (
editHtml +
html +
'\n----\n' +
'Last modified {docsify-updated} '
);
});
},
],
};
Tips
借助webhooks直接起飞 参见demo