使用 docsify 快速搭建文档类型网站

2023-6-17 12 6/17
使用 docsify 快速搭建文档类型网站

快速开始

  1. 全局安装 docsify-cli
npm i docsify-cli -g
  1. 初始化项目
docsify init docs

该命令会在当前目录下新建 docs 目录,并在其中初始化以下文件:

使用 docsify 快速搭建文档类型网站
  1. 本地预览
docsify serve docs

以上命令会开始实时的预览,浏览器中输入 http://localhost:3000 就可以看到效果。试试修改目录下 README.md 的内容,修改内容将实时更新。

使用 docsify 快速搭建文档类型网站

个性定制

docsify 提供了很方便的配置来进行个性化定制。下面2张截图展示了我们接下来的配置会达到的效果。

使用 docsify 快速搭建文档类型网站

使用 docsify 快速搭建文档类型网站

配置项

配置在 index.html 文件的 window.$docsify 中。多数的个性定制都是配置结合其他一同来实现的。

<script>
  window.$docsify = {
    repo'docsifyjs/docsify',
    maxLevel3,
    coverpagetrue,
  };
</script>

封面

在配置项中,设置 coverpage: true,开启封面渲染功能。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。该文件的内容会被用来生成封面。

<script>
  window.$docsify = {
    coverpagetrue,
  };
</script>
![logo](https://docsify.js.org/_media/icon.svg)

# craft4j

> Java 后端开发及架构都应该知道的干货文章合集。

[GitHub](https://github.com/fatfoo/craft4j.git)
[Get Started](#craft4j)

<!-- 颜色作为自定义背景 -->
<!-- ![color](#ffff88) -->

<!-- 图片作为自定义背景 -->
![](_media/bg.jpg)

通过 markdown 语法,我们也可以使用颜色或者图片作为自定义背景。

导航栏

在配置项中,设置 loadNavbar: true,可以自定义导航栏,配合 _navbar.md 文件进行内容的渲染。

<script>
  window.$docsify = {
    loadNavbartrue
  }
</script>
<!-- _navbar.md -->
[ron-point](https://github.com/fatfoo/ron-point.git)
[精进Java](http://img.uprogrammer.cn/static/20200829154605.gif)

侧边栏

在配置项中,设置 loadSidebar: true,可以开启侧边栏。配合 _sidebar.md 文件进行内容的渲染。

<script>
  window.$docsify = {
    loadSidebartrue
  }
</script>
<!-- _sidebar.md -->
SSM 实战
  - [利用 Bean Validation 来简化接口请求参数校验](ssm-in-action/利用%20Bean%20Validation%20来简化接口请求参数校验.md)
  - [Spring Boot 集成 JWT 实现用户登录认证](ssm-in-action/Spring%20Boot%20集成%20JWT%20实现用户登录认证.md)
  - [一行代码就可以实现 Jwt 登录认证,爽呆了](ssm-in-action/一行代码就可以实现%20Jwt%20登录认证,爽呆了.md)
工具
  - [常用 Git 命令使用教程](toolkit/常用%20Git%20命令使用教程.md)
  - [入行 10 年总结,作为开发必须知道的 Maven 实用技巧](toolkit/入行%2010%20年总结,作为开发必须知道的%20Maven%20实用技巧.md)

以上会生成带目录的侧边栏。

主题

docsify 提供了多种主题,还有其他第三方贡献的主体,通过引入 css 的方式就可以方便的切换主题。如下使用了 vue 主题,想切换主题,只要放开对应 css 的注释。

<head>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
  <!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css"> -->
  <!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css"> -->
  <!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css"> -->
  <!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css"> -->
  <!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css"> -->
  <!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"> -->
  <!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"> -->
</head>

插件

docsify 也提供了许多开箱即用的插件。以下讲讲 craft4j 中用到的 emoji 插件、搜索插件、图片缩放插件、分页导航插件。

emoji 插件
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

要正确解析 emoji 字符串,在 index.html 中引入该插件即可。

全文搜索插件

全文搜索插件会根据当前页面上的超链接获取文档内容,在 localStorage 内建立文档索引。

<!-- 配置项中对全文搜索进行配置 -->

<script>
window.$docsify = {
// 全文检索完整配置参数
search: {
maxAge86400000// 过期时间,单位毫秒,默认一天
paths: [], // or 'auto'
placeholder'搜索',
noData'啦啦啦...你找不到我~',
// 搜索标题的最大层级, 1 - 6
depth4,
hideOtherSidebarContentfalse// 是否隐藏其他侧边栏内容
}
}
</script>

<!-- 引入全文搜索插件 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

图片缩放插件
<!-- 引入图片缩放插件 -->

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

分页导航插件
<!-- 引入分页导航插件 -->

<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>

代码高亮

docsify 内置的代码高亮工具是 Prism。除了 Prism 默认支持的语言外,其他添加额外的语法支持需要通过CDN添加相应的语法文件 :

<!-- java 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
<!-- bash 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<!-- properties 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-properties.min.js"></script>
<!-- yaml 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>

总结

docsify 提供了非常强大的功能来快速搭建一个高颜值的文档类型网站。只需要编写 markdown 格式的文档就可以生成网站内容。其实很适合用来管理个人或者团队的知识文档。

以上讲到了快速搭建 docsify 站点的基础配置,具体实例见 http://craft4j.uprogrammer.cn/(点击阅读原文直达),docsify 更多的配置可以查看官方文档 https://docsify.js.org/#/zh-cn/。

- THE END -

非特殊说明,本博所有文章均为博主原创。

共有 0 条评论