故事背景:很多时候对外发布的产品需要一份html格式的文档
首先要了解的是 word直接转成html是不现实的,需要通过md文件来转换。
我们本节课讨论的Gitbook即是在MD基础上进行操作的。
所以
任务一:安装typora软件,用于编辑md文件,简单自学一下即可掌握
任务二:全局安装gitbook
npm install -g gitbook-cli
任务三:打开当前目录,执行
$ gitbook init
你会看到两个文件,README.md 和 SUMMARY.md
将SUMMARY.md 文件拖入typora进行编辑
# 目录
* [前言](README.md)
* [第一章](one/README.md)
* [1](one/one.md)
* [2](one/two.md)
* [3](one/three.md)
* [第二章](two/README.md)
* [第三章](three/README.md)
然后保存编辑,再次执行gitbook init,gitbook会根据这个summary文件内的结构创建相应的文件。
任务四:运行
$ gitbook serve
然后可以根据提示在本地查看运行效果
任务五:生成html
$ gitbook build
执行后会在_book目录下生成我们需要的html文件,那么剩下的工作量其实就是维护md,这里建议使用git
拓展:
这里要补充两点
第一: gitbook社区拥有很多插件,我们可以通过gitbook install命令来安装,需要我们创建一个book.json文件,我自己使用的这份json文件可以用来参考
{
"author": "yanhuinan",
"description": "devDoc",
"extension": null,
"generator": "site",
"title": "二次开发文档",
"language": "1c, abnf, accesslog, actionscript, ada, apache, applescript, arduino, armasm, asciidoc, aspectj, autohotkey, autoit, avrasm, awk, axapta, bash, basic, bnf, brainfuck, cal, capnproto, ceylon, clean, clojure, clojure-repl, cmake, coffeescript, coq, cos, cpp, crmsh, crystal, cs, csp, css, d, dart, delphi, diff, django, dns, dockerfile, dos, dsconfig, dts, dust, ebnf, elixir, elm, erb, erlang, erlang-repl, excel, fix, flix, fortran, fsharp, gams, gauss, gcode, gherkin, glsl, go, golo, gradle, groovy, haml, handlebars, haskell, haxe, hsp, htmlbars, http, hy, inform7, ini, irpf90, java, javascript, json, julia, kotlin, lasso, ldif, leaf, less, lisp, livecodeserver, livescript, llvm, lsl, lua, makefile, markdown, mathematica, matlab, maxima, mel, mercury, mipsasm, mizar, mojolicious, monkey, moonscript, n1ql, nginx, nimrod, nix, nsis, objectivec, ocaml, openscad, oxygene, parser3, perl, pf, php, pony, powershell, processing, profile, prolog, protobuf, puppet, purebasic, python, q, qml, r, rib, roboconf, rsl, ruby, ruleslanguage, rust, scala, scheme, scilab, scss, smali, smalltalk, sml, sqf, sql, stan, stata, step21, stylus, subunit, swift, taggerscript, tap, tcl, tex, thrift, tp, twig, typescript, vala, vbnet, vbscript, vbscript-html, verilog, vhdl, vim, x86asm, xl, xml, xquery, yaml, zephir",
"variables": {},
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": true,
"wechat": true
}
},
"output": null,
"pdf": {
"fontSize": 12,
"footerTemplate": null,
"headerTemplate": null,
"margin": {
"bottom": 36,
"left": 62,
"right": 62,
"top": 36
},
"pageNumbers": false,
"paperSize": "a4"
},
"plugins": [
"-livereload",
"theme-comscore",
"-lunr",
"-search",
"search-plus@^0.0.11",
"simple-page-toc@^0.1.1",
"-highlight",
"prism@^2.0.3",
"prism-themes@^0.0.2",
"advanced-emoji@^0.2.1",
"anchors@^0.7.1",
"include-codeblock@^3.0.2",
"ace@^0.3.2",
"emphasize@^1.1.0",
"katex@^1.1.3",
"splitter@^0.0.8",
"[email protected]",
"tbfed-pagefooter@^0.0.1",
"expandable-chapters-small@^0.1.7",
"donate@^1.0.2",
"favicon@^0.0.2",
"todo@^0.1.3",
"terminal@^0.3.2",
"alerts@^0.2.0",
"include-csv@^0.1.0",
"markdown-video",
"anchor-navigation-ex",
"embed-pdf",
"chart@^0.2.0"
],
"pluginsConfig": {
"theme-default": {
"showLevel": true
},
"prism": {
"css": ["prismjs/themes/prism-okaidia.css"],
"lang": {
"flow": "javascript"
}
},
"include-codeblock": {
"template": "ace",
"unindent": true,
"edit": true
},
"tbfed-pagefooter": {
"copyright": "Copyright © xdatainsight@yanhuinan",
"modify_label": "该文件修订时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
},
"donate": {
"wechat": "./img/pay.jpg",
"title": "",
"button": "联系作者",
"wechatText": "18380464736"
},
"simple-page-toc": {
"maxDepth": 3,
"skipFirstH1": true
},
"sectionx": {
"tag": "b"
},
"favicon": {
"shortcut": "favicon.ico",
"bookmark": "favicon.ico"
},
"terminal": {
"copyButtons": true,
"fade": false,
"style": "flat"
}
}
}
第二:我们的gitbook还拥有生成pdf epub mobi格式的功能,但是经过试验,效果不太好,暂时不推荐