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 © 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