docsify - 生成文档网站简单使用

时间: 作者: 点击量:
教程

https://segmentfault.com/a/1190000017576714

GitBook 3.2.3 网络版:

教程:https://www.cnblogs.com/gjb724332682/p/9290917.html
案例 :http://doc.keydatas.com/

简介
GitBook 是一个基于 Node.js 的命令行工具,可使用 GitHub / Git、Markdown、AsciiDoc来制作精美的电子书。GitBook 可以将文档作为静态网站或电子书(PDF,ePub或Mobi格式)输出。
GitBook.com 是使用 GitBook 格式创建和托管图书的在线平台,它提供托管,协作功能和易于使用的编辑器。
本文示例运行的系统为CentOS Linux release 7.4.1708,nodejs版本为v8.11.3。
 
安装nodejs
访问nodejs官网,下载nodejs,下载后的文件名为node-v8.11.3-linux-x64.tar.xz。
1.执行 tar -Jxvf node-v8.11.3-linux-x64.tar.xz,将nodejs解压到当前目录。
2.需要创建软链接,执行 ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/node /usr/local/bin/node、ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/npm /usr/local/bin/npm。
 
安装GitBook
1.执行 npm install gitbook-cli -g安装GitBook命令行工具,自动选择版本,同时也会安装GitBook。
2.安装完成后,可以在nodejs目录里的bin目录下看到gitbook软连接文件,执行 ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/gitbook /usr/local/bin/gitbook,让该命令全局可用。
npm命令的-g选项是指全局安装,将模块安装到全局目录中,全局目录可以用npm config get prefix 命令获取以及用npm config set prefix ""命令设置,不加-g则是将模块下载到当前命令行所在目录。
npm update gitbook-cli -g是更新命令,npm uninstall gitbook-cli -g是卸载命令。
 
GitBook命令
gitbook -h显示GitBook 帮助信息,gitbook help显示GitBook可用命令。
GitBook可以在本地安装多个版本并在执行命令的时候指定某个版本,如果指定的版本还没安装就会自动下载安装,下载后的GitBook会被放到~/.gitbook目录下。相关操作有:
gitbook ls:列出本地已安装的gitbook版本
gitbook current:列出当前活动的gitbook版本
gitbook ls-remote:列出远程可以下载安装的gitbook版本
gitbook fetch [version]:下载安装某个gitbook版本
gitbook uninstall [version]:卸载某个gitbook版本
gitbook update:更新到最新的gitbook版本
如 gitbook -v 4.0.0-alpha.6 current会显示GitBook version is 4.0.0-alpha.6,而gitbook -V会显示gitbook和gitbook cli的运行版本。
 
初始化GitBook
1.执行 mkdir gitbook-demo && cd gitbook-demo 创建一个gitbook-demo目录并进入到该目录。
2.执行gitbook init 初始化GitBook,会在当前目录下生成 README.md 和 SUMMARY.md文件。SUMMARY.md是GitBook的目录文件。README.md是电子书介绍文件,必须存在。
也可以先手动创建SUMMARY.md,再执行gitbook init,如果SUMMARY.md中配置的文件夹和文件不存在,就会自动创建文件夹和文件,已经存在的文件夹和文件不会被覆盖。一般情况下是先在gitbook-demo目录下执行gitbook init,然后将要制作文档的md文件放到gitbook-demo里,接着再修改SUMMARY.md。
gitbook init的更多用法参考gitbook help。
 
生成静态网站
在gitbook-demo目录下执行 gitbook build,会在gitbook-demo目录下生成一个 _book 目录,里面的内容为静态网站的文件,可以将 _book 目录下的文件拷贝到nginx、httpd等web服务器内,也可以使用gitbook serve命令启动一个web服务,默认端口是4000。
gitbook build和gitbook serve的更多用法参考gitbook help。
 
GitBook目录结构
基本结构如下:
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
book.json:全局配置数据 (可选)
README.md:介绍电子书(必须)
SUMMARY.md:目录 (可选)
GLOSSARY.md:词汇、术语列表(可选)
 
SUMMARY.md格式
基本格式为:* [描述](文件路径或者http超链接)。文件路径是相对于SUMMARY.md所在的目录的。
支持多级目录,每级目录多缩进4个空格。例如:
* [介绍](README.md)
* [概述](index.md)
* [接口](api.md)
* [注意事项](note.md)
 
GLOSSARY.md格式
基本格式是一组h2标题加上描述,在其他页面用到这些词汇时会突出显示,鼠标放上去就会显示术语描述。术语暂不支持中文。
例如:
## test
测试定义
 
book.json格式
GitBook 允许使用灵活的配置自定义电子书,这些选项在 book.json 文件中指定,格式为json。
root:包含除了 book.json外的所有电子书文件的根目录。
structure:指定readme, summary, glossary和 languages的文件名,参考 Structure paragraph。
title:电子书名,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的。
description:书籍的描述,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的。
author:作者名。在GitBook.com上,这个字段是预填的。
isbn:国际标准书号 ISBN。
language:本书的语言类型 ,默认值是 en。
direction:文本阅读顺序,可以是 rtl (从右向左)或 ltr (从左向右),默认值依赖于 language 的值。
gitbook:应该使用的GitBook版本。使用 SemVer 规范,并接受类似于 “> = 3.0.0” 的条件。
 
Structure paragraph
除了 root 属性之外,还可以指定readme, summary, glossary和 languages 的文件名,而不是使用默认名称,如README.md。这些文件必须在项目的根目录下,不接受的路径。
structure.readme:readme 文件名(默认值是 README.md )
structure.summary:summary 文件名 (默认值是 SUMMARY.md)
structure.glossary:glossary 文件名(默认值是 GLOSSARY.md)
structure.languages:languages 文件名 (默认值是 LANGS.md)

上一篇:在线智能AI文章伪原创 + 原创度检测

下一篇:PHP 将页面url网址转换成图片、用于抓取截图、保存当前页面快照

注册体验: