gitbook初体验

Rocket
1,516 阅读3分钟

引言

  • 讲解使用gitbook提供的工具在本地开发一个书籍文档部署到自己的服务上

1、node安装

参考我的另一篇文章，建议使用nvm管理node版本 链接

2、gitbook客户端安装

nvm安装完node后，基本也npm也安装成功，使用npm安装gitbook的客户端

npm install gitbook-cli -g

3、gitbook目录初始化

新建一个gitbook目录

mkdir gitbokk
cd gitbook
gitbook init
  • gitbook init会在空项目中创建README.md和SUMMARY.md两个文件
  • README.md文件是项目的介绍文件。
  • SUMMARY.md是gitbook书籍的目录

4、本地启动服务

gitbook serve

Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 21 plugins are installed
info: 15 explicitly listed
info: loading plugin "search-pro"... OK
info: loading plugin "back-to-top-button"... OK
info: loading plugin "chapter-fold"... OK
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "tbfed-pagefooter"... OK
info: loading plugin "code"... OK
info: loading plugin "flexible-alerts"... OK
info: loading plugin "popup"... OK
info: loading plugin "localized-footer"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 20 pages
info: found 25 asset files
warn: "options" property is deprecated, use config.get(key) instead
warn: "this.generator" property is deprecated, use "this.output.name" instead
warn: "navigation" property is deprecated
warn: "book" property is deprecated, use "this" directly instead
info: >> generation finished with success in 2.6s !

Starting server ...
Serving book on http://localhost:4000

5、打包

gitbook build

会在当前目录生成一个_book目录

在_book文件夹里有一个index.html文件，这个文件就是文档网站的HTM入口，把_book文件夹复制到服务器，然后把web服务的入口引向index.html即可完成文档网站的部署。

如果你想查看输出目录详细的记录，可使用gitbook build ./ --log=debug --debug来构建查看

6、生成电子书

gitbook pdf ./ ./mybook.pdf


gitbook epub ./ ./mybook.epub


gitbook mobi ./ ./mybook.mobi

7、配置文件讲解

如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。 配置文件写完后，需要重启服务或者重新打包才能应用配置

touch book.json

{
    "title": "我的一本书",
    "author" : "18211167516@163.com",
    "description" : "我第一本书的描述，很好", 
    "keywords": "Gitbook使用手册,markdown,gitbook,",
    "language" : "zh-hans",//语言
    "plugins": [
        "-lunr",
        "-search",
        "search-pro", 
        "back-to-top-button",
        "chapter-fold",
        "expandable-chapters",
        "highlight",
        "tbfed-pagefooter",
        "code", 
        "flexible-alerts", 
        "popup",
        "localized-footer"
    ],
    "pluginsConfig": { 
        "localized-footer": {
            "hline": true,        
            "filename": "./FOOTER.md" 
        },
        "theme-default": {
            "showLevel": true
        },
        "anchor-navigation-ex": {
            "isShowTocTitleIcon": true
        },
        "tbfed-pagefooter": {
            "copyright":"",
            "modify_label": "该文件最后修改时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "code": {
            "copyButtons": true
        }
    },
    "links" : { 
        "sidebar" : {
            "我的连接" : "https://www.baidu.com"
        }
    },
    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}
  • title 标题
  • author 作者
  • description 描述，对应gitbook网站的description
  • language 使用的语言，zh-hans是简体中文，会对应到页面的
  • structure 指定 Readme、Summary、Glossary 和 Languages 对应的文件名，下面是这几个文件对应变量以及默认值：
Variable	Description
structure.readme	Readme file name (defaults to README.md)
structure.summary	Summary file name (defaults to SUMMARY.md)
structure.glossary	Glossary file name (defaults to GLOSSARY.md)
structure.languages	Languages file name (defaults to LANGS.md)
比如想把readme文件个名字，则可以使用如下配置

"structure": {
    "readme": "introduction.md"
},

使用这个配置后，gitbook服务就不会找readme文件，而去找introduction文件当项目说明，这样就可以把readme文件完全当成代码仓库说明文档了。
  • plugins 使用的插件列表，所有的插件都在这里写出来，然后使用gitbook install来安装。
  • pluginsConfig 插件的配置信息，如果插件需要配置参数，那么在这里填写。
  • links 可以给侧导航栏添加链接信息
"links" : {
    "sidebar" : {
        "个性链接1" : "https://www.baidu.com"
    }
}
  • styles 自定义页面样式，各种格式对应各自的css文件
"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}

8、实用插件

9、bug问题

  • 假如碰到了 Error: ENOENT: no such file or directory, stat

找到.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js

confirm: true

改成

confirm: false
  • Error: Error with command “svgexport”
npm install svgexport -g

10、部署到GitHub Pages

github新建一个仓库

cd _book
git init
git add -A
git commit -m 'init'
git remote add origin <yourgit>
git branch -m main
git push -u origin main

在github网站上的仓库里面点击Settings -> GitHub Pages选项中 -> Source里面选择gh-pages branch 然后点击Save按钮，然后在GitHub Pages下面就会看见一个网址，这个网址就是最终的网站。

微信截图_20210527161838.png

结尾

与诸君共勉之，希望对您有所帮助

avatar
文章
阅读
粉丝