类库从零部署-第二步：编写文档&发布官网

doudizhu
224 阅读1分钟

系列文章

编写使用文档

生成目录结构

安装gitbook

$ sudo npm i gitbook-cli -g

$ gitbook -v // 查看版本信息。此命令会默认同时安装 GitBook。


// 报错: "cb.apply is not a function"
// 解决方式：
$ sudo vim /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js
  将65行起的三行都注释掉：
  // fs.stat = statFix(fs.stat)
  // fs.fstat = statFix(fs.fstat)
  // fs.lstat = statFix(fs.lstat)

// 原因：为了解决旧版本返回uid+gid时候的数据类型的问题，新版本此处反而会干扰执行
// 参考博文: https://mizeri.github.io/2021/04/24/gitbook-cbapply-not-a-function/

SUMMARY.md 生成目录的配置文件

# Summary

* [项目介绍](README.md)
* [使用文档](doc/use/README.md)
    * [使用1](doc/use/use1.md)
    * [使用2](doc/use/use2.md)
* [二次开发](doc/dev/README.md)
    * [开发1](doc/dev/dev1.md)
    * [开发2](doc/dev/dev2.md)

生成目录初始化

$ gitbook init


// 报错：TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received an instance of Promise
// 解决方式：降级node版本
$ touch ~/.bash_profile
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
$ nvm install 12.22.3
$ nvm use 12.22.3

// 再次执行
$ gitbook init

写文档

doc/dev/README.md

# 二次开发

- 下载 `git@github.com:doudizhu/fast-cache-ddz.git`
- 编辑`src`目录的源码
- 执行`npm run release`编译
- 执行`npm run example`启动示例

doc/use/README.md

    # 使用文档
    
    ## 初始化
    ```js
    var FC = window.FastCache;
    var cache = new FC();
    ```
    
    ## 设置
    ```js
    cache.set('a',100)
    ```
    
    ## 获取
    ```js
    cache.get('a')

gitignore忽略,新增

_book
.DS_Store

提交

$ git add .
$ git commit -m '# 编写使用文档 ## 生成目录结构'
$ git push

生成md文档对应html页面

  gitbook build

发布官网

此处与项目代码分离发布，也可文档与项目代码合并在一起，配置 github page 访问，如：/(_book)

创建 github page

访问：https://github.com/new
  Repository name:
    fast-cache-ddza.github.io
  Add a README file
  点击：create repository

跳转至：https://github.com/doudizhu/fast-cache-ddza.github.io
  settings
    githup pages
      点击：Check it out here!

配置 github page 访问

跳转至： https://github.com/doudizhu/fast-cache-ddza.github.io/settings/pages
  Source
    Branch:main 
    /(root)
    点击：Save

配置简单内容测试

克隆项目代码

mkdir package && cd package
git clone git@github.com:doudizhu/fast-cache-ddza.github.io.git
code fast-cache-ddza.github.io/

index.html 创建入口页

<p>hello fast-cache</p >

提交访问:

git add .
git commit -m '## 配置 github page 访问 ## 配置简单内容测试'
git push

访问：https://doudizhu.github.io/fast-cache-ddza.github.io/

生成项目文档，发布官网

  gitbook build
  cp -r _book/ ../package/fast-cache-ddza.github.io

  cd ../package/fast-cache-ddza.github.io
  git pull
  git add .
  git commit -m 'update'
  git push

  cd ../fast-cache-ddza.github.io

访问：https://doudizhu.github.io/fast-cache-ddza.github.io/
avatar
文章
阅读
粉丝