iuap-design/blog

gitbook插件开发

LiuYueKai opened this issue · 9 comments

LiuYueKai commented

gitbook插件开发

本次主要记录开发gitbook插件的一些记录，后续会根据开发进度不断完善。以下文档内容可参考：
https://github.com/iuap-design/gitbook-plugin-iuap-design

创建插件

1.创建仓库名字以gitbook-plugin-开头，后面为插件的具体名称
例如：gitbook-plugin-iuap-design
2.再package.json中需要添加

"engines": {
    "gitbook": ">1.x.x"
},

之后gitbook才能识别此插件

插件核心文件说明

index.js

module.exports = {
    book: {
        assets: './book',
        js: [
            'iuap-desigin.js'
        ],
        css: [
            'iuap-desigin.css'
        ]
    },
    hooks: {    
        "page": function (page) {             
            _.forEach(page.sections, insertAnchors);
            return page;
        }
    }
};

book下配置内容会出现在最终的产出内容中，并且在浏览页面时才执行。
hooks下配置hook，此例中的page可以获取gitbook插件生成的默认section标签中的内容，同时对此部分内容进行编辑修改，影响最终产出的html文件。

package.json

插件的配置信息。详细说明参考：
http://blog.csdn.net/zhangjk1993/article/details/50380403

插件使用

在book.json中的pulgins属性中添加创建的插件
例如：

"plugins":[
    "iuap-design"
]

插件调试

book内容调试

在book.json中添加插件执行执行

$ gitbook serve

或者

$ gitbook build

gitbook插件会根据book.json中的ouput产出html文件。进入此文件夹通过以下路径

gitbook\plugins\gitbook-plugin-iuap-design

可找到插件index.js中module.exports下book中配置的js及css，修改js及css刷新页面即可看到效果。

hooks内容调试

此部分内容只能通过重新执行

$ gitbook serve

或者

$ gitbook build

来进行调试。

以上内容只是目前开发过程的一些总结，有错误的地方欢迎提出来。

GuoYongfeng commented

@LiuYueKai 总结的不错，赞一个。

gitbook-plugin-iuap-design 插件用于增强并且优化文档展示，在iUAP Design官网开发过程中起到重要作用。

但同时也还需要继续改进：

  • 【BUG】通过变量实现页面标题的可配置。在 book.json 中配置字段，在插件中通过book对象拿到后进行book内容的填充。
  • 【Feature】页面加载资源优化，保证页面在点击切换过程中体验顺畅
  • 【BUG】解析带有js的md文件时出现报错，组件库tab下有4个页面有此情况
  • 【Feature】代码复制功能，优先级可以相对靠后
  • 【Feature】移动端可用，目前左侧目录宽度写死，导致移动端直接无法看页面内容
  • 【Feature】需要给生成的页面加上和首页一样的面包图标呼出导航，否则在移动端无法切换
  • 【BUG】生成的页面左侧导航带二级时，样式错乱并且需要优化
onvno commented

参照官方api获取book.json中的变量，一直获取不到,提示undefined.
根据初步了解，是不是book.json中pluginsConfig自定义的变量只能在md文档中获取。明天会验证下，如果我的理解是错误的，望指导。

onvno commented

1.1.7-1.1.8为目前提交，做以下调整：

  • 【BUG】更改二级菜单样式错乱问题
  • 【Feature】增加gitbook目录汉堡包按钮效果
  • 【BUG】增加移动端gitbook内容默认展示效果

目前主导航暂汉堡包按钮未调整，同时文杰反馈官网主导航 文字 和 按钮 样式要抽时间碰一下。目前先跟月凯调整js加载相关问题。

onvno commented

1.1.9更新“

  • 【Feature】js/css/header/footer加载方式更新
onvno commented

1.1.12更新

  • 调整二级菜单css样式及展示部分padding值，保留目前的字号，线框，背景
onvno commented

1.1.16更新

  • 更改整体CSS样式
  • 资源优化，去掉不需要的u/u-tree/u-grid资源加载
  • 增加内页主导航移动端效果
  • 修改左侧移动端导航侧滑bug
  • 修改左侧二级导航高度bug
  • 移动端隐藏backtop,锚点icon
onvno commented

1.1.17更新

  • bug调整:JSdemo模态框,tab,tree效果正常显示
  • bug调整:更改侧导航样式
  • 增加:目录及主体内容动画效果

备注：本次demo显示后，发现md文件生成页面样式有问题，下一版本更新

onvno commented

1.1.18更新

  • 增加移动端样式
7iang commented

也是醉了，插件开发完之后怎么发布？可以帮忙介绍下吗？

  • 👍1