给自己的项目发布一个文档吧
给自己的项目发布一个文档
Github Page配置
在上一篇,我们搭建了一个脚手架,方便我们更快的开始一个项目。这篇我们将使用github page给这个项目发布一个文档
我们可以在 github 仓库的 Setting-Pages界面进行文档的设置,例如我这个仓库,把文档源设置成了当前仓库master分支的/docs目录,之后我们只需要往这个目录下添加静态文件就可以在对应的site展示文档了。
使用Docsify
使用Docsify能更方便地发布文档,只需要编辑md文件即可修改页面信息,因此我们使用docsify来构建文档
安装
首先你需要安装node.js,这里就不细说了
然后npm i docsify-cli -g
全局安装docsify-cli工具
docsify init ./docs
初始化文档,我们设置的github page源是docs目录,所以初始化的是docs目录
初始化成功后会看到docs目录下会有几个文件
index.html
入口文件README.md
会做为主页内容渲染.nojekyll
用于阻止 GitHub Pages 忽略掉下划线开头的文件
直接编辑README.me 就能更新文档内容了
本地查看
docsify serve docs
即可在本地查看页面
配置
另外如果要对页面进行详细配置可以看官方文档和这篇文章,docsify,Docsify使用指南(打造最快捷、最轻量级的个人&团队文档) - 追逐时光者 - 博客园 (cnblogs.com)。
这里是我的配置文件以及最终效果
配置文件:https://github.com/weloe/go-web-demo/tree/master/docs
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>go-web-demo</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<!-- 默认主题 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
<!-- 定义加载时候的动作 -->
<div id="app" class="loading">加载中...</div>
<script>
window.$docsify = {
// 项目名称
name: 'go-web-demo',
// 仓库地址,点击右上角的Github章鱼猫头像会跳转到此地址
repo: 'https://github.com/weloe',
// 侧边栏支持,默认加载的是项目根目录下的_sidebar.md文件
loadSidebar: true,
// 导航栏支持,默认加载的是项目根目录下的_navbar.md文件
loadNavbar: true,
// 封面支持,默认加载的是项目根目录下的_coverpage.md文件
coverpage: false,
// 最大支持渲染的标题层级
maxLevel: 5,
// 自定义侧边栏后默认不会再生成目录,设置生成目录的最大层级(建议配置为2-4)
subMaxLevel: 4,
// 小屏设备下合并导航栏到侧边栏
mergeNavbar: true,
/*搜索相关设置*/
search: {
maxAge: 86400000,// 过期时间,单位毫秒,默认一天
paths: 'auto',// 注意:仅适用于 paths: 'auto' 模式
placeholder: '搜索',
// 支持本地化
placeholder: {
'/zh-cn/': '搜索',
'/': 'Type to search'
},
noData: '找不到结果',
depth: 4,
hideOtherSidebarContent: false,
namespace: 'Docsify-Guide',
}
}
</script>
<!-- docsify的js依赖 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<!-- emoji表情支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
<!-- 图片放大缩小支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
<!-- 搜索功能支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
<!--在所有的代码块上添加一个简单的Click to copy按钮来允许用户从你的文档中轻易地复制代码-->
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
</body>
</html>
<style>
.loading {
position: relative;
width: 50px;
perspective: 200px;
}
.loading:before,
.loading:after {
position: absolute;
width: 20px;
height: 20px;
content: "";
animation: jumping 0.5s infinite alternate;
background: rgba(0, 0, 0, 0);
}
.loading:before {
left: 0;
}
.loading:after {
right: 0;
animation-delay: 0.15s;
}
@keyframes jumping {
0% {
transform: scale(1) translateY(0px) rotateX(0deg);
box-shadow: 0 0 0 rgba(0, 0, 0, 0);
}
100% {
transform: scale(1.2) translateY(-25px) rotateX(45deg);
background: #000;
box-shadow: 0 25px 40px #000;
}
}
</style>
最终效果
https://weloe.github.io/go-web-demo/#/
发布
当你配置完文件,直接push到github上时就会自动发布,前提是你按照文章开头设置了page
成功发布完后能在仓库的commit记录和仓库的Environments看到这两个