gitbook使用

安装

我是在Win10的wsl下安装使用的.

  1. 安装node.js和npm. Ref

    # Enable the NodeSource repository
    curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
    # install
    sudo apt install nodejs
    # verify
    node --version
    npm --version
    
  2. 安装gitbook

    # install
    sudo npm install -g gitbook-cli
    # verify
    gitbook -V
    

基本使用

  1. 初始化

    gitbook init
    

    它会生成
    README.md: 本书介绍
    SUMMARY.md: 定义本书目录

  2. 编辑

    可用VSCode编辑

  3. 输出

    1. 输出静态网页

      gitbook build
      

      它会生成_book文件夹

    2. 输出pdf

      # install
      sudo apt install calibre
      npm install gitbook-pdf -g
      # 命令,会生成book.pdf的文件
      gitbook pdf .
      
  4. 预览

    gitbook --port 4000 serve ./
    

    可以在http://localhost:4000/实时预览

配置文件

在根目录下可以使用配置文件book.json. 更多内容可参见这里.

主题

gitbook可以修改主题,参考 TemplatingTheming.

Gitbook可以通过自定义插件来修改主题, 本主题是修改自theme-hqbook. 本主题取了名字叫coolx, 放在了github上.

[!TIP|label: 使用private plugin] 在book.json中可以使用private的github repo作为插件, 语法为"theme-coolx@git+https://github.com/xinntao/gitbook-plugin-theme-coolx"

在修改主题时候,我们需要在本地调试插件:

[!TIP|label: 在本地修改和调试插件]

  1. 在gitbook plugin folder, npm link
  2. 在gitbook folder, npm link gitbook-plugin-name

    Reference

另外一个使用了gitbook实现了sphinx主题的theme-veeam(但好像没有必要,直接用sphinx就好了=-=).

其他需求 (插件)

只要把插件写在book.json, 然后gitbook install, 就会自动安装用到的package, 不需要单独一个个安装.

  1. 自动生成目录(SUMMARY.md)Ref

    # install
    npm install -g gitbook-summary
    # cmd
    book sm
    

    它会根据字母序来组织,如果需要保留顺序,可在题目前加上数字.
    如果有多余的目录,比如"node_modules", 则可以在book.json中加入

    "ignores": [
     "node_modules"
    ]
    
  2. 折叠目录
    使用插件: expandable-chapters.
    需要配合插件 chapter-fold 一起用
    折叠目录有一个缺点,就是默认是折叠的,这个没法默认展开,有点不友好.

  3. 页面添加修改时间等页脚
    使用插件: tbfed-pagefooter.

  4. 支持中文搜索,及搜索结果高亮
    使用插件: search-plus

  5. 使用Math Latex
    使用插件: katex

  6. 字体颜色背景
    使用插件: emphasize.
    使用示例:
    This text is highlighted with markdown!
    This text is highlighted in red!
    This text is highlighted with a custom color!
    源码: 把\%替换成%

    This text is {\% em \%}highlighted with **markdown**!{\% endem \%}<br>
    This text is {\% em type="red" \%}highlighted in red!{\% endem \%}
    This text is {\% em color="#ff0000" \%}highlighted with a custom color!{\% endem \%}
    
  7. 带颜色字体
    红色字体示例.

    <span style="color:red;">红色字体</span>
    
  8. 代码高亮
    使用插件: prism.

    npm install gitbook-plugin-prism
    npm install gitbook-plugin-prism-themes
    

    还需要配置pluginsConfig;禁用自带的-highlight.
    Prism Themes

  9. 添加TODO List
    使用插件: todo
    源码:
    - [ ] item 1
    - [x] item 2

    • item 1
    • item 2
  10. 查看修改源码
    使用插件: editlink.

  11. 使用醒目的NOTE, TIP等
    使用插件: flexible-alerts.

    [!NOTE] 源码

    > [!NOTE]
    > Contents
    


    支持修改显示的label:

    [!NOTE|label: 修改显示的label]

    > [!NOTE|label: 修改显示的label]
    > Contents
    


    TIP:

    [!TIP]

    > [!TIP]
    > Contents
    


    WARNING:

    [!WARNING]

    > [!WARNING]
    > Contents
    


    DANGER:

    [!DANGER]

    > [!DANGER]
    > Contents
    


    COMMENT:

    [!COMMENT]

    > [!COMMENT]
    > Contents
    

以下的功能暂时没有用,或在coolx主题中已经提供.

  1. 生成当前页的目录
    使用插件: simple-page-toc
    在需要生成目录的地方加上 <!-- toc --> .

  2. 添加Toc到侧边悬浮导航以及回到顶部按钮
    使用插件: anchor-navigation-ex.

  3. 使用Google统计
    使用插件: ga. 但目前版本好像不支持.

References

Gitbook 介绍:
http://gitbook.zhangjikai.com/
https://tonydeng.github.io/gitbook-zh/gitbook-howtouse/index.html

更多插件推荐:
http://www.unclealan.cn/index.php/front/153.html
https://www.goodzzp.com/custom/plugin/other/index.html
https://zhousiwei.gitee.io/2019/06/24/GitBook%E7%9B%B8%E5%85%B3%E9%85%8D%E7%BD%AE%E5%8F%8A%E4%BC%98%E5%8C%96/
https://segmentfault.com/a/1190000019806829

Copyright © Xintao all right reserved,powered by Gitbook修改时间: 2021-10-28 00:50:45

results matching ""

    No results matching ""