专栏首页黑光技术使用gitbook来写文档和文章啦

使用gitbook来写文档和文章啦

前言

项目中文档管理是一个比较麻烦的事情,一般的做法都是写word文档,或者pdf;针对代码或者接口文档高级一点的可以使用Doxygen或者swagger这样的工具自动生成更新文档。但是项目中还有很多文档有是图文混合的。那这样的文档怎么有效管理呢?

在找了几个工具之后,发现了一个比较合适的工具gitbook。这个工具之前也接触过,主要是用来书籍编写管理,这方面确实做的非常专业。但是我发现用来做文档管理也是非常好用的,所以拿来测试了一下,效果还是不错的。看看这个效果,金杯也是左右分栏,左边是目录分类列表,右边是内容。还可以直接进行搜索。

gitbook介绍

gitbook其实是一个nodejs的一个工具软件,是基于nodejs的。gitbook.com就是基于这个工具开发的系统,他是一个提供了在线文档书籍开发管理的系统,它同时打通了github。gitbook作为一个工具当然也可以本地使用,gitbook也是开源的代码在github,在toolchain这个里专门介绍本地安装使用的方式。

接下来简单介绍一下安装方式,过程非常简单,我使用的ubuntu系统来使用,安装方法如下。

安装和简单使用

安装

apt-get install nodejs npm
npm install gitbook-cli

安装之后就可以使用了,直接运行一下gitbook命令看看:

root@c43ee1d7ec6f:/mnt/docs# gitbook 

  Usage: gitbook [options] [command]


  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a <version>
    alias [folder] [version]  Set an alias named <version> pointing to <folder>
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook    help                      List commands for GitBook    *                         run a command with a specific gitbook version

简单使用

新建一个目录,在目录中直接运行gitbook init就可以初始化一个项目了:

root@c43ee1d7ec6f:/mnt/docs# ls
README.md  SUMMARY.md 
root@c43ee1d7ec6f:/mnt/docs# 

gitbook使用markdown来写,所以创建的文件都是md文件,初始化文件有两个README.md和SUMMARY.md,其中SUMMARY.md是目录文件,整个图书或者文档的目录结构就是在这个文件中定义的。一般情况下这样的方式就可以编写文档了,如果需要图片也是非常简单的,在本地目录中新建图片文件夹,把图片放里面,再在文件中写引用路径即可。

高级使用

配置文件book.json

book.json是gitbook的配置文件,可以在里面进行整个文档站点主题名称、插件等的配置,如下:

{    
"title": "黑光技术",    
"description": "",    
"author": "helight",    
"language": "zh-hans",    
"styles":{        
     "website":"styles/website.css"
    },    
"plugins": [        
     "search",        
     "-sharing"
    ],    
"pluginsConfig": {}
}

插件

gitbook比较好玩的一点就是其插件,有很多有意思的插件,可以让站点更好玩,比如有菜单格式的插件,有分享插件,有主题插件等等,下面是我比较长用的一些插件,简单介绍一下:

    "plugins": [        
        "search",       
        "insert-logo",       
        "alerts",       
        "expandable-chapters",       
        "splitter",        
        "anchor-navigation-ex",        
        "page-footer-ex",        
        "-sharing"
    ],

是一个内置的插件,主要做站点搜索,非常强大,可以搜索所有文档的内容。

是一个可以在左上角插入一个logo图片的插件,就像上面截图中的一样,可以插入自己的logo图片。

alerts

这个是主要是一些样式的插件,可以根据配置针对不同的内容定义不同的颜色。

expandable-chapters

是一个可以是的目录收缩的差价,也比较实用。

splitter

是一个控制左右分栏大小的插件,可以拖动控制左右分栏。

anchor-navigation-ex

是一个展示页面大纲的空间,可以按照段落来展示,可以快捷转挑到页面的相应位置。

是一个脚标配置插件,自动为每个页面生成脚标。

-sharing

组件前面加上-号的意思就是不使用这个组件,一般是针对内置组件。

自定义站点css

使用这种方式可以自定义控制站点的样式。

    "styles":{        
        "website":"styles/website.css"
    },

典型的应用就是定义右面页面的宽度,定义隐藏“发布到gitbook”这个链接地址等等。下面我简单列出一些我用过的一些样式。

.gitbook-link {    
  display: none !important;
}
.page-inner {   
  max-width: 1000px;    
  padding: 2px 2px 2px 2px;
}
.book .book-summary .book-logo {    
  text-align: left !important;    
  padding: 0px 0px !important;    
  display: block !important;
}

好了,开始我们的写作历程吧,这样可以非常好的积累我们的写作文章,说不定哪天还可以积累出一本书来哦。

OK, Let's go!!!

看完本文有收获?请分享给更多人

关注「黑光技术」加星标,关注大数据+微服务

本文分享自微信公众号 - 黑光技术(helight_dt),作者:helight

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2018-11-26

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 使用gitbook来写文档和文章啦

    项目中文档管理是一个比较麻烦的事情,一般的做法都是写word文档,或者pdf;针对代码或者接口文档高级一点的可以使用Doxygen或者swagger这样的工具自...

    黑光技术
  • Golang UnitTest单元测试

    单元测试是程序开发者适用一段代码来验证另外一段代码写的是否符合预期的一种相对高效的自我测试方法。

    黑光技术
  • Golang官方依赖管理工具dep学习使用笔记

    今天在看一个内部项目的时候发现内部一个项目的体积非常大,一看原来是vendor占了很大空间。里面的库都是静态提交到git库的,更新和管理都很不方便,想想java...

    黑光技术
  • 使用gitbook来写文档和文章啦

    项目中文档管理是一个比较麻烦的事情,一般的做法都是写word文档,或者pdf;针对代码或者接口文档高级一点的可以使用Doxygen或者swagger这样的工具自...

    黑光技术
  • synchronized锁住的是代码还是对象

    在Java中,synchronized关键字是用来控制线程同步的,就是在多线程的环境下,控制synchronized代码段不被多个线程同时执行。synchron...

    用户1205080
  • 如何使用Spiped在Ubuntu 16.04上加密到Redis的流量

    Redis是一个开源键值数据存储,使用内存存储模型和可选的磁盘写入来实现持久性。它具有事务,发布/订阅消息传递模式以及其他功能之间的自动故障转移功能。Redis...

    黑色技术
  • 前端开发工具总结

    主要是为了帮助大家搜集一下前端开发中要用到的一些东西,打造一个前端开发工具字典,方便大家查阅。

    用户1462769
  • 打造前端瑞士军刀,为你开发路上披荆斩棘

    主要是为了帮助大家搜集一下前端开发中要用到的一些东西,打造一个前端开发工具字典,方便大家查阅。

    石燕平
  • 云盘精灵搜索不可描述版

    ❷测试自己的IE浏览器没有问题以后关闭浏览器,打开后台回复“云盘精灵”获得并解压的软件,正式使用。搜索“小白课代表”

    课代表
  • ES6的Promise

    相信凡是写过javascript的童鞋也一定都写过回调方法(callback),简单说回调方法就是将一个方法func2作为参数传入另一个方法func1中,当fu...

    庞小明

扫码关注云+社区

领取腾讯云代金券