docser

1.1.3 • Public • Published

文档系统

主要用于管理开发文档,例如前端的组件库,前端的模块等,都可以提供一个良好的文档,本文档也不仅限于前端项目,可以用于任何的项目的介绍,不过前端项目可以直接在前端预览。

运行

安装全局命令行工具即可

npm -g i docser

快速上手

你可以在命令行执行 docser serve这个命令会快捷开启一个服务器,并且扫描你当前命令行所在目录的所有md文件,你可以直接在目录里书写md文件 最好有个规范,如果你想配置这个运行路径,那么你可以参考下面的配置。 目前只支持显示一级和二级,不支持更多层级,之后会将其进行优化

示范模板

项目启动你可以使用示范模板来使用,这里提供了快捷命令,这里提供了docs.config.jsinstall.jsdocs.routes.js 的写法示例

docser init

这样能快速生成示范案例,通过 docser serve 启动开发服务器,通过docser build进行项目文档打包

配置文件

本文档系统使用ElementUI的文档系统进行调整使用,其中有两个文件必不可少,需要放在 docs.config.jscontext的指向的地址,默认是 当前的工作路径下的docs 工作路径也是指的是当前命令行的位置

  1. install.js 负责安装程序组件,例如ElementUi就可以在这里安装
  2. docs.routes.js 负责渲染页面引入路由以及md文档界面
  3. docs.config.js 负责管理项目的标题,文档位置,输出路径等

docs.config.js

需要导出成一个对象(commonjs格式)

属性名称 描述 类型
outputDir 输出路径,打包编译后输出到的文件夹路径 string
context 上下文地址,用于指定文档的根路径 string
title 用于定义文档显示的标题 string
port 端口 number
search 是否开启搜索功能,默认开启 boolean
cache 缓存,暂时无法使用 boolean
pages 多页模式,默认单页模式 boolean
tailwindcss tailwindcss启用状态,默认禁用 boolean

docs.routes.js

需要导出成一个数组 (不限格式)

属性名称 描述 类型
path 路由路径,如果有children属性会被认定为父级路由路径 string
title 路由显示标题 string?
name 路由名称 string?
groupName 分组名称,只在拥有children属性时有效 string?
component md组件页面地址 string
redirect 路由索引到的时候,跳转地址填这个就不可填写component string?
children 子路由,和上面的属性一样 object[]

:::warning 上面的三个属性都可以设置路由名称,但优先级为 title > groupName > name 但name也是路由的name,不推荐设置这个为标题,优先考虑title 次选 groupNamename可以和其他的搭配使用 :::

install.js

需要导出成一个函数 (不限格式)

参数名称 描述 类型
Vue vue对象 Vue
VueRouter vue的路由对象 VueRouter

文档系统有何好处

从以下几个点来说名文档的好处

  1. 规范模块,建立信任。在文档书写后可以通过预览服务器快速访问文档从而提升开发效率
  2. 预览组件,文档带有demo功能,书写组件后可以直接预览。如ui库,能预览能剩下很多时间
  3. 减少冗余,当组件或代码工具多了的时候,项目维护变得比较复杂。对于项目不是特别熟悉的来说,没有文档更难知道是否已经设计某个功能,有文档系统能快速检索是否存在此功能,提高开发效率

更新日志

下面是描述更新内容

1.0.4

  1. 更新搜索功能
  2. 添加search的配置,可以在配置项查看
  3. 更换路由方式
  4. 添加worker加载能力

1.0.5

  1. 修复配置初始化出现错误
  2. 添加多页模式可以通过配置来配置单页和多页, 在多页模式下,第一项会被当成导航,在目录模式下,第一个目录会被当成导航
  3. 增加初始化配置文件,例如docs.config.jsdocs.routes.js,可以参考docser init --help查看命令帮助

1.0.6

  1. 修复用户空间和全局空间的依赖版本冲突的问题,优先采用全局空间

1.0.7

  1. 添加postcss和tailwindcss 3.2.1
  2. 添加缓存配置,可以通过cache: false忽略
  3. 修复搜索跳转问题
  4. 添加 :::template 模板块

1.0.8

  1. 重新设置cache的值,默认不开启,添加缓存配置,可以通过cache: true 开启,如果项目出现TypeError: Cannot read properties of undefined (reading 'buildMeta') 则先删除缓存目录
  2. 添加命令行支持 -m 开启多页,-c 开启缓存
  3. 添加tailwindcss的md例子文件
  4. 添加命令行指定context,例如docser serve dist dist就会被认为是context,默认是process.cwd()build命令同理,可以通过docser serve --help查看帮助

1.0.9

  1. 修复搜索热更新和搜索失效的问题

1.1.0

  1. 添加路由加载进度条,错误提示
  2. 默认禁用tailwindcss,在配置项中配置,或者在命令行中配置
  3. 重构ui界面
  4. 添加页面描点

1.1.1

  1. 添加mermaid代码块
  2. 优化md的文档加载,使其能更好的加载
  3. 修复代码块的热更新问题
  4. 移除:::template容器代码块,默认代码块自带此功能
  5. 对图片限制宽度
  6. 取消cdn代码,改为本地 (部分cdn还是会很慢,特殊情况可能加载失败)

1.1.2

  1. 修复热更新问题
  2. 修复vue无法使用import多个问题,隔离上下文环境
  3. 添加代码块运行方法,目前只针对js代码
  4. 本地化字体图标

1.1.3

  1. 取消的代码块高度限制
  2. 居中 view-wapper元素

Package Sidebar

Install

npm i docser

Weekly Downloads

1

Version

1.1.3

License

MIT

Unpacked Size

1.42 MB

Total Files

76

Last publish

Collaborators

  • app_net