本文章是用来手把手教如何搭建一个文档网站,需要使用到Markdown文档,不懂的可以百度一下它的语法,下载一个Typora,几分钟就能学会。搭建好的网站你可以使用它当做自己的专属仓库,可以搭建在GitHub、Gitlab、Gitee上
插件的官网地址是 docsify,如果需要更精细化的配置可以查阅官网。本教程是手把手教你如何搭建网站到GitHub上,后续会持续更新Gitlab和Gitee等其他网站。
教程的演示地址:https://lemon6767.github.io/#/
感兴趣的看下去吧(▽)
源代码:https://github.com/lemon6767/lemon6767.github.io/tree/master
1、准备工作
- 保证自己的电脑安装了NPM 地址
- 有一个Github账号
2、初始化
全局安装 docsify-cli
工具
npm i docsify-cli -g
新建文件夹并初始化
mkdir amoqi-learn
cd amoqi-learn
docsify init ./
初始化成功之后,可以看到 amoqi-learn
目录下有以下几个文件
-
index.html
入口文件 -
README.md
会做为主页内容渲染 -
.nojekyll
用于阻止 GitHub Pages 忽略掉下划线开头的文件
直接编辑 docs/README.md
就能更新文档内容,也可以添加更多页面
发布:docsify serve ./
然后访问:http://localhost:3000
3、修改配置文件
修改配置文件index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="./lib/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app">加载中</div>
<script>
window.$docsify = {
name: 'amoqi-learn',
repo: 'https://github.com/lemon6767/lemon6767.github.io/tree/master',
loadNavbar: true,
loadSidebar: true,
coverpage: true,
auto2top: true,
maxLevel: 2,
subMaxLevel: 3,
search: {
placeholder: '搜索',
noData: '找不到结果!',
depth: 3
},
alias: {
'/.*/_sidebar.md': '/_sidebar.md',//防止意外回退
'/.*/_navbar.md': '/_navbar.md'
},
plugins: [
]
}
</script>
<!-- 插件JS -->
<script src="./lib/docsify/lib/docsify.min.js"></script>
<!-- 搜索插件 -->
<script src="./lib/docsify/lib/plugins/search.js"></script>
<!-- 复制代码插件 -->
<script src="./lib/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
<!-- 语法着色库 -->
<script src="./lib/prismjs/components/prism-bash.js"></script>
<script src="./lib/prismjs/components/prism-java.js"></script>
<script src="./lib/prismjs/components/prism-sql.js"></script>
<script src="./lib/prismjs/components/prism-yaml.js"></script>
</body>
</html>
3.1 添加插件
自定义添加了搜索插件、复制代码插件、语法着色插件。具体参考地址可以访问网站
3.2 开启侧边栏
选项 loadSidebar:ture
表示开启了侧边栏,需要定义一个 _sidebar.md
文件,文件的内容就是我们侧边栏的内容。
如下我添加了如下内容,格式为无序列表
* 序章
* [简介](foreword/foreword_01.md)
* [精品软件清单](foreword/foreword_02.md)
创建foreword文件夹,创建 foreword_01.md
、foreword_02.md
文件。
修改之后重启就会发现文档网站多了侧边栏,点击侧边栏对应的内容就在右边显示
3.3 添加封面
coverpage: true
为了能让我们的文档网站有封面,我们还需要新建一个名字为 _coverpage.md
的文件,内容如下
# amoqi-learn
> 快速学习、快乐生活
[Get Started](README.md)
4、部署到Github
4.1、创建仓库
在github上创建一个仓库,名字为 用户名.github.io
,必须这样命名才能进行访问,例如,我的是 lemon6767.github.io
4.2、上传代码并配置
创建docs文件夹
,把我们的文件复制到docs文件夹
里,如果不复制也是可以的,文件目录如下:
上传代码,这块就不累述了。
进入github仓库,点击settings -> Pages
选择分支和文件夹,如果没有配置docs文件夹,文件都在根目录的选择 /(root
),点击
Save`,上方就会出现上图提示语,点击提示语链接就能访问了。
Your site is published at https://lemon6767.github.io/
5、结语
码字不易,希望能多多支持。一名四年工作经验的程序猿,目前从事物流行业的工作,有自己的小破网站amoqi.cn。欢迎大家关注公众号【CoderQi】,一起来交流JAVA知识,包括但不限于SpringBoot+微服务,更有奇奇学习过程中学习的视频、面试资料和专业书籍等免费放送,希望大家能够喜欢。