Loading [MathJax]/jax/output/CommonHTML/config.js
首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >专栏 >【云+社区年度征文】用上神器docsify 靠MarkDown 就能写自己的网站

【云+社区年度征文】用上神器docsify 靠MarkDown 就能写自己的网站

原创
作者头像
韩旭051
修改于 2020-12-03 09:27:37
修改于 2020-12-03 09:27:37
1.5K0
举报
文章被收录于专栏:刷题笔记刷题笔记

搭建个人网站

动态博客

  之前尝试过搭建自己的博客,有知名的 PHP 动态博客 WordPress 托管到我自己的服务器上,后面又自己开发了一款 SpringBoot 和 VUE 的前后端分离博客,这个用来学习还是不错的,但是终归需要一个服务器来跑这个,而且需要数据库 MySQL 之类的 关系型数据库 用来存储数据,用有逼格的专业话讲就是 用关系型数据库将数据持久化。

静态博客

hexo

  除了动态的博客,还体验过静态的博客,之前一直在用 hexo 这款静态博客,

hexo是用 markdown 作为源文件,但是需要本地通过 hexo 程序进行渲染,转换成 HTML 文件转成静态页面,再由 web服务器 进行托管。放在 github 码云 gitee 都可以 使用静态页面托管。

很是方便而且免费,不需要再自己整一个服务器,但是 hexo 还是有点麻烦的,需要本地有 node 环境才可以编译。

当然,万能的 Github 后面有了 特别特别好用的 Github Action 可以白嫖资本主义的服务器,用微软家的云服务器编译成 HTML 静态页面,再自动托管到 仓库里。

这个也蛮方便的,解决了上面的问题,不过配置这个 Github Action 就挺麻烦的,需要很多安全验证,感兴趣的话,我后面还是可以讲一下这个配置方案,不过对于新手来说真的是麻烦很多。

docsify

知道前两天 我发现了一个更方便的文档生成工具 docsify (一个神奇的文档生成器 A magical documentation generator.)

使用了一下才发现 这个比 hexo 要方便很多,更适合小白来使用。

docsify 效果

docsify 样例

他们的官网 就是用这个技术写的,打开看一下 蛮不错的,还有一个研究生在读的大佬的笔记 cs-wiki 也是使用的这个技术完成的搭建。

  • docsify 是专业用来写文档的,配合 github 的在线托管,特别方便就可以使用

左边可以显示目录 和 每篇文档 自动生成小标题,文章内容也是解析好的 markdown 文件

与其我干巴巴的说效果,不如大家点进去体验一下

与其看着这两个样例不如自己也部署好了,亲自感受下自己的站点。

废话不说了,直接上安装教程

小白无 npm 环境 直接硬写版

手动 创建一个 html 文件 index.html

假设写在空文件夹 /doc 里面吧

写入这些代码

代码语言:txt
AI代码解释
复制
<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

这就好了

是不是不敢相信

不过真的是这样

环境安装就是这么 的简单

按照官网文档的教程,如果你有 Python 环境 直接跑一个 web 服务就能预览了

cd docs && python -m SimpleHTTPServer 3000

然后浏览器 访问300端口 就 OK啦

localhost:3000

或者

127.0.0.1:3000

这就是一个空网页

想添加内容 就写一个 markdown

默认的主页叫做 readme.md

所以我们 先创建这个 文档

写一些内容 ,保存后 刷新网页

就会可以实时的预览了。

非小白 npm 用户

  1. 全局安装 docsify-cli 工具 npm i docsify-cli -g
  2. 如果想在项目的 ./docs 目录里写文档,直接通过 init 初始化项目。 docsify init ./docs
  3. 直接编辑 docs/README.md 就能更新文档内容
  4. 预览效果 docsify serve docs

进阶使用内容

多页文档

官方文档

写了一两篇文章 发现 readme.md 这个文件越来越长,真的很难顶,不可能一个博客要是二三十偏文章 全都蜗居在一个 markdown 里面吧。想想就来气,在宿舍不能上床下桌 不能四人间 不能双人间 不能独立卫浴 毕业了也没钱租个大平层,博客也要蜗居在一个文件里? 想想就气的要死

查了查文档 发现 官方早就考虑到了这个问题,多页文档,就能很好的解决这个问题。

查官网是这么说的

如果需要创建多个页面,或者需要多级路由的网站,在 docsify 里也能很容易的实现。例如创建一个 guide.md 文件,那么对应的路由就是 /#/guide

假设你的目录结构如下:

代码语言:txt
AI代码解释
复制
.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面将是

代码语言:txt
AI代码解释
复制
docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/guide
docs/zh-cn/README.md  => http://domain.com/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide

说人话 就是 除了readme.md 这个默认主页,别的文章你就随便起一个别的 markdown 的名字就行,访问这个页面就在地址栏在之前的域名之后加入相对位置就行,学过 HTML 的老同志都懂

侧边栏定制显示层数

之前我说了 侧边栏 可以自动生成 根据你 markdown 的 #1 #2 #3 #4 #5 #6 如果全部生成就是六层

写的时候很顺手,但是渲染出来前端,就像一个手风琴一样

六层目录,全部在侧边栏展示出来,太丑了,官方经过多次的产品迭代,也早就知道我会有这种强迫症问题

可以设置 subMaxLevel 配置显示的层数 1 就是只显示#1 以此类推,一般渲染到 #3 就好了,大标题 小标题 和各部分的内容 应该就够了

自定义侧边栏同时也可以开启目录功能。设置 subMaxLevel 配置项,具体介绍见 配置项#sub-max-level。

代码语言:txt
AI代码解释
复制
<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 2
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

搜索框

用时间长了 博客里记录的东西 也多了,总不可能一直用 Ctrl + F 来搜索文档吧

看看有没有搜索功能,我用 Ctrl+F 这种上古搜索方案 找了一下没找到

我灵机一动 一动动,一动不动,发现样例的左上角 不就是一个 搜索框吗? 既然样例有,那么 我也能用

直接搜到了 Search 插件

一句话说 直接 在 最开始的 本地 html 文件里 的

代码语言:txt
AI代码解释
复制
window.$docsify= {

}

加入 search: 'auto', // 默认值 就够了

我觉得 默认的 就挺好的

代码语言:txt
AI代码解释
复制
window.$docsify= {
	search: 'auto'
}

官方文档 给出了 更完整的配置教程,能看懂就OK

全文搜索插件会根据当前页面上的超链接获取文档内容,在 localStorage 内建立文档索引。默认过期时间为一天,当然我们可以自己指定需要缓存的文件列表或者配置过期时间。

代码语言:txt
AI代码解释
复制
<script>
  window.$docsify = {
    search: 'auto', // 默认值

    search : [
      '/',            // => /README.md
      '/guide',       // => /guide.md
      '/get-started', // => /get-started.md
      '/zh-cn/',      // => /zh-cn/README.md
    ],

    // 完整配置参数
    search: {
      maxAge: 86400000, // 过期时间,单位毫秒,默认一天
      paths: [], // or 'auto'
      placeholder: 'Type to search',

      // 支持本地化
      placeholder: {
        '/zh-cn/': '搜索',
        '/': 'Type to search'
      },

      noData: 'No Results!',

      // 支持本地化
      noData: {
        '/zh-cn/': '找不到结果',
        '/': 'No Results'
      },

      // 搜索标题的最大层级, 1 - 6
      depth: 2,

      hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容

      // 避免搜索索引冲突
      // 同一域下的多个网站之间
      namespace: 'website-1',

      // 使用不同的索引作为路径前缀(namespaces)
      // 注意:仅适用于 paths: 'auto' 模式
      //
      // 初始化索引时,我们从侧边栏查找第一个路径
      // 如果它与列表中的前缀匹配,我们将切换到相应的索引
      pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],

      // 您可以提供一个正则表达式来匹配前缀。在这种情况下,
      // 匹配到的字符串将被用来识别索引
      pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/
    }
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

部署到 github page 和 gitee page 服务

最后也是最重要的就是 怎么 部署到 github 上吧

  1. 新建一个仓库 一定要 public 名字无所谓 (后面 访问的链接 就会是 你的名字.github.io/仓库名) 比如我这个就是 HANXU2018.github.io/docs 创建点那个绿色的大按钮 这个就不用我教了吧
  1. 仓库下载到本地

我就用 github Desktop 打开这个仓库了

我把他克隆到本地了

  1. 把刚才写好的 docs 文件夹放进去
  1. 把仓库提交到 github 上

Git 的使用教程 还有 Github Desktop 的教程 由于篇幅原因 我就不教了

挖个坑 后面有机会就写 哈哈

  1. 回到 Github 刷新 可以看到 东西传上去了

但是现在还不能访问,因为我们还没有配置 github page 静态托管 服务 还差最后 一步。

进入仓库配置页面 Settings

往下拉找到 Github Page 选择 Branch 为 master

文件夹路径 默认为 ROOT

因为咱们访问的是 index.html 我放在 docs 文件夹里面了,所以要把 root 改成 /docs

最后 Save 保存 别忘了哦

  1. 访问 github.io 最后 访问我 在第一步里面说的 网址 浏览器访问就可以 看到 最后的效果了

访问的链接 就会是 你的名字.github.io/仓库名

比如我这个就是 HANXU2018.github.io/docs

见证奇迹的时刻

最后 BB 两句

总算讲完了,我写的也不是很好,我才刚看了两天这个工具,准备作为自己的笔记本使用

以后 有啥 要更新的 更好的功能,我还会再继续更新

ヾ( ̄▽ ̄)Bye~Bye~再见~

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
暂无评论
推荐阅读
编辑精选文章
换一批
Visual Studio Code 快捷键大全(Windows)
Visual Studio Code 是一款优秀的编辑器,非常适合编写 TS 以及 React 。最近在学习 AngularJs 2,开始使用 VSCode,特意整理翻译了一下官网的快捷键。因为已经习惯了 Sublime 的快捷键,更换到 VSCode 有些不适应,尤其是 Emmet 的使用。 通用 Ctrl+Shift+P, F1 打开命令面板 Ctrl+P 快速打开文件 Ctrl+Shift+N 打开新窗口/实例 Ctrl+Shift+W 关闭窗口/实例 基础编辑
叙帝利
2018/01/17
32.3K1
Idea 常用快捷键
———–自动代码——– 常用的有fori/sout/psvm+Tab即可生成循环、System.out、main方法等boilerplate样板代码 例如要输入for(User user : users)只需输入user.for+Tab 再比如,要输入Date birthday = user.getBirthday();只需输入user.getBirthday().var+Tab即可。代码标签输入完成后,按Tab,生成代码。 Ctrl+Alt+O 优化导入的类和包 Alt+Insert 生成
用户1212940
2018/01/23
1.2K0
IntelliJ Idea 常用快捷键 列表(实战终极总结!!!!)
1. -----------自动代码--------  常用的有fori/sout/psvm+Tab即可生成循环、System.out、main方法等boilerplate样板代码  例如要输入for(User user : users)只需输入user.for+Tab 
MonroeCode
2018/01/09
1.9K0
IntelliJ Idea 常用快捷键 列表(实战终极总结!!!!)
pycharm快捷键
作者:lslx518 来源:CSDN 原文:https://blog.csdn.net/lslx518/article/details/81483089 版权声明:本文为博主原创文章,转载请附上博文链接!
kalifa_lau
2019/04/18
1K0
IntelliJ IDEA常用快捷键列表
对于刚转到IDEA的,可能需要熟悉下IDEA的快捷键。当然,作为当下最好用的IDE,也支持设置其他IDE工具的快捷键!
4xx.me
2022/06/09
2840
IntelliJ IDEA 2019 快捷键终极大全,速度收藏!
常用的有fori/sout/psvm+Tab即可生成循环、System.out、main方法等boilerplate样板代码 。
芋道源码
2019/08/06
1.1K0
微信小程序——常用快捷键【四】
思索
2024/08/16
2360
微信小程序——常用快捷键【四】
Intellij IDEA 最全实用快捷键整理(长期更新)[通俗易懂]
—————————————– -Xms2048m -Xmx2048m -XX:MaxPermSize=512m -ea -server -Dsun.awt.keepWorkingSetOnMinimize=true
全栈程序员站长
2022/08/26
1.7K0
IntelliJ IDEA常用快捷键汇总
转载自https://blog.csdn.net/wei83523408/article/details/60472168
allsmallpig
2021/02/25
7630
IntelliJ IDEA 快捷键大全 | 终极版
上周大雄给大家分享了一些只要你用上,就可以丢掉鼠标的Eclipse快捷键。自从那篇文章一推送,好家伙,IDEA的拥护者全都涌出来了。
老九君
2020/04/28
8460
IDEA和Eclipse常用快捷键
下面的快捷键是重构里面常用的,本人就自己喜欢且常用的整理一下(注:一般重构的快捷键都是Alt+Shift开头的了)
QAIU
2023/03/14
1.6K0
Android 开发快捷键,idea 开发快捷键
android studio 怎样用if else 抱起来一段代码: Ctrl + Alt + T
zhangjiqun
2024/12/16
2350
Android 开发快捷键,idea 开发快捷键
IDEA快捷键部分整理
这篇文章最后修改于 2022-07-01 日,距今已有 144 天,请注意甄别内容是否已经过时!
羽翼博客
2022/11/28
7500
VS code常用的快捷键
在前端的开发过程中,如果有一个比较好的开发工具,配合一些常用的快捷键,开发效率将大大提升,正所谓工具善其事必先利其器。前端推荐使用编辑器VS code,用过HB-X,ST3,Webstorm等编译器之后就会发现,前端编辑器最屌的还是VS code。
孙叫兽
2021/12/20
7640
VS code常用的快捷键
IDEA快捷键
IDEA的快捷键: Alt+回车 导入包,自动修正 Ctrl+N 查找类 Ctrl+Shift+N 查找文件 Ctrl+Alt+L 格式化代码 Ctrl+Alt+O 优化导入的类和包 Alt+Insert 生成代码(如get,set方法,构造函数等) Ctrl+E或者Alt+Shift+C 最近更改的代码 Ctrl+R 替换文本 Ctrl+F 查找文本 Ctrl+Shift+Space 自动补全代码 Ctrl+空格 代码提示 Ctrl+Alt+Space 类名或接口名提示 Ctrl+P 方法参数提示 Ctrl+Shift+Alt+N 查找类中的方法或变量 Alt+Shift+C 对比最近修改的代码
且陶陶
2023/04/12
4550
IDEA常用设置及推荐插件
一个没有getter,setter方法的类通过添加@Getter和@Setter注解拥有了getter,setter方法。
macrozheng
2019/07/22
9270
IDEA常用设置及推荐插件
IDEA快捷键
Editing方面: Ctrl+Space: Basic code completion(the name of any class,method or variable) 就是一些基本的实现,象你输入了要调用的某个类或者方法或者变量的前几个字母,想不起后面的该怎样拼写了,就可以使用这个快捷键。它会自动把系统中的n个匹配项给你罗列出来的。 Ctrl+Shift+Space: Smart code completion (filter the list of methods and variables by
二十三年蝉
2018/02/28
9180
idea 凯哥常用快捷键
Ctrl+Alt+F12    显示当前文件的路径,并可以方便的将相关父路径打开    
凯哥Java
2019/06/28
5670
史上最全的IntelliJIdea快捷键
I Teach You 我教你
2023/07/18
4420
pycharm 掌握这些快捷键,你就是大神!!
发布者:全栈程序员栈长,转载请注明出处:https://javaforall.cn/174586.html原文链接:https://javaforall.cn
全栈程序员站长
2022/09/27
3880
相关推荐
Visual Studio Code 快捷键大全(Windows)
更多 >
交个朋友
加入腾讯云官网粉丝站
蹲全网底价单品 享第一手活动信息
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档