next-docify
是一个基于Next.js
的静态网站生成工具
next-docify
在设计上主要是参考了Docusaurus, gitbook
- 易用性:基于
Next.js
的封装,是一个单独的功能模块,只需更改脚本启动语法糖就可以享受markdown
数据的便捷引入 - 灵活性:可以对文档指定不同的渲染模版
- 定制化:本身模块提供的是数据层的抽象,没有
View
的引入;如果使用基于Next.js
搭建起来的服务,渲染的文档数据只需在需要展示时通过import
来引入。 - 按需加载:数据层面都是通过
chunk
模块来动态引入
安装
npm i next-docify --save
或者
yarn add next-docify --dev
准备工作
package.json
文件
更新
更新为
next.config.js
文件
更新moduleexports = /* config options here */
更新为
const withNextDocifyConfig = ; moduleexports = ;
.babelrc
file
更新添加next-docify/dynamic-site-import-plugin
到babel
配置
site.config.js
文件
添加在根目录提供markdown
数据源的配置文件site.config.js
;参数详情参考
moduleexports = site: 'next-docify template' component: './pages/docs' accessPath: '/docs' docDirName: 'docs' docBaseName: 'tutorial';
快速入门
markdown
数据
引入在进行文档数据渲染时,开发者比较关心的是如何能够获取想要的markdown
数据文件;而next-docify
就提供的是下面的import
方式
;
site
接受两个参数,并且返回一个Promise
对象;
accessPath
(required): 需要跟site.config.js
中的配置一致;主要是通过这个设置来获取到底docs
数据源的位置;通过这个参数的设置,data
数据中会包含postmeta
和manifest
两个对象。
path
(optional): 作为可选参数,通过path
的设置可以获取具体到某一个文件作为作为数据源;通过这个参数的设置,data
数据中会再添加dataSource
对象,dataSource
包含的是所要渲染的markdown
文件内容。
site.config.js
配置读取文档信息的配置文件,返回的数据类型<Array|object>
;
moduleexports = site: 'next-docify template' component: './pages/docs' accessPath: '/docs' docDirName: 'docs' docBaseName: 'tutorial';
site
(optional): 设置当前渲染页面的name
component
(required): 设置当前文档对应应该渲染到的页面组件,从而实现对不同的文档指定不同的渲染模版accessPath
(required): 设置文档页面的访问路径docDirName
(required): 文档根目录docBaseName
(required): 文档相对目录
目录结构
├── docs └── tutorial ├── Summary.md └── quick-start.md
docs
的结构控制
文档的结构是通过文档的目录下的summary.md
解析获得;它的结构来自于gitbook的处理方式。按照offset
来区分parent-children
的关系;通过(quick-start.md)
的形式来指定访问/tutorial/quick-start
路径时应当提供的文档数据。
* tutorial * quick-start
markdown文档格式
如果想要添加文档内容层面的meta
data;比如说创建时间
,描述信息
以及标题
之类的信息的话,可以通过下面的形式插入到markdown
文件的开头。
---title: quick startdescription: 新手教程createAt: 2018-04-12---
---
和---
之间的键值对会被解析作为dataSource
中的meta
对象数据。对于键没有任何的约束处理,开发者可以按照个人的需求填写想要的数据。
注意点
accessPath
是返回对象数组中各个对象的主键
,需要和site
中的参数accessPath
一致,这样才能够获取关于文档的结构信息manifest
和文档meta数据postmeta
.
FAQ
其它静态网站生成工具的对比
- 比较流行的静态网站生成工具,比如jekyll, Docusaurus等,支持模版的选择和一定程度上模版自定义实现;但是如果说希望得到更高度化的自定义,都会受到使用模版的样式影响。
next-docify
是作为一个模块提供的是渲染数据的抽象。假如说使用的是Next.js
作为网站的解决方案,渲染文档数据只是它的部分页面,那么就可以通过引入next-docify
实现文档数据提供的逻辑。
针对的用户
next-docify
目前主要针对的是前端开发者并且是使用Next.js
构建的服务。- 如果说是普通的非前端开发者用户的话,可以通过
create-next-docify-app
按照模版的形式来选择使用自己想要的模版。