GitBook搭建本地博客

安装与配置

• 参考 （node版本可能导致通过npm安装gitbook失败，可通过nvm管理多版本node）

GitBook命令

• gitbook init xxx：初始化一本书

• gitbook build：构建一本书的静态文件，生成的_book目录可用于部署到ngix或tomcat服务器中。

• gitbook install：安装book.json中指定的插件

• 启动gitbook本地服务：gitbook serve（会自动执行gitbook build）；启动本地服务后，修改文件会自动同步刷新页面内容

• gitbook pdf：生成pdf文件（需要安装calibre）

推荐插件

• github：添加github图标

• splitter：调节侧边栏宽度

• chapter-fold与expandable-chapters：两个插件结合实现目录折叠

• lightbox和popup：lightbox弹框等大查看图片，popup新页面查看大图，两者结合弹框查看大图

• search-plus：支持中文搜索，需移除自带的lunr和search插件

• code：显示代码行数并复制

• hide-element：隐藏内容

• tbfed-pagefooter：页脚copyright

• insert-logo：logo插件，即指定左上角图标，url开头建议带上/否则对于中文路径文档将无法获取到logo图片

• custom-favicon：指定网页图标，仅支持ico格式，url开头不带/

• favicon-absolute：绝对路径指定网页图标，url开头带/（推荐，不会出现favicon失效的问题）

• theme-comscore：高亮主题插件

• page-treeview：创建页内目录，默认会带上copyright；如果想要删除，需要在插件目录中打开：/node_modules/gitbook-plugin-page-treeview/lib/index.js，把方法generateContent的返回值改成"return renderContent;"

• back-to-top-button：回到顶部。其实可以不需要，任何页面都可借助ctrl+home / ctrl+end回到顶部/底部

• 其余插件：参考 （以上插件基本够用）

book.json配置示例：

{
    "plugins": [
        "github",
        "splitter",
        "chapter-fold",
        "expandable-chapters",
        "hide-element",
        "code",
        "-lunr",
        "-search",
        "search-plus",
        "popup",
        "lightbox",
        "insert-logo",
        "favicon-absolute",
        "tbfed-pagefooter",
        "theme-comscore",
        "page-treeview",
        "back-to-top-button"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/luckyboylch"
        },
        "hide-element": {
            "elements": [
                ".gitbook-link"
            ]
        },
        "insert-logo": {
            "url": "/logo/ThreeCloud.jpg",
            "style": "background: none; max-height: 30px; min-height: 30px; max- 174px; min- 174px"
        },
        "favicon-absolute": {
            "favicon": "/logo/summer.ico",
            "appleTouchIconPrecomposed152": "/logo/summer.ico"
        },
        "tbfed-pagefooter": {
            "copyright": "Copyright &copy lch 2021"
        }
    }
}

热加载

• 有时执行git serve命令会报错"找不到xxx.js"（每次文件还可能不一样）

  解决：修改C:UsersAdministrator.gitbookversions3.2.3liboutputwebsitecopyPluginAssets.js文件，将两处的confirm:true 均改为 confirm:false
  参考：https://gitbook.jackielee.top/Utils/GitBook/

• 修改文件有时热加载失败

  gitbook默认安装了livereload插件实现实时修改实时刷新页面的功能，但有时修改后并没有实时刷新反而页面挂了。
  解决：删除_book目录，会自动刷新
  根据是否有修改来删除_book目录：
  if [ -n "$(git status -s)" ];then
      rm -rf "_book/"
  fi

持久运行

• 在windows后台持久运行gitbook服务，实现随时修改随时访问gitbook：

  • 方法1：新建bat文件，双击执行即可：参考

  if "%1"=="hide" goto CmdBegin
  start mshta vbscript:createobject("wscript.shell").run("""%~0"" hide",0)(window.close)&&exit
  :CmdBegin
  ​
  cd "C:UsersxxxDesktopCloverBook"
  gitbook install
  LIMIT=10240 increase-memory-limit
  gitbook serve

  • 方法2（推荐）：新建shell脚本startBook.sh，双击执行即可。

  bookDir="C:UsersxxxDesktopCloverBook"
  cd ${bookDir}
  pid=`netstat -aon|grep "4000"|grep "LISTENING"| head -n 1 | awk '{print $NF}'`
  # pid为空才允许启动
  if [ -z "$pid" ];then
      echo "start local book server..."
      # 删除缓存
      rm -rf ${bookDir}"\_book"
      # 为避免修改插件配置，此处重新install下
      gitbook install > /dev/null
      # 解决长时间运行堆栈溢出问题，LIMIT必须放前面才会生效，直接执行increase-memory-limit的默认值也是10240
      LIMIT=10240 increase-memory-limit
      nohup gitbook serve &
  else
      echo "The local book server is running."
  fi
  sleep 1.5s
  # 直接关掉终端，后台进程仍被关掉。解决办法：exit退出终端部不要直接关
  exit

• 停止后台gitbook服务

  新建shell脚本stopBook.sh，双击执行即可。

pid=`netstat -aon|grep "4000"|grep "LISTENING"| head -n 1 | awk '{print $NF}'`
# pid不为空才需要停止
if [ -n "$pid" ];then
    echo "stop local book server..."
    taskkill //f //pid $pid
else
    echo "The local book server is not running."
fi
sleep 1.5s

• 内存溢出问题解决

  问题：长时间持久运行gitbook项目会挂掉，报错"FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory"。
  解决：
  

  #step1：安装插件：
  npm install -g increase-memory-limit
  #step2：切到项目根目录下执行：（LIMIT必须放前面；直接执行increase-memory-limit默认的limit为10240；该命令本质是在node_modules/.bin目录下的所有执行node命令的脚本中加上'--max-old-space-size=10240'参数）
  LIMIT=4096 increase-memory-limit
  #step3：再启动项目
  gitbook serve

  参考1 参考2