一个好的开源软件必须要有一个完善的文档才容易被推广,那么我们在如何简单、高效、低成本的搭建一个文档网站呢?今天我们使用Github+docsify来零成本轻松打造一个在线文档系统!
不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件,所有转换工作都是在运行时。只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages。
npm i docsify-cli -g
在cmd 中下载仓库
命令:
git clone
进入项目目录中
docsify init ./docs
运行成功后,在docs 目录下会自动生成三个文件:
-
index.html 入口文件
-
README.md 会做为主页内容渲染
-
.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
docsify serve docs
docsify 的配置都在
index.html
中的window.$docsify
函数中配置。
- 修改 html 代码
<!-- 注释:默认首页
<div id="app"></div>
-->
<!-- 添加:加载对话框1:https://docsify.js.org/#/quickstart?id=loading-dialog -->
<div data-app id="main">Please wait...</div>
- 修改
window.$docsify
代码
// 为 el 指定 html 标签
window.$docsify = {
el: '#main',
};
window.$docsify = {
repo: 'docsifyjs/docsify',
// or
repo: 'https://github.com/docsifyjs/docsify/',
};
window.$docsify = {
maxLevel: 4,
};
-
创建
_navbarm.md
文件如果没有指定文件,则默认加载
_navbar.md
文件 -
设置index.html文件
window.$docsify = { // load from _navbar.md loadNavbar: true, // load from nav.md loadNavbar: 'nav.md', };
-
创建
_sidebar.md
文件如果没有指定侧边栏文件,则默认加载
_sidebar.md
文件 -
设置index.html文件
window.$docsify = { // load from _sidebar.md loadSidebar: true, // load from summary.md loadSidebar: 'summary.md', };
此选项将完全隐藏您的侧边栏,并且不会在侧面呈现任何内容。
window.$docsify = {
hideSidebar: true,
};
window.$docsify = {
subMaxLevel: 2,
};
如果没有指定文件,默认使用README.md
作为网站的主页。
window.$docsify = {
// Change to /home.md
homepage: 'home.md',
// Or use the readme in your repo
homepage:
'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};
-
创建
_coverpage.md
文件如果没有指定封面文件,则默认加载
_coverpage.md
作为封面文件 -
修改
index.html
文件window.$docsify = { coverpage: true, // Custom file name coverpage: 'cover.md', // multiple covers coverpage: ['/', '/zh-cn/'], // multiple covers and custom file name coverpage: { '/': 'cover.md', '/zh-cn/': 'cover.md', }, // 设置访问主页时候仅加载封面 onlyCover: false, };
window.$docsify = {
logo: '/_media/icon.svg',
};
window.$docsify = {
name: 'docsify',
};
name 字段还可以包含自定义 HTML,以便于自定义:
window.$docsify = {
name: '<span>docsify</span>',
};
window.$docsify = {
nameLink: '/',
// For each route
nameLink: {
'/zh-cn/': '#/zh-cn/',
'/': '#/',
},
};
window.$docsify = {
themeColor: '#3F51B5',
};