前端技术类站点文档搭建(docsify+nest)

145 阅读1分钟

探索了一阵,最终采用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

上菜

文件目录

image.png

服务端核心代码

# 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> &copy;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