助你更了解CDN
当前位置:网站首页 > CDN搭建 > 正文

使用docsify+Git搭建自己的WiKi网站

作者:CDN发布时间:2021-05-31分类:CDN搭建浏览:189评论:0


导读:...
本文主要内容:0. 前言
1. 要求
2. 快速安装docsify
3. 自定义配置项
3.1 修改主页内容
3.2 定制侧边栏
3.3 定制导航栏
3.4 增加标题与Git右上角标
3.5 增加搜索框
3.6 增加封面
3.7 更多插件
4. 部署到Git
0. 前言身为技术人,一方面需要时刻更新自己的技术储备,学习最新的技术,另一方面在工作和项目开发时,面对遇到的各种各样的BUG,需要记住各式各样的对策。
生而为人,遗忘是最大的敌人。将学习到的知识点,解决BUG的对策,整理成文档,或许是对抗遗忘的最佳方案。
这诸多的技术文档,以怎样的方式进行展示?
每人都有自己的选择方案:
有人使用博客系统进行记录,如CSDN博客园简书自建博客;有人使用笔记软件,如印象笔记有道云笔记;有人使用第三方WiKi系统,如语雀看云;还有人,使用Git搭建属于自己的WiKi网站(文档网站),分享自己的笔记。目前,可用的WiKi网站开源项目中,比较火的有HexoGitBookVuePressdocsify等。
每个开源项目都有自己的优点。而docsify,是轻量级最高自定义化程度最高的项目。
本文将讲述如何使用docsify+Git搭建自己的WiKi网站
1. 要求在搭建之前,你的计算机需要安装以下环境:
名称简介官网Git分布式版本控制系统https://git-scm.comnpmNode.js 的包管理工具https://www.npmjs.com此外,你还需要:
掌握Markdown文档语法,docsify只能部署Markdown文档;拥有Gitee/GitHub账号,用来部署WiKi系统;掌握简单的HTML、JS语法,index文件需要自己配置。接下来我们将从以下几个方面详细讲解如何使用docsify+Git搭建自己的WiKi网站
快速安装docsify自定义配置项部署到Git2. 快速安装docsify1、创建好安装docsify的文件夹,比如:
图:存放项目的文件夹2、在上图的地址栏里输入cmd,按回车,打开命令行:
图:打开此文件夹命令行窗口3、使用如下命令安装 docsify-cli 工具:
npm i docsify-cli -g
4、使用如下命令初始化一个名为docs的项目:
docsify init ./docs
5、使用如下命令本地运行并预览网站
docsify serve docs
如下图是各个命令的执行过程。自动生成docs项目文件,并显示运行的网站地址为http://localhost:3000。
图:创建项目进入docs项目,有三个默认的初始化文件:
图:初始文件每个文件的作用如下:
index.html 网站入口文件README.md 作为主页内容渲染.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件浏览器访问 http://localhost:3000,即可看到网站效果:
图:默认主页3. 自定义配置项默认生成的网站效果,并非我们所需要的。
根据实际需求增加一些插件,更能满足我们的需求。
使用Web开发工具(WebStorm、PhpStorm等)打开docs文件,在编辑器中可以更好地编辑。
3.1 修改主页内容修改README.md图:修改README文件本地网站无需重启,刷新即可显示最新的内容:
图:新内容3.2 定制侧边栏1、打开index.html文件,找到<script>脚本处,增加配置 loadSidebar 选项,开启侧边栏loadSidebar: true, // 增加:自动加载侧边栏
如下图:
图:定制侧边栏2、在根目录创建一个名为_sidebar.md的文件:
图:定制侧边栏如果有如下图所示的系列文档需要在侧边栏进行展示:
图:侧栏需要显示的内容3、在_sidebar.md文件中,按照如下格式写入侧边栏内容:
<!-- 侧边栏 docs/_sidebar.md -->

- Laravel基础笔记
  - [1. 创建项目](/laravel/base/1.%20创建项目.md)
  - [2. 路由的基础知识](/laravel/base/2.%20路由的基础知识.md)
  - [3. 控制模块基础知识](/laravel/base/3.%20控制模块基础知识.md)
  - [4. 数据库操作](/laravel/base/4.%20数据库操作.md)
<!-- 以下略 -->
如图:
图:侧边栏书写格式4、本地预览网站自动加载了侧边栏:
图:新的侧边栏5、在index的配置文件中,增加subMaxLevel配置项,增加生成目录的层级:
subMaxLevel: 4, // 生成目录的最大层级
如下图:
图:修改目录层级修改后的效果如下图,文章内的标题也可作为侧栏显示出来:
图:修改后的目录层级3.3 定制导航栏1、index页配置 loadNavbar选项,开启导航栏loadNavbar: true, // 加载导航栏
如图:
图:配置导航栏2、在根目录创建一个名为_navbar.md的文件,并按如下格式写入导航栏信息:
<!-- _navbar.md 上面的导航栏  -->

* 我的平台

  * [知行达摩院](https://www.zxdmy.com)
  * [微信公众号](https://img.zxdmy.com/md/20210129164325.jpg!img2wp)
  * [CSDN](https://cxhit.blog.csdn.net/)
  * [Gitee](https://gitee.com/ZXAcademy)
  * [GitHub](https://github.com/ZXAcademy)


* 联系我们
  * [邮箱](contacts/email.md)
  * [电话](zh-contacts/phone.md)
如图:
图:导航栏书写格式3、查看导航栏:
图:导航栏效果3.4 增加标题与Git右上角标1、修改index配置信息:图:配置标题与角标2、查看预览页面:
图:修改效果3.5 增加搜索框1、修改index配置信息:引入JS文件
  <!--搜索插件-->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
修改配置
      // 搜索框的完整配置参数
      search: {
        maxAge: 86400000, // 过期时间,单位毫秒,默认一天
        paths: [], // or 'auto'
        placeholder: '输入内容检索',
        noData: '未检索到结果',
        depth: 1,// 搜索标题的最大层级, 1 - 6
        hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容
      }
如图:
图:配置搜索框2、查看预览页面:
图:搜索框效果3.6 增加封面1、修改index中的配置项coverpage,开启封面coverpage: true, // 开启封面
如图:
图:配置封面2、在根目录创建一个名为_coverpage.md的文件,并按如下格式写入封面信息
<!-- _coverpage.md 封面 -->

![logo](_media/icon2.jpg!img2wp)

# zxdmy.com <small></small>

> 知行达摩院 - 学无止境,知行致远!

- 记录课程学习笔记
- 记录科学研究进展
- 记录项目研发历程

[知行达摩院](https://zxdmy.com)
[开始使用](#欢迎使用)
如图:
图:封面书写格式3、效果:
图:封面效果3.7 更多插件当然还有更多插件,比如代码复制图片缩放翻页字数统计等。插件的配置和使用方式大同小异。有的插件需要添加JS增加配置项,有的插件只需要添加JS
需要更多插件可查阅官网开发文档:https://docsify.js.org
4. 部署到Git目前有两种部署方案,一种是部署至Gitee,另一种是部署到GitHub
下文以部署到GitHub为例。
部署至Gitee的步骤相同。
1、新建一个与GitHub用户名同名的公开仓库(Public),如下图所示:
图:创建Git项目为什么要同名?
这样的话,你的WiKi网站的域名就是:https://zxacademy.github.io/
如果使用其他的仓库名,如blog,那么你的WiKi网站域名就是:https://zxacademy.github.io/blog
为什么要公开仓库?
GitHub私有仓库开启Pages功能需要付费。
2、复制仓库地址,如图所示:
图:复制Git项目地址3、访问本地WiKi项目的根目录,右击,选择 Git Bash Here
图:打开Git Bash4、输入初始化命令
git init
如图:
图:初始化Git这时,项目根目录多了一个名为 .git 的文件夹
图:初始化效果这里建议在项目根目录中增加.gitignore 文件,屏蔽.git和.idea文件夹及其子目录文件:
图:增加忽略文件5、在GitHub 的项目页面,复制仓库地址,然后在上面的 bash 窗口中,输入如下命令并执行:
git remote add origin 仓库地址
如:
git remote add origin https://github.com/ZXAcademy/ZXAcademy.git
6、使用如下命令,将码云上的仓库 pull 到本地(注意本地项目中不要有和仓库中重名的文件,比如README.md、LICENSE等初始化仓库时产生的文件)
git pull origin master
如果远程仓库为空,会报如下错误,忽略,继续执行。如图:
图:拉取项目7、使用如下命令,将项目所有文件添加到git本地缓冲区
git add .
这里末尾的点(.),表示当前目录下的所有文件
8、使用如下命令为本次提交添加备注:
git commit -m '新添加的文件内容描述'
如图:
图:commit项目至本地使用如下命令,将项目推送到GitHub
git push origin master
图:
图:push项目9、前往GitHub网站查看上传成功的文件:
图:push成功10、按照下图开启Git Page服务:
图:开启Git Pages然后访问给出的site即可访问自定义的WiKi网站:
https://zxacademy.github.io/zxacademy
图:访问Git里的网站图:访问Git里的网站为什么我这里直接访问https://zxacademy.github.io 不行呢?
因为我的GitHub用户名为ZXAcademy,含有大写字母,所以不行。
如果以后需要增删改文章,直接修改后,push至Git仓库,即可实时更新WiKi网站。
以上就是使用docsify+Git搭建自己的WiKi网站的全部内容。
— The End —



推荐文章



觉得有帮助,欢迎赞赏



欢迎 发表评论:

  • 请填写验证码