最新公告
  • 欢迎您光临起源地模板网,本站秉承服务宗旨 履行“站长”责任,销售只是起点 服务永无止境!立即加入钻石VIP
  • GitBook 实践

    正文概述 掘金(吧啦啦啦)   2020-12-12   764

    最近在重构项目,需要调研一下帮助文档。之前项目里面用的是 gitbook 也好多年了,觉得有点丑,想找个现代化一点的哈哈哈。但是时间有限,也是一顿百度,借鉴了许多,在这里就是稍微整理一下吧! 上来就找到了这个文章,看了下时间还不算太旧,里面说调研了 vuePress 和 gitbook ,我基本上也是按照这两个方向来的。

    这片文章先说说 GitBook.

    Base Demo

    全局安装 gitbook cli 工具.

    npm install gitbook-cli -g
    

    然后检查 gitbook 有没有安装成功

    gitbook -V
    

    出现下面这样子就安装成功了 GitBook 实践

    初始化书籍目录

    gitbook init
    

    GitBook 实践 README.md 是项目起来之后默认地址(/)指向的文件

    SUMMARY.md 是目录

    写文档

    这里只粘出来目录结构和SUMMARY.md GitBook 实践

    # Summary
    
    * [首页](README.md)
    * [介绍](docs/introduct.md)
    * [第一章](docs/chapter1/README.md)
      * [第一节](docs/chapter1/section1.md)
    

    运行

    gitbook serve
    

    GitBook 实践 打开浏览器 http://localhost:4000 GitBook 实践

    基本 Demo 就完事了~

    其他

    多语言。

    gitbook 支持多语言,在根目录下加一个 LANGS.md 文件加上支持的语言就行了,可以参考Learn Git这个地址。 GitBook 实践 然后这个时候进来之后就是这个页面,有点丑哈,这个插件gitbook-plugin-multilingual-index说是可以自定义多语言主页。

    我没有尝试。也没有尝试能不能在页面上弄个下拉修改语言的方案,我现在就搁在左侧菜单里面了。

    关于 GitBook 全文检索。

    本来是因为 gitbook 画风不好看,所以才调研的帮助文档,结果在最后定好用 vuepress 之前,产品忽然间发现 vuepress 不能满足他们全文搜索的功能,所以最终方案用的还是 gitbook.然后我就下去看了一下gitbook 全文检索是怎么做的。

    不管是 gitbook 默认的搜索还是增强的搜索,他们原理都一样。把这些文件整成一个大 json,然后用 jQuerygetJSON 去读文件,搜索,就拿上面的 demo 为例。打包之后生成了一个 search_index.json,里面的内容是这样的。

    {"index":{"version":"0.5.12","fields":[{"name":"title","boost":10},{"name":"keywords","boost":15},{"name":"body","boost":1}],"ref":"url","documentStore":{"store":{"./":["首页"],"docs/introduct.html":["介绍"],"docs/chapter1/":["第一章"],"docs/chapter1/section1.html":["1","第一节"]},"length":4},"tokenStore":{"root":{"1":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":1}}},"docs":{},"首":{"docs":{},"页":{"docs":{"./":{"ref":"./","tf":11}}}},"介":{"docs":{},"绍":{"docs":{"docs/introduct.html":{"ref":"docs/introduct.html","tf":11}}}},"第":{"docs":{},"一":{"docs":{},"章":{"docs":{"docs/chapter1/":{"ref":"docs/chapter1/","tf":11}}},"节":{"docs":{"docs/chapter1/section1.html":{"ref":"docs/chapter1/section1.html","tf":10}}}}}},"length":5},"corpusTokens":["1","介绍","第一章","第一节","首页"],"pipeline":["stopWordFilter","stemmer"]},"store":{"./":{"url":"./","title":"首页","keywords":"","body":"首页\n"},"docs/introduct.html":{"url":"docs/introduct.html","title":"介绍","keywords":"","body":"介绍\n"},"docs/chapter1/":{"url":"docs/chapter1/","title":"第一章","keywords":"","body":"第一章\n"},"docs/chapter1/section1.html":{"url":"docs/chapter1/section1.html","title":"第一节","keywords":"","body":"1-1\n"}}}
    

    然后我看了一下我们重构前项目里面这个大 json 文件有 15M 那么大

    自定义配置

    上面就是一个基础款,但是他基础款的东西直接拿过来好像不是很好用,比如说

    • 搜索: 默认搜索是没有关键词高亮的,所以你可以禁用掉默认的搜索,改成 search-pro
    • 分享: 默认的分享都是国外的一些网站,在国内不是很适用

    还可以增强一下你写的文档,比如说

    • 代码复制
    • 回到顶部
    • 目录展开收起
    • 隐藏指定元素

    我们可以通过配置文件实现一些自定义的配置,在根目录下新建book.json,就可以自定义配置了。

    我的配置是这样滴

    {
      "title": "test",
      "author": "test",
      "description": "description",
      "language": "zh-hans",
      "plugins": [
        "-highlight",
        "copy-code-button",
        "search-pro",
        "-search",
        "-lunr",
        "splitter",
        "-sharing",
        "anchor-navigation-ex",
        "expandable-chapters",
        "back-to-top-button",
        "splitter",
        "hide-element"
      ],
      "pluginsConfig": {
        "anchor-navigation-ex": {
          "showLevel": false,
          "mode": "float",
          "float": {
            "floatIcon": "fa fa-navicon",
            "showLevelIcon": false,
            "level1Icon": "fa fa-hand-o-right",
            "level2Icon": "fa fa-hand-o-right",
            "level3Icon": "fa fa-hand-o-right"
          },
          "showGoTop": false
        },
        "hide-element": {
          "elements": [".gitbook-link"]
        }
      }
    }
    

    更多配置可以参考这里

    一般 gitbook 的插件都是叫 'gitbook-plugin',所以可以自行去 NPM 上找。

    配置上加上插件要 重新的 gitbook install.这个命令贼拉慢,所以这个时候你直接用 npm 安装即可。忘记在哪里看到说是gitbook install 是把用到的插件全都安装一遍,所以慢什么的,但是这个我装的时候没留意。

    部署优化

    叫这个标题不是很准确,我就是给他加了一个 package.json 方便上到服务器打包部署。我把 gitbook 依赖放到了 package.json 里面,就不用全局安装 gitbook 了。

    上 package.json

    {
      "name": "Test",
      "version": "1.0.0",
      "description": "description",
      "main": "index.js",
      "dependencies": {
        "gitbook-cli": "^2.3.2",
        "gitbook-plugin-anchor-navigation-ex": "^1.0.14",
        "gitbook-plugin-back-to-top-button": "^0.1.4",
        "gitbook-plugin-baidu-tongji": "^1.0.4",
        "gitbook-plugin-collapsible-menu": "^1.0.3",
        "gitbook-plugin-copy-code-button": "^0.0.2",
        "gitbook-plugin-donate": "^1.0.2",
        "gitbook-plugin-expandable-chapters": "^0.2.0",
        "gitbook-plugin-github-buttons": "^3.0.0",
        "gitbook-plugin-hide-element": "^0.0.4",
        "gitbook-plugin-page-toc-button": "^0.1.1",
        "gitbook-plugin-search-pro": "^2.0.2",
        "gitbook-plugin-splitter": "^0.0.8",
        "gitbook-plugin-tbfed-pagefooter": "^0.0.1"
      },
      "devDependencies": {},
      "scripts": {
        "start": "gitbook serve",
        "build": "gitbook build"
      },
      "repository": {
        "type": "git",
        "url": "xxxxxx"
      },
      "keywords": [
        "help"
      ],
      "author": "Xu",
      "license": "ISC"
    }
    
    

    参考链接:

    1. Leader 让我做 CMS 帮助中心的技术选型,我撸了 VuePress 和 GitBook,然后选择...
    2. ChengWei's Blogs
    3. gitbook使用及book.json详细配置

    起源地下载网 » GitBook 实践

    常见问题FAQ

    免费下载或者VIP会员专享资源能否直接商用?
    本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
    提示下载完但解压或打开不了?
    最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度网盘软件或迅雷下载。若排除这种情况,可在对应资源底部留言,或 联络我们.。
    找不到素材资源介绍文章里的示例图片?
    对于PPT,KEY,Mockups,APP,网页模版等类型的素材,文章内用于介绍的图片通常并不包含在对应可供下载素材包内。这些相关商业图片需另外购买,且本站不负责(也没有办法)找到出处。 同样地一些字体文件也是这种情况,但部分素材会在素材包内有一份字体下载链接清单。
    模板不会安装或需要功能定制以及二次开发?
    请QQ联系我们

    发表评论

    还没有评论,快来抢沙发吧!

    如需帝国cms功能定制以及二次开发请联系我们

    联系作者

    请选择支付方式

    ×
    迅虎支付宝
    迅虎微信
    支付宝当面付
    余额支付
    ×
    微信扫码支付 0 元