--- title: Docsify top: true cover: true toc: true mathjax: false summary: >- 实用Docisy搭建个人博客 tags: - Docsify - 博客搭建教程 categories: - "折腾" reprintPolicy: cc_by author: TianZD abbrlink: 2eeac462 date: 2022-04-27 12:23:53 coverImg: img: password: --- # Docsify [toc] [codesheep微信文章](https://mp.weixin.qq.com/s?__biz=MzU4ODI1MjA3NQ==&mid=2247510629&idx=1&sn=48e481b9f176ebeb2d68342af3f33317&chksm=fddd7ca1caaaf5b73efe05dcb5b87c570344708e2a7bddffb5c8bd08638b631e595a4d2b646c&mpshare=1&scene=1&srcid=0223V1apWEBHMQrFHzWwPQiN&sharer_sharetime=1645581220908&sharer_shareid=9615bd3fd5ee967a5d2b03b78f23d393#rd) ## 框架对比 其实做这种网站,完全不用自己手写,现成的工具太多了,这地方随便举几个典型例子吧。 ### Hexo 这是一个大家用得非常广泛的静态博客,两年前咱们这里就已经演示过它的使用以及部署上线。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232332738.png) 工具地址:https://hexo.io ### VuePress 一款基于Vue框架驱动的静态网站生成器,比较符合用于知识文档网站的建站需求,现在用的小伙伴也很多。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232332139.png) 工具地址:https://vuepress.vuejs.org/ ### docsify docsify同样是一个很好用的知识文档网站生成框架,轻量简便,而且无需构建,写完内容就可以直接发布,界面干净又卫生。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232332353.png) 工具地址:https://docsify.js.org/ - 无需构建,写完文档直接发布 - 容易使用并且轻量 (压缩后 ~21kB) - 智能的全文搜索 - 提供多套主题 - 丰富的 API - 支持 Emoji - 兼容 IE11 - 支持服务端渲染 SSR ([示例](https://github.com/docsifyjs/docsify-ssr-demo)) ### Gitbook GitBook也是一个可以用来制作知识库文档以及精美电子书网站的工具框架,不少技术电子书文档都是用它来做的。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232332503.png) 工具地址:https://github.com/GitbookIO/gitbook ## 前置环境 docsify唯一需要的一个前置工具就是`npm`工具 查看是否安装及版本 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232334892.png) 如果没有的话,直接在本地电脑上安装一个`node.js`环境就可以了。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232334539.jpeg) 不管是macOS还是Windows系统,直接去`https://nodejs.org/`官网下载个安装包就可以了,直接下一步下一步即可,安装完成之后会包含npm工具。 ## 安装Docsify ```bash npm install -g docsify-cli docsify -v //查看版本 ``` ## 开始 ### 新建项目文件夹 接下来我们从零开始来新建一个本地的项目文件夹。 可以在任何地方新建,名字也可以随便命名,这里取名为`repository`,代表的意思是知识仓库 ### 初始化网站 进入到上述新建的项目文件夹`repository`,执行如下命令即可初始化网站,非常简单: ```bash docsify init ``` 初始化成功之后,命令行里也会输出对应初始化成功的打印信息。 ### 启动本地预览 ```bash docsify serve ``` ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232337249.png) 我们会发现docsify会帮我们在`localhost:3000`启动一个知识库网站。 然后在浏览器打开`http://localhost:3000`即可看见网站效果。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232337010.png) 当然,这时候的页面看起来非常简陋,几乎什么也没有。 接下来我们来看一看网站的文件结构,这个工具是如何做到这么快就可以启动一个网站的呢。 ## 项目结构 上文执行完`docsify init`命令成功初始化网站后,docsify会在项目文件夹里自动帮我们生成以下两个文件: - `index.html`:网站主入口文件和配置文件 - `README.md`:网站内容文件。支持Markdown格式,docsify可以帮我们把该Markdown源文件渲染成网页进行展示。 所以我们只需要直接编辑生成的这个README.md文件就能更新网站的内容。 ![image-20220223233926608](https://gitee.com/tianzhendong/img/raw/master//images/202202232339692.png) `coverpage`:封面 `navbar`:导航栏 `sidebar`:侧边栏 `logo.ico`:网页图标 ## 配置 https://blog.csdn.net/Lonelyooacz/article/details/103490545 ### 页面和URL路径 如果需要创建多个页面,或者需要多级路由的网站,在docsify里能很容易实现。 打比方说,你的目录结构如下: ``` . └── repository ├── README.md ├── test.md └── content ├── README.md └── bigdata.md ``` 那么对应的页面访问URL地址将是: ``` repository/README.md => http://127.0.0.1:3000/ repository/test.md => http://127.0.0.1:3000/test repository/content/README.md => http://127.0.0.1:3000/content/ repository/content/bigdata.md => http://127.0.0.1:3000/content/bigdata ``` 所以只需要在项目目录里添加其他`.md`文件,或者目录层级,即可形成多页面网站,非常简单易懂! ### 修改主题 docsify提供了多套主题可供使用。 直接修改`index.html`中引入的CSS文件即可修改网站主题。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232343575.png) 目前提供有好几套主题可供选择: ```html ``` ### 设置封面 像上文刚刚这样创建出来的网站其实是没有封面的,如果需要添加封面,可以通过在`index.html`中设置`coverpage`参数为`true`来实现: ```html coverpage: true ``` 这样既可开启封面功能。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342034.png) 封面功能开启之后,我们可以直接去项目文件夹里创建一个`_coverpage.md`文件来制作封面内容。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342150.png) 比如我们这地方,添加了`_coverpage.md`文件之后,在里面写上如下几段文字: ```markdown ![logo](https://cdn.jsdelivr.net/gh/justacoder99/r2coding@master/img/r2coding_logo_cover.7hb2s8l3eqk0.png) - 本站取名为r2coding,即Road To Coding,意为编程自学之路,是自学编程以来所用资源和分享内容的大聚合。旨在为编程自学者提供一系列清晰的学习路线、靠谱的资源、高效的工具、和务实的文章,方便自己也方便他人。**网站内容会持续保持更新,欢迎收藏品鉴!** ## 记住,一定要善用 `Ctrl+F` 哦! [**联系作者**](https://github.com/rd2coding/Road2Coding) [**开启阅读**](README.md) ``` 在网页上渲染之后,即可看到如下效果: ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342169.png) 所以其操作是非常简单的。 ### 设置导航栏 像上文刚刚这样创建出来的网站顶部右上角其实是没有导航栏的,如果需要添加导航栏,可以通过在`index.html`中设置`loadNavbar`参数来开启: ``` loadNavbar: true ``` ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232343460.png) 导航栏功能开启之后,我们可以直接去项目文件夹里创建一个`_navbar.md`文件来制作导航栏菜单内容。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342788.png) 比如我们这地方,添加了`_navbar.md`导航栏之后的效果大致如下: ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342908.png) ### 设置章鱼猫 可以通过在`index.html`中设置`repo`参数来开启网站右上角的章鱼猫链接的小图标功能 ``` repo: 'https://github.com/rd2coding/Road2Coding' ``` ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342609.png) 设置完成后的效果如下,还是很萌的,鼠标移到上面,小尾巴还能摇一摇。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342876.png) ### 设置logo 可以通过在`index.html`中设置`name`参数或者`logo`参数来开启网站侧边栏左上角的标题或者logo显示功能: ``` name: 'Road To Coding', logo: 'https://cdn.jsdelivr.net/gh/justacoder99/r2coding@master/img/r2coding_logo_sidebar.1na4hwjnopq8.png' ``` ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342324.png) 比如这地方设置了logo图片之后,效果大致如下: ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232342942.png) ### 设置tabs 在`index.html`中添加 docsify-tabs 插件。 ```html ``` 查看[选项](https://jhildenbiddle.github.io/docsify-tabs/#/?id=options)部分并根据需要进行配置。 ```html window.$docsify = { // ... tabs: { persist : true, // default sync : true, // default theme : 'classic', // default tabComments: true, // default tabHeadings: true // default } }; ``` 查看[自定义](https://jhildenbiddle.github.io/docsify-tabs/#/?id=customization)部分并根据需要设置主题属性。 ```html ``` 使用HTML 注释定义选项卡集`tabs:start`。`tabs:end` HTML 注释用于标记选项卡集的开始和结束。当 Markdown 在您的 docsify 站点(例如 GitHub、GitLab 等)之外呈现为 HTML 时,使用 HTML 注释可防止显示与选项卡相关的标记。 ```markdown ... ``` 使用**标题 + 粗体**标记定义选项卡集中的选项卡。 标题文本将用作选项卡标签,所有后续内容将与该选项卡相关联,直到下一个选项卡或`tab:end`评论的开始。使用标题 + 粗体标记允许使用标准标记定义选项卡,并确保选项卡内容在您的 docsify 站点(例如 GitHub、GitLab 等)之外呈现时显示带有标题。 ```markdown #### **English** Hello! #### **French** Bonjour! #### **Italian** Ciao! ``` #### **English** Hello! #### **French** Bonjour! #### **Italian** Ciao! 效果: ![image-20220224000446534](https://gitee.com/tianzhendong/img/raw/master//images/202202240004587.png) ### alert插件 https://github.com/fzankl/docsify-plugin-flexible-alerts ### 首页html文件 ```html Tian's Blog
🏃‍🏃‍🏃‍💨 加载中...
``` ## Nginx部署准备 对于这类网站的部署,我们当然可以部署到`GitHub Pages`服务或者`Gitee Pages`服务上去 也直接将其部署到云服务器上去。 ### 安装服务器软件 这里选用Nginx这个Web服务器来驱动网站,因为Nginx服务器除了本身非常轻量,稳定,不耗资源之外,而且性能还好,还特别能扛并发。 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232345781.png) - 首先准备一个`nginx-1.17.10.tar.gz`的安装包,我们将其直接上传到云服务器的`root`⽬录下 - 在`/usr/local/`下创建`nginx`⽂件夹并进⼊ ```shell cd /usr/local/ mkdir nginx cd nginx ``` - 将Nginx安装包解压到`/usr/local/nginx`中即可 ```shell tar zxvf /root/nginx-1.17.10.tar.gz -C ./ ``` 解压完之后,在`/usr/local/nginx`⽬录中会出现⼀个`nginx-1.17.10`的目录 - 预先安装额外的几个依赖 ```shell yum -y install pcre-devel yum -y install openssl openssl-devel ``` - 接下来编译安装Nginx即可 ```shell cd nginx-1.17.10 ./configure make && make install ``` 安装完成后, Nginx的可执行文件位置位于 ```shell /usr/local/nginx/sbin/nginx ``` 其配置⽂件则位于: ``` /usr/local/nginx/conf/nginx.conf ``` - 启动Nginx 直接执⾏如下命令即可 ```shell /usr/local/nginx/sbin/nginx ``` - 如果想停⽌Nginx服务,可执⾏: ```shell /usr/local/nginx/sbin/nginx -s stop ``` - 如果修改了配置⽂件后想重新加载Nginx,可执⾏: ```shell /usr/local/nginx/sbin/nginx -s reload ``` ### 上传网站到云服务器 比如,我们可以直接在`/usr/local/nginx/`目录中创建一个`www`文件夹,用于存放我们本地的项目文件夹。 然后我们可以直接将本地的项目文件夹`repository`上传到`www`目录里即可 ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232345234.png) ### Nginx配置和访问 接下来我们打开路径`/usr/local/nginx/conf/nginx.conf`下的Nginx服务器配置文件,修改其中最关键的一个`location /`下的`root`目录配置为项目文件夹的路径即可 ```shell location / { root /usr/local/nginx/www/repository; index index.html index.htm; } ``` ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232345404.png) 然后我们直接在浏览器中访问云服务器的公网IP,就可以访问该知识库网站了: ![图片](https://gitee.com/tianzhendong/img/raw/master//images/202202232345961.jpeg) 最后再将域名和这个IP一绑定,就OK了 ## nginx服务器添加密码访问 ### 通过htpasswd命令生成用户名及对应密码数据库文件 ```shell htpasswd -c /htpasswd/passwd.db test ``` 说明:此命令是使用Crypt算法生产一个加密文件passwd.db。 - test是用户名 - /htpasswd/passwd.db 是密码文件存放地址 - htpasswd apache的生产密码的插件 把 passwd.db文件设置为777权限 ```shell chmod 777 文件名 ``` ### nginx域名配置文件修改 ```shell location / { root html; index index.html index.htm index index.jpg; auth_basic 'Restricted'; # 认证名称,随意填写 auth_basic_user_file /htpasswd/passwd.db; # 认证的密码文件,需要生产。 } ``` 如果没有安装apache,可以安装如下软件,就有htpasswd这个命令了 ```shell yum -y install httpd-tools yum -y install httpd #安装httpd which htpasswd #查看是否安装 rpm -qf /usr/bin/htpasswd #查看是否安装 htpasswd -cb /usr/local/nginx/conf/htpasswd ceshi 123789 #生成密码文件 chmod 400 /usr/local/nginx/conf/htpasswd #为了安全设置文件权限 ``` 然后重启nginx服务器即可实现nginx服务器添加密码 ```shell #3、检查语法并重启 /usr/local/nginx/sbin/nginx -t /usr/local/nginx/sbin/nginx -s reload ``` ## 定时git pull和重启nginx 前提:www中已经设置了git仓库,这里为www下的NoteBooks文件夹 - 拉取最新代码 ```shell git pull ``` - 在NoteBooks下新建自动化脚本 ```shell vim 111gitpull.sh ``` - 输入: ```shell #!/bin/bash cd /usr/local/nginx/www/NoteBooks git pull /usr/local/nginx/sbin/nginx -s reload ``` - 设置自动启动,这里每30分钟拉取一次 进入root用户 编辑cron脚本 ```shell crontab -e ``` 输入: ```shell */30 * * * * /usr/local/nginx/www/NoteBooks/111gitpull.sh ``` - 将服务自动启动 ```shell vim /etc/rc.d/rc.local ``` 这个脚本的末尾加上: ```shell /sbin/service crond start ``` ## 配置Gittalk ### 第一步:创建OAuth Application 这里假设你的[github](https://so.csdn.net/so/search?q=github&spm=1001.2101.3001.7020)仓库已经创建好,docsify也已经安装使用中。申请授权地址[点击这里](https://github.com/settings/applications/new) 几个参数解释: - Application name:项目名,随便填 - Homepage URL:博客地址,也就是要访问的地址,我的是https://waldeincheng.github.io/Python-Notes - Application description:应用描述,随便填,我的是waldeincheng’s blog - Authorization callback URL:可以指向新的URL,或者跟上面的Homepage URL一样即可 完成后会生成相应的`clientID`和`clientSecret` ### 第二步:配置gittalk docsify下有一个index.html配置文件,打开,添加上 ``` ``` 配置: - , css文件放到index.html里的`\`标签里 - `clientID`:刚刚获取的ID - `clientSecret`:刚刚获取的授权密码 - `repo`:仓库名 - `owner`:github用户名 - `admin`:[‘github用户名’] 保存修改,git提交上去就行了,显示格式如图 ## Windows自动启动Docsify 使用 `.bat` 的话,会显示一个短暂的黑窗口所以要想后台静默运行,需要用到 `.vbs` 脚本 ### 创建vbs脚本 在docsify目录下新建一个vbs文件,内容如下 ```vbscript set ws=WScript.CreateObject("WScript.Shell") ws.Run "docsify serve",0 ``` 该脚本含义为在当前目录下执行 `docsify serve` 命令 ### 开启启动 windows 开机会自动调用下列两个文件夹下的可执行文件 用户目录的自启文件夹: ```text C:\Users\用户名\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup ``` > 注意用户名,每个用户都不相同 所有用户都会执行的全局自启文件夹 ```text C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp ``` 在脚本上右键创建快捷方式,然后将这个快捷方式放到上述两个文件夹任意一个即可