给自己的项目发布一个文档吧 - 秋玻
source link: https://www.cnblogs.com/weloe/p/17374287.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
给自己的项目发布一个文档
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看到这两个
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK